diff-cover |pypi-version| |conda-version| |build-status|
========================================================================================
Automatically find diff lines that need test coverage.
Also finds diff lines that have violations (according to tools such
as pycodestyle, pyflakes, flake8, or pylint).
This is used as a code quality metric during code reviews.
Overview
--------
Diff coverage is the percentage of new or modified
lines that are covered by tests. This provides a clear
and achievable standard for code review: If you touch a line
of code, that line should be covered. Code coverage
is *every* developer's responsibility!
The ``diff-cover`` command line tool compares an XML coverage report
with the output of ``git diff``. It then reports coverage information
for lines in the diff.
Currently, ``diff-cover`` requires that:
- You are using ``git`` for version control.
- Your test runner generates coverage reports in Cobertura, Clover
or JaCoCo XML format, or LCov format.
Supported XML or LCov coverage reports can be generated with many coverage tools,
including:
- Cobertura__ (Java)
- Clover__ (Java)
- JaCoCo__ (Java)
- coverage.py__ (Python)
- JSCover__ (JavaScript)
- lcov__ (C/C++)
__ http://cobertura.sourceforge.net/
__ http://openclover.org/
__ https://www.jacoco.org/
__ http://nedbatchelder.com/code/coverage/
__ http://tntim96.github.io/JSCover/
__ https://ltp.sourceforge.net/coverage/lcov.php
``diff-cover`` is designed to be extended. If you are interested
in adding support for other version control systems or coverage
report formats, see below for information on how to contribute!
Installation
------------
To install the latest release:
.. code:: bash
pip install diff_cover
To install the development version:
.. code:: bash
git clone https://github.com/Bachmann1234/diff-cover.git
cd diff-cover
poetry install
poetry shell
Getting Started
---------------
1. Set the current working directory to a ``git`` repository.
2. Run your test suite under coverage and generate a [Cobertura, Clover or JaCoCo] XML report.
For example, using `pytest-cov`__:
.. code:: bash
pytest --cov --cov-report=xml
__ https://pypi.org/project/pytest-cov
This will create a ``coverage.xml`` file in the current working directory.
**NOTE**: If you are using a different coverage generator, you will
need to use different commands to generate the coverage XML report.
3. Run ``diff-cover``:
.. code:: bash
diff-cover coverage.xml
This will compare the current ``git`` branch to ``origin/main`` and print
the diff coverage report to the console.
You can also generate an HTML, JSON or Markdown version of the report:
.. code:: bash
diff-cover coverage.xml --html-report report.html
diff-cover coverage.xml --json-report report.json
diff-cover coverage.xml --markdown-report report.md
Multiple XML Coverage Reports
-------------------------------
In the case that one has multiple xml reports form multiple test suites, you
can get a combined coverage report (a line is counted as covered if it is
covered in ANY of the xml reports) by running ``diff-cover`` with multiple
coverage reports as arguments. You may specify any arbitrary number of coverage
reports:
.. code:: bash
diff-cover coverage1.xml coverage2.xml
Quality Coverage
-----------------
You can use diff-cover to see quality reports on the diff as well by running
``diff-quality``.
.. code :: bash
diff-quality --violations=<tool>
Where ``tool`` is the quality checker to use. Currently ``pycodestyle``, ``pyflakes``,
``flake8``, ``pylint``, ``checkstyle``, ``checkstylexml`` are supported, but more
checkers can (and should!) be supported. See the section "Adding `diff-quality``
Support for a New Quality Checker".
NOTE: There's no way to run ``findbugs`` from ``diff-quality`` as it operating
over the generated java bytecode and should be integrated into the build
framework.
Like ``diff-cover``, HTML, JSON or Markdown reports can be generated with
.. code:: bash
diff-quality --violations=<tool> --html-report report.html
diff-quality --violations=<tool> --json-report report.json
diff-quality --violations=<tool> --markdown-report report.md
If you have already generated a report using ``pycodestyle``, ``pyflakes``, ``flake8``,
``pylint``, ``checkstyle``, ``checkstylexml``, or ``findbugs`` you can pass the report
to ``diff-quality``. This is more efficient than letting ``diff-quality`` re-run
``pycodestyle``, ``pyflakes``, ``flake8``, ``pylint``, ``checkstyle``, or ``checkstylexml``.
.. code:: bash
# For pylint < 1.0
pylint -f parseable > pylint_report.txt
# For pylint >= 1.0
pylint --msg-template="{path}:{line}: [{msg_id}({symbol}), {obj}] {msg}" > pylint_report.txt
# Use the generated pylint report when running diff-quality
diff-quality --violations=pylint pylint_report.txt
# Use a generated pycodestyle report when running diff-quality.
pycodestyle > pycodestyle_report.txt
diff-quality --violations=pycodestyle pycodestyle_report.txt
Note that you must use the ``-f parseable`` option to generate
the ``pylint`` report for pylint versions less than 1.0 and the
``--msg-template`` option for versions >= 1.0.
``diff-quality`` will also accept multiple ``pycodestyle``, ``pyflakes``, ``flake8``,
or ``pylint`` reports:
.. code:: bash
diff-quality --violations=pylint report_1.txt report_2.txt
If you need to pass in additional options you can with the ``options`` flag
.. code:: bash
diff-quality --violations=pycodestyle --options="--exclude='*/migrations*' --statistics" pycodestyle_report.txt
Compare Branch
--------------
By default, ``diff-cover`` compares the current branch to ``origin/main``. To specify a different compare branch:
.. code:: bash
diff-cover coverage.xml --compare-branch=origin/release
Fail Under
----------
To have ``diff-cover`` and ``diff-quality`` return a non zero status code if the report quality/coverage percentage is
below a certain threshold specify the fail-under parameter
.. code:: bash
diff-cover coverage.xml --fail-under=80
diff-quality --violations=pycodestyle --fail-under=80
The above will return a non zero status if the coverage or quality score was below 80%.
Exclude/Include paths
---------------------
Explicit exclusion of paths is possible for both ``diff-cover`` and ``diff-quality``, while inclusion is
only supported for ``diff-quality`` (since 5.1.0).
The exclude option works with ``fnmatch``, include with ``glob``. Both options can consume multiple values.
Include options should be wrapped in double quotes to prevent shell globbing. Also they should be relative to
the current git directory.
.. code:: bash
diff-cover coverage.xml --exclude setup.py
diff-quality --violations=pycodestyle --exclude setup.py
diff-quality --violations=pycodestyle --include project/foo/**
The following is executed for every changed file:
#. check if any include pattern was specified
#. if yes, check if the changed file is part of at least one include pattern
#. check if the file is part of any exclude pattern
Ignore/Include based on file status in git
------------------------------------------
Both ``diff-cover`` and ``diff-quality`` allow users to ignore and include files based on the git
status: staged, unstaged, untracked:
* ``--ignore-staged``: ignore all staged files (by default include them)
* ``--ignore-unstaged``: ignore all unstaged files (by default include them)
* ``--include-untracked``: include all untracked files (by default ignore them)
Quiet mode
----------
Both ``diff-cover`` and ``diff-quality`` support a quiet mode which is disable by default.
It can be enabled by using the ``-q``/``--quiet`` flag:
.. code:: bash
diff-cover coverage.xml -q
diff-quality --violations=pycodestyle -q
If enabled, the tool will only print errors and failures but no information or warning messages.
Configuration files
-------------------
Both tools allow users to specify the options in a configuration file with `--config-file`/`-c`:
.. code:: bash
diff-cover coverage.xml --config-file myconfig.toml
diff-quality --violations=pycodestyle --config-file myconfig.toml
Currently, only TOML files are supported.
Please note, that only non-mandatory options are supported.
If an option is specified in the configuration file and over the command line, the value of the
command line is used.
TOML configuration
~~~~~~~~~~~~~~~~~~
The parser will only react to configuration files ending with `.toml`.
To use it, install `diff-cover` with the extra requirement `toml`.
The option names are the same as on the command line, but all dashes should be underscores.
If an option can be specified multiple times, the configuration value should be specified as a list.
.. code:: toml
[tool.diff_cover]
compare_branch = "origin/feature"
quiet = true
[tool.diff_quality]
compare_branch = "origin/feature"
ignore_staged = true
Troubleshooting
----------------------
**Issue**: ``diff-cover`` always reports: "No lines with coverage information in this diff."
**Solution**: ``diff-cover`` matches source files in the coverage XML report with
source files in the ``git diff``. For this reason, it's important
that the relative paths to the files match. If you are using `coverage.py`__
to generate the coverage XML report, then make sure you run
``diff-cover`` from the same working directory.
__ http://nedbatchelder.com/code/coverage/
**Issue**: ``GitDiffTool._execute()`` raises the error:
.. code:: bash
fatal: ambiguous argument 'origin/main...HEAD': unknown revision or path not in the working tree.
This is known to occur when running ``diff-cover`` in `Travis CI`__
__ http://travis-ci.org
**Solution**: Fetch the remote main branch before running ``diff-cover``:
.. code:: bash
git fetch origin master:refs/remotes/origin/main
**Issue**: ``diff-quality`` reports "diff_cover.violations_reporter.QualityReporterError:
No config file found, using default configuration"
**Solution**: Your project needs a `pylintrc` file.
Provide this file (it can be empty) and ``diff-quality`` should run without issue.
**Issue**: ``diff-quality`` reports "Quality tool not installed"
**Solution**: ``diff-quality`` assumes you have the tool you wish to run against your diff installed.
If you do not have it then install it with your favorite package manager.
**Issue**: ``diff-quality`` reports no quality issues
**Solution**: You might use a pattern like ``diff-quality --violations foo *.py``. The last argument
is not used to specify the files but for the quality tool report. Remove it to resolve the issue
License
-------
The code in this repository is licensed under the Apache 2.0 license.
Please see ``LICENSE.txt`` for details.
How to Contribute
-----------------
Contributions are very welcome. The easiest way is to fork this repo, and then
make a pull request from your fork.
NOTE: ``diff-quality`` supports a plugin model, so new tools can be integrated
without requiring changes to this repo. See the section "Adding `diff-quality``
Support for a New Quality Checker".
Setting Up For Development
~~~~~~~~~~~~~~~~~~~~~~~~~~
This project is managed with `poetry` this can be installed with `pip`
poetry manages a python virtual environment and organizes dependencies. It also
packages this project.
.. code:: bash
pip install poetry
.. code:: bash
poetry install
I would also suggest running this command after. This will make it so git blame ignores the commit
that formatted the entire codebase.
.. code:: bash
git config blame.ignoreRevsFile .git-blame-ignore-revs
Adding `diff-quality`` Support for a New Quality Checker
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Adding support for a new quality checker is simple. ``diff-quality`` supports
plugins using the popular Python
`pluggy package <https://pluggy.readthedocs.io/en/latest/>`_.
If the quality checker is already implemented as a Python package, great! If not,
`create a Python package <https://packaging.python.org/tutorials/packaging-projects/>`_
to host the plugin implementation.
In the Python package's ``setup.py`` file, define an entry point for the plugin,
e.g.
.. code:: python
setup(
...
entry_points={
'diff_cover': [
'sqlfluff = sqlfluff.diff_quality_plugin'
],
},
...
)
Notes:
* The dictionary key for the entry point must be named ``diff_cover``
* The value must be in the format ``TOOL_NAME = YOUR_PACKAGE.PLUGIN_MODULE``
When your package is installed, ``diff-quality`` uses this information to
look up the tool package and module based on the tool name provided to the
``--violations`` option of the ``diff-quality`` command, e.g.:
.. code:: bash
$ diff-quality --violations sqlfluff
The plugin implementation will look something like the example below. This is
a simplified example based on a working plugin implementation.
.. code:: python
from diff_cover.hook import hookimpl as diff_cover_hookimpl
from diff_cover.violationsreporters.base import BaseViolationReporter, Violation
class SQLFluffViolationReporter(BaseViolationReporter):
supported_extensions = ['sql']
def __init__(self):
super(SQLFluffViolationReporter, self).__init__('sqlfluff')
def violations(self, src_path):
return [
Violation(violation.line_number, violation.description)
for violation in get_linter().get_violations(src_path)
]
def measured_lines(self, src_path):
return None
@staticmethod
def installed():
return True
@diff_cover_hookimpl
def diff_cover_report_quality():
return SQLFluffViolationReporter()
Important notes:
* ``diff-quality`` is looking for a plugin function:
* Located in your package's module that was listed in the ``setup.py`` entry point.
* Marked with the ``@diff_cover_hookimpl`` decorator
* Named ``diff_cover_report_quality``. (This distinguishes it from any other
plugin types ``diff_cover`` may support.)
* The function should return an object with the following properties and methods:
* ``supported_extensions`` property with a list of supported file extensions
* ``violations()`` function that returns a list of ``Violation`` objects for
the specified ``src_path``. For more details on this function and other
possible reporting-related methods, see the ``BaseViolationReporter`` class
`here <https://github.com/Bachmann1234/diff_cover/blob/main/diff_cover/violationsreporters/base.py>`_.
Special Thanks
-------------------------
Shout out to the original author of diff-cover `Will Daly
<https://github.com/wedaly>`_ and the original author of diff-quality `Sarina Canelake
<https://github.com/sarina>`_.
Originally created with the support of `edX
<https://github.com/edx>`_.
.. |pypi-version| image:: https://img.shields.io/pypi/v/diff-cover.svg
:target: https://pypi.org/project/diff-cover
:alt: PyPI version
.. |conda-version| image:: https://img.shields.io/conda/vn/conda-forge/diff-cover.svg
:target: https://anaconda.org/conda-forge/diff-cover
:alt: Conda version
.. |build-status| image:: https://github.com/bachmann1234/diff_cover/actions/workflows/verify.yaml/badge.svg?branch=main
:target: https://github.com/Bachmann1234/diff_cover/actions/workflows/verify.yaml
:alt: Build Status
Raw data
{
"_id": null,
"home_page": "https://github.com/Bachmann1234/diff-cover",
"name": "diff-cover",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0.0,>=3.8.10",
"maintainer_email": null,
"keywords": null,
"author": "See Contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/dd/23/d26ca0d7401c362fd1d760947c8436790fd4e76fcf110323f1a2e35ab981/diff_cover-9.0.0.tar.gz",
"platform": null,
"description": "diff-cover |pypi-version| |conda-version| |build-status|\n========================================================================================\n\nAutomatically find diff lines that need test coverage.\nAlso finds diff lines that have violations (according to tools such\nas pycodestyle, pyflakes, flake8, or pylint).\nThis is used as a code quality metric during code reviews.\n\nOverview\n--------\n\nDiff coverage is the percentage of new or modified\nlines that are covered by tests. This provides a clear\nand achievable standard for code review: If you touch a line\nof code, that line should be covered. Code coverage\nis *every* developer's responsibility!\n\nThe ``diff-cover`` command line tool compares an XML coverage report\nwith the output of ``git diff``. It then reports coverage information\nfor lines in the diff.\n\nCurrently, ``diff-cover`` requires that:\n\n- You are using ``git`` for version control.\n- Your test runner generates coverage reports in Cobertura, Clover\n or JaCoCo XML format, or LCov format.\n\nSupported XML or LCov coverage reports can be generated with many coverage tools,\nincluding:\n\n- Cobertura__ (Java)\n- Clover__ (Java)\n- JaCoCo__ (Java)\n- coverage.py__ (Python)\n- JSCover__ (JavaScript)\n- lcov__ (C/C++)\n\n__ http://cobertura.sourceforge.net/\n__ http://openclover.org/\n__ https://www.jacoco.org/\n__ http://nedbatchelder.com/code/coverage/\n__ http://tntim96.github.io/JSCover/\n__ https://ltp.sourceforge.net/coverage/lcov.php\n\n\n``diff-cover`` is designed to be extended. If you are interested\nin adding support for other version control systems or coverage\nreport formats, see below for information on how to contribute!\n\n\nInstallation\n------------\n\nTo install the latest release:\n\n.. code:: bash\n\n pip install diff_cover\n\n\nTo install the development version:\n\n.. code:: bash\n\n git clone https://github.com/Bachmann1234/diff-cover.git\n cd diff-cover\n poetry install\n poetry shell\n\n\nGetting Started\n---------------\n\n1. Set the current working directory to a ``git`` repository.\n\n2. Run your test suite under coverage and generate a [Cobertura, Clover or JaCoCo] XML report.\n For example, using `pytest-cov`__:\n\n.. code:: bash\n\n pytest --cov --cov-report=xml\n\n__ https://pypi.org/project/pytest-cov\n\nThis will create a ``coverage.xml`` file in the current working directory.\n\n**NOTE**: If you are using a different coverage generator, you will\nneed to use different commands to generate the coverage XML report.\n\n\n3. Run ``diff-cover``:\n\n.. code:: bash\n\n diff-cover coverage.xml\n\nThis will compare the current ``git`` branch to ``origin/main`` and print\nthe diff coverage report to the console.\n\nYou can also generate an HTML, JSON or Markdown version of the report:\n\n.. code:: bash\n\n diff-cover coverage.xml --html-report report.html\n diff-cover coverage.xml --json-report report.json\n diff-cover coverage.xml --markdown-report report.md\n\nMultiple XML Coverage Reports\n-------------------------------\n\nIn the case that one has multiple xml reports form multiple test suites, you\ncan get a combined coverage report (a line is counted as covered if it is\ncovered in ANY of the xml reports) by running ``diff-cover`` with multiple\ncoverage reports as arguments. You may specify any arbitrary number of coverage\nreports:\n\n.. code:: bash\n\n diff-cover coverage1.xml coverage2.xml\n\nQuality Coverage\n-----------------\nYou can use diff-cover to see quality reports on the diff as well by running\n``diff-quality``.\n\n.. code :: bash\n\n diff-quality --violations=<tool>\n\nWhere ``tool`` is the quality checker to use. Currently ``pycodestyle``, ``pyflakes``,\n``flake8``, ``pylint``, ``checkstyle``, ``checkstylexml`` are supported, but more\ncheckers can (and should!) be supported. See the section \"Adding `diff-quality``\nSupport for a New Quality Checker\".\n\nNOTE: There's no way to run ``findbugs`` from ``diff-quality`` as it operating\nover the generated java bytecode and should be integrated into the build\nframework.\n\nLike ``diff-cover``, HTML, JSON or Markdown reports can be generated with\n\n.. code:: bash\n\n diff-quality --violations=<tool> --html-report report.html\n diff-quality --violations=<tool> --json-report report.json\n diff-quality --violations=<tool> --markdown-report report.md\n\nIf you have already generated a report using ``pycodestyle``, ``pyflakes``, ``flake8``,\n``pylint``, ``checkstyle``, ``checkstylexml``, or ``findbugs`` you can pass the report\nto ``diff-quality``. This is more efficient than letting ``diff-quality`` re-run\n``pycodestyle``, ``pyflakes``, ``flake8``, ``pylint``, ``checkstyle``, or ``checkstylexml``.\n\n.. code:: bash\n\n # For pylint < 1.0\n pylint -f parseable > pylint_report.txt\n\n # For pylint >= 1.0\n pylint --msg-template=\"{path}:{line}: [{msg_id}({symbol}), {obj}] {msg}\" > pylint_report.txt\n\n # Use the generated pylint report when running diff-quality\n diff-quality --violations=pylint pylint_report.txt\n\n # Use a generated pycodestyle report when running diff-quality.\n pycodestyle > pycodestyle_report.txt\n diff-quality --violations=pycodestyle pycodestyle_report.txt\n\nNote that you must use the ``-f parseable`` option to generate\nthe ``pylint`` report for pylint versions less than 1.0 and the\n``--msg-template`` option for versions >= 1.0.\n\n``diff-quality`` will also accept multiple ``pycodestyle``, ``pyflakes``, ``flake8``,\nor ``pylint`` reports:\n\n.. code:: bash\n\n diff-quality --violations=pylint report_1.txt report_2.txt\n\nIf you need to pass in additional options you can with the ``options`` flag\n\n.. code:: bash\n\n diff-quality --violations=pycodestyle --options=\"--exclude='*/migrations*' --statistics\" pycodestyle_report.txt\n\nCompare Branch\n--------------\n\nBy default, ``diff-cover`` compares the current branch to ``origin/main``. To specify a different compare branch:\n\n.. code:: bash\n\n diff-cover coverage.xml --compare-branch=origin/release\n\nFail Under\n----------\n\nTo have ``diff-cover`` and ``diff-quality`` return a non zero status code if the report quality/coverage percentage is\nbelow a certain threshold specify the fail-under parameter\n\n.. code:: bash\n\n diff-cover coverage.xml --fail-under=80\n diff-quality --violations=pycodestyle --fail-under=80\n\nThe above will return a non zero status if the coverage or quality score was below 80%.\n\nExclude/Include paths\n---------------------\n\nExplicit exclusion of paths is possible for both ``diff-cover`` and ``diff-quality``, while inclusion is\nonly supported for ``diff-quality`` (since 5.1.0).\n\nThe exclude option works with ``fnmatch``, include with ``glob``. Both options can consume multiple values.\nInclude options should be wrapped in double quotes to prevent shell globbing. Also they should be relative to\nthe current git directory.\n\n.. code:: bash\n\n diff-cover coverage.xml --exclude setup.py\n diff-quality --violations=pycodestyle --exclude setup.py\n\n diff-quality --violations=pycodestyle --include project/foo/**\n\nThe following is executed for every changed file:\n\n#. check if any include pattern was specified\n#. if yes, check if the changed file is part of at least one include pattern\n#. check if the file is part of any exclude pattern\n\nIgnore/Include based on file status in git\n------------------------------------------\nBoth ``diff-cover`` and ``diff-quality`` allow users to ignore and include files based on the git\nstatus: staged, unstaged, untracked:\n\n* ``--ignore-staged``: ignore all staged files (by default include them)\n* ``--ignore-unstaged``: ignore all unstaged files (by default include them)\n* ``--include-untracked``: include all untracked files (by default ignore them)\n\nQuiet mode\n----------\nBoth ``diff-cover`` and ``diff-quality`` support a quiet mode which is disable by default.\nIt can be enabled by using the ``-q``/``--quiet`` flag:\n\n.. code:: bash\n\n diff-cover coverage.xml -q\n diff-quality --violations=pycodestyle -q\n\nIf enabled, the tool will only print errors and failures but no information or warning messages.\n\nConfiguration files\n-------------------\nBoth tools allow users to specify the options in a configuration file with `--config-file`/`-c`:\n\n.. code:: bash\n\n diff-cover coverage.xml --config-file myconfig.toml\n diff-quality --violations=pycodestyle --config-file myconfig.toml\n\nCurrently, only TOML files are supported.\nPlease note, that only non-mandatory options are supported.\nIf an option is specified in the configuration file and over the command line, the value of the\ncommand line is used.\n\nTOML configuration\n~~~~~~~~~~~~~~~~~~\n\nThe parser will only react to configuration files ending with `.toml`.\nTo use it, install `diff-cover` with the extra requirement `toml`.\n\nThe option names are the same as on the command line, but all dashes should be underscores.\nIf an option can be specified multiple times, the configuration value should be specified as a list.\n\n.. code:: toml\n\n [tool.diff_cover]\n compare_branch = \"origin/feature\"\n quiet = true\n\n [tool.diff_quality]\n compare_branch = \"origin/feature\"\n ignore_staged = true\n\n\nTroubleshooting\n----------------------\n\n**Issue**: ``diff-cover`` always reports: \"No lines with coverage information in this diff.\"\n\n**Solution**: ``diff-cover`` matches source files in the coverage XML report with\nsource files in the ``git diff``. For this reason, it's important\nthat the relative paths to the files match. If you are using `coverage.py`__\nto generate the coverage XML report, then make sure you run\n``diff-cover`` from the same working directory.\n\n__ http://nedbatchelder.com/code/coverage/\n\n**Issue**: ``GitDiffTool._execute()`` raises the error:\n\n.. code:: bash\n\n fatal: ambiguous argument 'origin/main...HEAD': unknown revision or path not in the working tree.\n\nThis is known to occur when running ``diff-cover`` in `Travis CI`__\n\n__ http://travis-ci.org\n\n**Solution**: Fetch the remote main branch before running ``diff-cover``:\n\n.. code:: bash\n\n git fetch origin master:refs/remotes/origin/main\n\n**Issue**: ``diff-quality`` reports \"diff_cover.violations_reporter.QualityReporterError:\nNo config file found, using default configuration\"\n\n**Solution**: Your project needs a `pylintrc` file.\nProvide this file (it can be empty) and ``diff-quality`` should run without issue.\n\n**Issue**: ``diff-quality`` reports \"Quality tool not installed\"\n\n**Solution**: ``diff-quality`` assumes you have the tool you wish to run against your diff installed.\nIf you do not have it then install it with your favorite package manager.\n\n**Issue**: ``diff-quality`` reports no quality issues\n\n**Solution**: You might use a pattern like ``diff-quality --violations foo *.py``. The last argument\nis not used to specify the files but for the quality tool report. Remove it to resolve the issue\n\nLicense\n-------\n\nThe code in this repository is licensed under the Apache 2.0 license.\nPlease see ``LICENSE.txt`` for details.\n\n\nHow to Contribute\n-----------------\n\nContributions are very welcome. The easiest way is to fork this repo, and then\nmake a pull request from your fork.\n\nNOTE: ``diff-quality`` supports a plugin model, so new tools can be integrated\nwithout requiring changes to this repo. See the section \"Adding `diff-quality``\nSupport for a New Quality Checker\".\n\nSetting Up For Development\n~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThis project is managed with `poetry` this can be installed with `pip`\npoetry manages a python virtual environment and organizes dependencies. It also\npackages this project.\n\n.. code:: bash\n\n pip install poetry\n\n.. code:: bash\n\n poetry install\n\nI would also suggest running this command after. This will make it so git blame ignores the commit\nthat formatted the entire codebase.\n\n.. code:: bash\n\n git config blame.ignoreRevsFile .git-blame-ignore-revs\n\n\nAdding `diff-quality`` Support for a New Quality Checker\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nAdding support for a new quality checker is simple. ``diff-quality`` supports\nplugins using the popular Python\n`pluggy package <https://pluggy.readthedocs.io/en/latest/>`_.\n\nIf the quality checker is already implemented as a Python package, great! If not,\n`create a Python package <https://packaging.python.org/tutorials/packaging-projects/>`_\nto host the plugin implementation.\n\nIn the Python package's ``setup.py`` file, define an entry point for the plugin,\ne.g.\n\n.. code:: python\n\n setup(\n ...\n entry_points={\n 'diff_cover': [\n 'sqlfluff = sqlfluff.diff_quality_plugin'\n ],\n },\n ...\n )\n\nNotes:\n\n* The dictionary key for the entry point must be named ``diff_cover``\n* The value must be in the format ``TOOL_NAME = YOUR_PACKAGE.PLUGIN_MODULE``\n\nWhen your package is installed, ``diff-quality`` uses this information to\nlook up the tool package and module based on the tool name provided to the\n``--violations`` option of the ``diff-quality`` command, e.g.:\n\n.. code:: bash\n\n $ diff-quality --violations sqlfluff\n\nThe plugin implementation will look something like the example below. This is\na simplified example based on a working plugin implementation.\n\n.. code:: python\n\n from diff_cover.hook import hookimpl as diff_cover_hookimpl\n from diff_cover.violationsreporters.base import BaseViolationReporter, Violation\n\n class SQLFluffViolationReporter(BaseViolationReporter):\n supported_extensions = ['sql']\n\n def __init__(self):\n super(SQLFluffViolationReporter, self).__init__('sqlfluff')\n\n def violations(self, src_path):\n return [\n Violation(violation.line_number, violation.description)\n for violation in get_linter().get_violations(src_path)\n ]\n\n def measured_lines(self, src_path):\n return None\n\n @staticmethod\n def installed():\n return True\n\n\n @diff_cover_hookimpl\n def diff_cover_report_quality():\n return SQLFluffViolationReporter()\n\nImportant notes:\n\n* ``diff-quality`` is looking for a plugin function:\n\n * Located in your package's module that was listed in the ``setup.py`` entry point.\n * Marked with the ``@diff_cover_hookimpl`` decorator\n * Named ``diff_cover_report_quality``. (This distinguishes it from any other\n plugin types ``diff_cover`` may support.)\n* The function should return an object with the following properties and methods:\n\n * ``supported_extensions`` property with a list of supported file extensions\n * ``violations()`` function that returns a list of ``Violation`` objects for\n the specified ``src_path``. For more details on this function and other\n possible reporting-related methods, see the ``BaseViolationReporter`` class\n `here <https://github.com/Bachmann1234/diff_cover/blob/main/diff_cover/violationsreporters/base.py>`_.\n\nSpecial Thanks\n-------------------------\n\nShout out to the original author of diff-cover `Will Daly\n<https://github.com/wedaly>`_ and the original author of diff-quality `Sarina Canelake\n<https://github.com/sarina>`_.\n\nOriginally created with the support of `edX\n<https://github.com/edx>`_.\n\n\n.. |pypi-version| image:: https://img.shields.io/pypi/v/diff-cover.svg\n :target: https://pypi.org/project/diff-cover\n :alt: PyPI version\n.. |conda-version| image:: https://img.shields.io/conda/vn/conda-forge/diff-cover.svg\n :target: https://anaconda.org/conda-forge/diff-cover\n :alt: Conda version\n.. |build-status| image:: https://github.com/bachmann1234/diff_cover/actions/workflows/verify.yaml/badge.svg?branch=main\n :target: https://github.com/Bachmann1234/diff_cover/actions/workflows/verify.yaml\n :alt: Build Status\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Run coverage and linting reports on diffs",
"version": "9.0.0",
"project_urls": {
"Homepage": "https://github.com/Bachmann1234/diff-cover",
"Repository": "https://github.com/Bachmann1234/diff-cover"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "91c26477e1e2124d7234dfb2cd54fb0628e52f251731592c6d18a935c9c7579b",
"md5": "11d4454368f293c83b28863c64af29e9",
"sha256": "31b308259b79e2cab5f30aff499a3ea3ba9475f0d495d82ba9b6caa7487bca03"
},
"downloads": -1,
"filename": "diff_cover-9.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "11d4454368f293c83b28863c64af29e9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.8.10",
"size": 51308,
"upload_time": "2024-04-14T20:08:35",
"upload_time_iso_8601": "2024-04-14T20:08:35.101617Z",
"url": "https://files.pythonhosted.org/packages/91/c2/6477e1e2124d7234dfb2cd54fb0628e52f251731592c6d18a935c9c7579b/diff_cover-9.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "dd23d26ca0d7401c362fd1d760947c8436790fd4e76fcf110323f1a2e35ab981",
"md5": "fa8a91af75a332f92fcd937670f07b42",
"sha256": "1dc851d3f3f320c048d03618e4c0d9861fa4a1506b425d2d09a564b20c95674a"
},
"downloads": -1,
"filename": "diff_cover-9.0.0.tar.gz",
"has_sig": false,
"md5_digest": "fa8a91af75a332f92fcd937670f07b42",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0.0,>=3.8.10",
"size": 91775,
"upload_time": "2024-04-14T20:08:37",
"upload_time_iso_8601": "2024-04-14T20:08:37.149206Z",
"url": "https://files.pythonhosted.org/packages/dd/23/d26ca0d7401c362fd1d760947c8436790fd4e76fcf110323f1a2e35ab981/diff_cover-9.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-14 20:08:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Bachmann1234",
"github_project": "diff-cover",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "diff-cover"
}
JSON
