==================
pytest-repo-health
==================
.. image:: https://img.shields.io/pypi/v/pytest-repo-health.svg
:target: https://pypi.org/project/pytest-repo-health
:alt: PyPI version
.. image:: https://img.shields.io/pypi/pyversions/pytest-repo-health.svg
:target: https://pypi.org/project/pytest-repo-health
:alt: Python versions
.. image:: https://github.com/openedx/pytest-repo-health/workflows/Python%20CI/badge.svg?branch=master
:target: https://github.com/openedx/pytest-repo-health/actions?query=workflow%3A%22Python+CI%22
:alt: CI
.. image:: https://ci.appveyor.com/api/projects/status/github/edx/pytest-repo-health?branch=master
:target: https://ci.appveyor.com/project/edx/pytest-repo-health/branch/master
:alt: See Build Status on AppVeyor
----
pytest-repo-health adapts pytest to run repo health checks as described in
`edx-repo-health`_. Similar to how pytest runs a number of test functions,
pytest-repo-health runs a number of repo check functions.
It inspects a code repository and outputs a report with info on whether the repository
follows standards as defined by checks. It's
a good complement for a `cookiecutter`_; the cookiecutter provides a good
template for starting a repository with current best practices, and pytest-repo-health
helps it keep up with those practices as they evolve over time.
This `pytest`_ plugin was generated with `Cookiecutter`_ along
with `@hackebrot`_'s `cookiecutter-pytest-plugin`_ template.
Installation
------------
For now, you need to git clone pytest-repo-health from: ``git@github.com:edx/pytest-repo-health.git``
You can install by running ``make requirements`` and then `pip install -e .`
in a Python 3.5+ virtualenv.
Usage
-----
Once installed, use this command to run checks::
$ pytest -c <() --noconftest --repo-health --repo-health-path <path to dir with checks> --repo-path <path to repo to check>
The -c and --noconftest options are needed to stop pytest from incorrectly reading configuration files in the repo you are checking::
-c file: load configuration from `file` instead of trying to locate one of the implicit configuration files. Helpful if invocation dir defines "add-opts" in one of its files.
--noconftest: Don't load any conftest.py files. Helpful in case invocation dir/repository has conftest files that change configurations or cause pytest to run unnecessary code.
Other pytest options can be used. For example, `-k` is helpful for running a subset of checks.
The "all_results" dictionary will be written as YAML to repo_health.yaml.
Adding Custom Checks
--------------------
Any repo can host repo checks. They must be in a directory named "repo_health".
If you would like to add custom checks for your own repo, create a dir named "repo_health" and place
modules with checks inside of it.
Checks naming convention:
- python_functions = "check_*"
- python_files = "check_*.py"
Checks Discovery
----------------
Pytest will look for checks in these directories, though it will only successfully run checks in the first place it finds them:
- Dir of pytest invocation(so current dir)
- Dir where pytest-repo-health is installed
- Dir specified by --repo-health-path flag in pytest invocation
Args
----
Arguments added by plugin::
--repo-health: this arg needs to be present for plugin to do anything
--repo-path <dir path> : the path to dir on which to perform checks. If not preset, checks will be performed on current dir
--repo-health-path <dir path>: path to where checks are located. If not preset, plugin will look for checks in current repo
--output-path <file path> : path to where to save resulting checks report
--repo-health-metadata: if this is present, plugin will collect metadata(docs) from checks. You can give filename after flag(if no filename, it defaults to metadata.yaml)
Future improvements
-------------------
- Currently, the checks do not throw any kind of warning or error if check does not pass.
- Documenting standard reqs/checks in each check better.
- Create tests for this plugin(currently, you can run these checks on this repo, but no automated method for it)
Contributing
------------
Contributions are very welcome. Tests can be run with `tox`_, please ensure
the coverage at least stays the same before you submit a pull request.
License
-------
The code in this repository is licensed under the Apache Software License 2.0 unless
otherwise noted.
Please see ``LICENSE.txt`` for details.
How To Contribute
-----------------
Contributions are very welcome.
Please read `How To Contribute <https://github.com/openedx/edx-platform/blob/master/CONTRIBUTING.rst>`_ for details.
Even though they were written with ``edx-platform`` in mind, the guidelines
should be followed for Open edX code in general.
The pull request description template should be automatically applied if you are creating a pull request from GitHub. Otherwise you
can find it it at `PULL_REQUEST_TEMPLATE.md <https://github.com/openedx/pytest-repo-health/blob/master/.github/PULL_REQUEST_TEMPLATE.md>`_
Issues
------
The issue report template should be automatically applied if you are creating an issue on GitHub as well. Otherwise you
can find it at `ISSUE_TEMPLATE.md <https://github.com/openedx/pytest-repo-health/blob/master/.github/ISSUE_TEMPLATE.md>`_
If you encounter any problems, please `file an issue`_ along with a detailed description.
Reporting Security Issues
-------------------------
Please do not report security issues in public. Please email security@edx.org.
Getting Help
------------
Have a question about this repository, or about Open edX in general? Please
refer to this `list of resources`_ if you need any assistance.
.. _list of resources: https://open.edx.org/getting-help
.. _edx-repo-health: https://github.com/openedx/edx-repo-health
.. _`Cookiecutter`: https://github.com/audreyr/cookiecutter
.. _`@hackebrot`: https://github.com/hackebrot
.. _`BSD-3`: http://opensource.org/licenses/BSD-3-Clause
.. _`GNU GPL v3.0`: http://www.gnu.org/licenses/gpl-3.0.txt
.. _`Apache Software License 2.0`: http://www.apache.org/licenses/LICENSE-2.0
.. _`cookiecutter-pytest-plugin`: https://github.com/pytest-dev/cookiecutter-pytest-plugin
.. _`file an issue`: https://github.com/openedx/pytest-repo-health/issues
.. _`pytest`: https://github.com/pytest-dev/pytest
.. _`tox`: https://tox.readthedocs.io/en/latest/
.. _`pip`: https://pypi.org/project/pip/
.. _`PyPI`: https://pypi.org/project
Raw data
{
"_id": null,
"home_page": "https://github.com/edX/pytest-repo-health",
"name": "pytest-repo-health",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "pytest edx",
"author": "edX",
"author_email": "oscm@edx.org",
"download_url": "https://files.pythonhosted.org/packages/fb/a0/c74a8383810faf5d8c1a052b58544aac4fc08f977a8dc87280587c79155f/pytest-repo-health-3.0.2.tar.gz",
"platform": null,
"description": "==================\npytest-repo-health\n==================\n\n\n.. image:: https://img.shields.io/pypi/v/pytest-repo-health.svg\n :target: https://pypi.org/project/pytest-repo-health\n :alt: PyPI version\n\n.. image:: https://img.shields.io/pypi/pyversions/pytest-repo-health.svg\n :target: https://pypi.org/project/pytest-repo-health\n :alt: Python versions\n\n.. image:: https://github.com/openedx/pytest-repo-health/workflows/Python%20CI/badge.svg?branch=master\n :target: https://github.com/openedx/pytest-repo-health/actions?query=workflow%3A%22Python+CI%22\n :alt: CI\n\n.. image:: https://ci.appveyor.com/api/projects/status/github/edx/pytest-repo-health?branch=master\n :target: https://ci.appveyor.com/project/edx/pytest-repo-health/branch/master\n :alt: See Build Status on AppVeyor\n\n----\n\npytest-repo-health adapts pytest to run repo health checks as described in\n`edx-repo-health`_. Similar to how pytest runs a number of test functions,\npytest-repo-health runs a number of repo check functions.\n\nIt inspects a code repository and outputs a report with info on whether the repository\nfollows standards as defined by checks. It's\na good complement for a `cookiecutter`_; the cookiecutter provides a good\ntemplate for starting a repository with current best practices, and pytest-repo-health\nhelps it keep up with those practices as they evolve over time.\n\nThis `pytest`_ plugin was generated with `Cookiecutter`_ along\nwith `@hackebrot`_'s `cookiecutter-pytest-plugin`_ template.\n\nInstallation\n------------\n\nFor now, you need to git clone pytest-repo-health from: ``git@github.com:edx/pytest-repo-health.git``\nYou can install by running ``make requirements`` and then `pip install -e .`\nin a Python 3.5+ virtualenv.\n\n\nUsage\n-----\n\nOnce installed, use this command to run checks::\n\n $ pytest -c <() --noconftest --repo-health --repo-health-path <path to dir with checks> --repo-path <path to repo to check>\n\nThe -c and --noconftest options are needed to stop pytest from incorrectly reading configuration files in the repo you are checking::\n\n -c file: load configuration from `file` instead of trying to locate one of the implicit configuration files. Helpful if invocation dir defines \"add-opts\" in one of its files.\n\n --noconftest: Don't load any conftest.py files. Helpful in case invocation dir/repository has conftest files that change configurations or cause pytest to run unnecessary code.\n\nOther pytest options can be used. For example, `-k` is helpful for running a subset of checks.\n\nThe \"all_results\" dictionary will be written as YAML to repo_health.yaml.\n\n\nAdding Custom Checks\n--------------------\n\nAny repo can host repo checks. They must be in a directory named \"repo_health\".\n\nIf you would like to add custom checks for your own repo, create a dir named \"repo_health\" and place\nmodules with checks inside of it.\n\nChecks naming convention:\n\n- python_functions = \"check_*\"\n- python_files = \"check_*.py\"\n\nChecks Discovery\n----------------\n\nPytest will look for checks in these directories, though it will only successfully run checks in the first place it finds them:\n- Dir of pytest invocation(so current dir)\n- Dir where pytest-repo-health is installed\n- Dir specified by --repo-health-path flag in pytest invocation\n\n\nArgs\n----\n\nArguments added by plugin::\n\n --repo-health: this arg needs to be present for plugin to do anything\n\n --repo-path <dir path> : the path to dir on which to perform checks. If not preset, checks will be performed on current dir\n\n --repo-health-path <dir path>: path to where checks are located. If not preset, plugin will look for checks in current repo\n\n --output-path <file path> : path to where to save resulting checks report\n\n --repo-health-metadata: if this is present, plugin will collect metadata(docs) from checks. You can give filename after flag(if no filename, it defaults to metadata.yaml)\n\nFuture improvements\n-------------------\n\n- Currently, the checks do not throw any kind of warning or error if check does not pass.\n- Documenting standard reqs/checks in each check better.\n- Create tests for this plugin(currently, you can run these checks on this repo, but no automated method for it)\n\nContributing\n------------\n\nContributions are very welcome. Tests can be run with `tox`_, please ensure\nthe coverage at least stays the same before you submit a pull request.\n\nLicense\n-------\n\nThe code in this repository is licensed under the Apache Software License 2.0 unless\notherwise noted.\n\nPlease see ``LICENSE.txt`` for details.\n\nHow To Contribute\n-----------------\n\nContributions are very welcome.\n\nPlease read `How To Contribute <https://github.com/openedx/edx-platform/blob/master/CONTRIBUTING.rst>`_ for details.\n\nEven though they were written with ``edx-platform`` in mind, the guidelines\nshould be followed for Open edX code in general.\n\nThe pull request description template should be automatically applied if you are creating a pull request from GitHub. Otherwise you\ncan find it it at `PULL_REQUEST_TEMPLATE.md <https://github.com/openedx/pytest-repo-health/blob/master/.github/PULL_REQUEST_TEMPLATE.md>`_\n\nIssues\n------\n\nThe issue report template should be automatically applied if you are creating an issue on GitHub as well. Otherwise you\ncan find it at `ISSUE_TEMPLATE.md <https://github.com/openedx/pytest-repo-health/blob/master/.github/ISSUE_TEMPLATE.md>`_\n\n\nIf you encounter any problems, please `file an issue`_ along with a detailed description.\n\nReporting Security Issues\n-------------------------\n\nPlease do not report security issues in public. Please email security@edx.org.\n\n\nGetting Help\n------------\n\nHave a question about this repository, or about Open edX in general? Please\nrefer to this `list of resources`_ if you need any assistance.\n\n.. _list of resources: https://open.edx.org/getting-help\n.. _edx-repo-health: https://github.com/openedx/edx-repo-health\n.. _`Cookiecutter`: https://github.com/audreyr/cookiecutter\n.. _`@hackebrot`: https://github.com/hackebrot\n.. _`BSD-3`: http://opensource.org/licenses/BSD-3-Clause\n.. _`GNU GPL v3.0`: http://www.gnu.org/licenses/gpl-3.0.txt\n.. _`Apache Software License 2.0`: http://www.apache.org/licenses/LICENSE-2.0\n.. _`cookiecutter-pytest-plugin`: https://github.com/pytest-dev/cookiecutter-pytest-plugin\n.. _`file an issue`: https://github.com/openedx/pytest-repo-health/issues\n.. _`pytest`: https://github.com/pytest-dev/pytest\n.. _`tox`: https://tox.readthedocs.io/en/latest/\n.. _`pip`: https://pypi.org/project/pip/\n.. _`PyPI`: https://pypi.org/project\n",
"bugtrack_url": null,
"license": "Apache Software License 2.0",
"summary": "A pytest plugin to report on repository standards conformance",
"version": "3.0.2",
"split_keywords": [
"pytest",
"edx"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "50d267cf2bd61f9ac2c0125daab559b171e6a0f0a18207d3a19e7c068e616248",
"md5": "d38fd28745a0f6ba3fce999d4015eb96",
"sha256": "797f082de9e4758300b932fd0d0a19dafaedec22ee9e5f5d749800575933a691"
},
"downloads": -1,
"filename": "pytest_repo_health-3.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d38fd28745a0f6ba3fce999d4015eb96",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 22613,
"upload_time": "2023-04-17T20:19:32",
"upload_time_iso_8601": "2023-04-17T20:19:32.252359Z",
"url": "https://files.pythonhosted.org/packages/50/d2/67cf2bd61f9ac2c0125daab559b171e6a0f0a18207d3a19e7c068e616248/pytest_repo_health-3.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fba0c74a8383810faf5d8c1a052b58544aac4fc08f977a8dc87280587c79155f",
"md5": "955be26b7e52d808ba466c74021a11db",
"sha256": "7e0663f5da3b059800955330dc2269a3b20366a22766be28bcd9d2df1a5ca873"
},
"downloads": -1,
"filename": "pytest-repo-health-3.0.2.tar.gz",
"has_sig": false,
"md5_digest": "955be26b7e52d808ba466c74021a11db",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 26733,
"upload_time": "2023-04-17T20:19:33",
"upload_time_iso_8601": "2023-04-17T20:19:33.731282Z",
"url": "https://files.pythonhosted.org/packages/fb/a0/c74a8383810faf5d8c1a052b58544aac4fc08f977a8dc87280587c79155f/pytest-repo-health-3.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-17 20:19:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "edX",
"github_project": "pytest-repo-health",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"appveyor": true,
"tox": true,
"lcname": "pytest-repo-health"
}
JSON
