.. image:: https://interrogate.readthedocs.io/en/latest/_static/logo_pink.png
:alt: Pink Sloth Logo
=================================
``interrogate``: explain yourself
=================================
.. image:: https://interrogate.readthedocs.io/en/latest/_static/interrogate_badge.svg
:target: https://github.com/econchick/interrogate
:alt: Documentation Coverage
.. image:: https://codecov.io/gh/econchick/interrogate/branch/master/graph/badge.svg
:target: https://codecov.io/gh/econchick/interrogate
:alt: Testing Coverage
.. image:: https://readthedocs.org/projects/interrogate/badge/?version=latest&style=flat
:target: https://interrogate.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. image:: https://github.com/econchick/interrogate/workflows/CI/badge.svg?branch=master
:target: https://github.com/econchick/interrogate/actions?workflow=CI
:alt: CI Status
.. start-readme
Interrogate a codebase for docstring coverage.
Why Do I Need This?
===================
``interrogate`` checks your code base for missing docstrings.
Documentation should be as important as code itself. And it should live *within* code. Python `standardized <https://www.python.org/dev/peps/pep-0257/>`_ docstrings, allowing for developers to navigate libraries as simply as calling ``help()`` on objects, and with powerful tools like `Sphinx <https://www.sphinx-doc.org/en/master/>`_, `pydoc <https://docs.python.org/3/library/pydoc.html>`_, and `Docutils <https://docutils.sourceforge.io/>`_ to automatically generate HTML, LaTeX, PDFs, etc.
*Enter:* ``interrogate``.
``interrogate`` will tell you which methods, functions, classes, and modules have docstrings, and which do not. Use ``interrogate`` to:
* Get an understanding of how well your code is documented;
* Add it to CI/CD checks to enforce documentation on newly-added code;
* Assess a new code base for (one aspect of) code quality and maintainability.
Let's get started.
Requirements
============
``interrogate`` supports Python 3.8 and above.
Installation
============
``interrogate`` is available on `PyPI <https://pypi.org/project/interrogate/>`_ and `GitHub <https://github.com/econchick/interrogate>`_. The recommended installation method is `pip <https://pip.pypa.io/en/stable/>`_-installing into a `virtualenv <https://hynek.me/articles/virtualenv-lives/>`_:
.. code-block:: console
$ pip install interrogate
Extras
------
``interrogate`` provides a way to generate a `shields.io-like coverage badge <#other-usage>`_ as an **SVG file**.
To generate a **PNG file** instead, install ``interrogate`` with the extras ``[png]``:
.. code-block:: console
$ pip install interrogate[png]
**NOTICE:** Additional system libraries/tools may be required in order to generate a PNG file of the coverage badge:
* on Windows, install Visual C++ compiler for Cairo;
* on macOS, install ``cairo`` and ``libffi`` (with Homebrew for example);
* on Linux, install the ``cairo``, ``python3-dev`` and ``libffi-dev`` packages (names may vary depending on distribution).
Refer to the ``cairosvg`` `documentation <https://cairosvg.org/documentation/>`_ for more information.
Usage
=====
Try it out on a Python project:
.. code-block:: console
$ interrogate [PATH]
RESULT: PASSED (minimum: 80.0%, actual: 100.0%)
Add verbosity to see a summary:
.. code-block:: console
$ interrogate -v [PATH]
================== Coverage for /Users/lynn/dev/interrogate/ ====================
------------------------------------ Summary ------------------------------------
| Name | Total | Miss | Cover | Cover% |
|---------------------------------------|---------|--------|---------|----------|
| src/interrogate/__init__.py | 1 | 0 | 1 | 100% |
| src/interrogate/__main__.py | 1 | 0 | 1 | 100% |
| src/interrogate/badge_gen.py | 6 | 0 | 6 | 100% |
| src/interrogate/cli.py | 2 | 0 | 2 | 100% |
| src/interrogate/config.py | 8 | 0 | 8 | 100% |
| src/interrogate/coverage.py | 27 | 0 | 27 | 100% |
| src/interrogate/utils.py | 10 | 0 | 10 | 100% |
| src/interrogate/visit.py | 18 | 0 | 18 | 100% |
| tests/functional/__init__.py | 1 | 0 | 1 | 100% |
| tests/functional/test_cli.py | 8 | 0 | 8 | 100% |
| tests/functional/test_coverage.py | 10 | 0 | 10 | 100% |
| tests/unit/__init__.py | 1 | 0 | 1 | 100% |
| tests/unit/test_badge_gen.py | 8 | 0 | 8 | 100% |
| tests/unit/test_config.py | 10 | 0 | 10 | 100% |
| tests/unit/test_utils.py | 13 | 0 | 13 | 100% |
|---------------------------------------|---------|--------|---------|----------|
| TOTAL | 124 | 0 | 124 | 100.0% |
---------------- RESULT: PASSED (minimum: 80.0%, actual: 100.0%) ----------------
Add even *more* verbosity:
.. code-block:: console
$ interrogate -vv [PATH]
================== Coverage for /Users/lynn/dev/interrogate/ ====================
------------------------------- Detailed Coverage -------------------------------
| Name | Status |
|---------------------------------------------------------------------|---------|
| src/interrogate/__init__.py (module) | COVERED |
|---------------------------------------------------------------------|---------|
| src/interrogate/__main__.py (module) | COVERED |
|---------------------------------------------------------------------|---------|
| src/interrogate/badge_gen.py (module) | COVERED |
| save_badge (L42) | COVERED |
| get_badge (L87) | COVERED |
| should_generate_badge (L103) | COVERED |
| get_color (L160) | COVERED |
| create (L173) | COVERED |
|---------------------------------------------------------------------|---------|
| src/interrogate/cli.py (module) | COVERED |
| main (L258) | COVERED |
|---------------------------------------------------------------------|---------|
| src/interrogate/config.py (module) | COVERED |
| InterrogateConfig (L19) | COVERED |
| find_project_root (L61) | COVERED |
| find_project_config (L89) | COVERED |
| parse_pyproject_toml (L100) | COVERED |
| sanitize_list_values (L116) | COVERED |
| parse_setup_cfg (L139) | COVERED |
| read_config_file (L173) | COVERED |
|---------------------------------------------------------------------|---------|
| src/interrogate/coverage.py (module) | COVERED |
| BaseInterrogateResult (L23) | COVERED |
| BaseInterrogateResult.perc_covered (L37) | COVERED |
| InterrogateFileResult (L54) | COVERED |
| InterrogateFileResult.combine (L67) | COVERED |
| InterrogateResults (L81) | COVERED |
| InterrogateResults.combine (L93) | COVERED |
| InterrogateCoverage (L101) | COVERED |
| InterrogateCoverage._add_common_exclude (L121) | COVERED |
| InterrogateCoverage._filter_files (L128) | COVERED |
| InterrogateCoverage.get_filenames_from_paths (L141) | COVERED |
| InterrogateCoverage._filter_nodes (L168) | COVERED |
| InterrogateCoverage._filter_inner_nested (L194) | COVERED |
| InterrogateCoverage._get_file_coverage (L203) | COVERED |
| InterrogateCoverage._get_coverage (L231) | COVERED |
| InterrogateCoverage.get_coverage (L248) | COVERED |
| InterrogateCoverage._get_filename (L253) | COVERED |
| InterrogateCoverage._get_detailed_row (L264) | COVERED |
| InterrogateCoverage._create_detailed_table (L281) | COVERED |
| InterrogateCoverage._create_detailed_table._sort_nodes (L288) | COVERED |
| InterrogateCoverage._print_detailed_table (L315) | COVERED |
| InterrogateCoverage._create_summary_table (L338) | COVERED |
| InterrogateCoverage._print_summary_table (L381) | COVERED |
| InterrogateCoverage._sort_results (L399) | COVERED |
| InterrogateCoverage._get_header_base (L429) | COVERED |
| InterrogateCoverage._print_omitted_file_count (L438) | COVERED |
| InterrogateCoverage.print_results (L469) | COVERED |
|---------------------------------------------------------------------|---------|
| src/interrogate/utils.py (module) | COVERED |
| parse_regex (L21) | COVERED |
| smart_open (L40) | COVERED |
| get_common_base (L60) | COVERED |
| OutputFormatter (L80) | COVERED |
| OutputFormatter.should_markup (L90) | COVERED |
| OutputFormatter.set_detailed_markup (L105) | COVERED |
| OutputFormatter.set_summary_markup (L129) | COVERED |
| OutputFormatter._interrogate_line_formatter (L158) | COVERED |
| OutputFormatter.get_table_formatter (L226) | COVERED |
|---------------------------------------------------------------------|---------|
| src/interrogate/visit.py (module) | COVERED |
| CovNode (L15) | COVERED |
| CoverageVisitor (L44) | COVERED |
| CoverageVisitor._has_doc (L58) | COVERED |
| CoverageVisitor._visit_helper (L65) | COVERED |
| CoverageVisitor._is_nested_func (L112) | COVERED |
| CoverageVisitor._is_nested_cls (L121) | COVERED |
| CoverageVisitor._is_private (L133) | COVERED |
| CoverageVisitor._is_semiprivate (L141) | COVERED |
| CoverageVisitor._is_ignored_common (L151) | COVERED |
| CoverageVisitor._has_property_decorators (L168) | COVERED |
| CoverageVisitor._has_setters (L182) | COVERED |
| CoverageVisitor._is_func_ignored (L193) | COVERED |
| CoverageVisitor._is_class_ignored (L217) | COVERED |
| CoverageVisitor.visit_Module (L221) | COVERED |
| CoverageVisitor.visit_ClassDef (L228) | COVERED |
| CoverageVisitor.visit_FunctionDef (L237) | COVERED |
| CoverageVisitor.visit_AsyncFunctionDef (L246) | COVERED |
|---------------------------------------------------------------------|---------|
| tests/functional/__init__.py (module) | COVERED |
|---------------------------------------------------------------------|---------|
| tests/functional/test_cli.py (module) | COVERED |
| runner (L22) | COVERED |
| test_run_no_paths (L30) | COVERED |
| test_run_shortflags (L77) | COVERED |
| test_run_longflags (L106) | COVERED |
| test_run_multiple_flags (L124) | COVERED |
| test_generate_badge (L135) | COVERED |
| test_incompatible_options (L170) | COVERED |
|---------------------------------------------------------------------|---------|
| tests/functional/test_coverage.py (module) | COVERED |
| test_coverage_simple (L60) | COVERED |
| test_coverage_errors (L73) | COVERED |
| test_print_results (L101) | COVERED |
| test_print_results_omit_covered (L130) | COVERED |
| test_print_results_omit_none (L156) | COVERED |
| test_print_results_omit_all_summary (L174) | COVERED |
| test_print_results_omit_all_detailed (L198) | COVERED |
| test_print_results_ignore_module (L226) | COVERED |
| test_print_results_single_file (L253) | COVERED |
|---------------------------------------------------------------------|---------|
| tests/unit/__init__.py (module) | COVERED |
|---------------------------------------------------------------------|---------|
| tests/unit/test_badge_gen.py (module) | COVERED |
| test_save_badge (L26) | COVERED |
| test_save_badge_windows (L50) | COVERED |
| test_save_badge_no_cairo (L62) | COVERED |
| test_get_badge (L73) | COVERED |
| test_should_generate (L96) | COVERED |
| test_get_color (L115) | COVERED |
| test_create (L136) | COVERED |
|---------------------------------------------------------------------|---------|
| tests/unit/test_config.py (module) | COVERED |
| test_find_project_root (L29) | COVERED |
| test_find_project_config (L48) | COVERED |
| test_parse_pyproject_toml (L57) | COVERED |
| test_sanitize_list_values (L93) | COVERED |
| test_parse_setup_cfg (L98) | COVERED |
| test_parse_setup_cfg_raises (L123) | COVERED |
| test_read_config_file_none (L134) | COVERED |
| test_read_config_file (L193) | COVERED |
| test_read_config_file_raises (L207) | COVERED |
|---------------------------------------------------------------------|---------|
| tests/unit/test_utils.py (module) | COVERED |
| test_parse_regex (L32) | COVERED |
| test_smart_open (L39) | COVERED |
| test_get_common_base (L69) | COVERED |
| test_get_common_base_windows (L100) | COVERED |
| test_output_formatter_should_markup (L132) | COVERED |
| test_output_formatter_set_detailed_markup (L163) | COVERED |
| test_output_formatter_set_summary_markup (L206) | COVERED |
| test_output_formatter_interrogate_line_formatter (L258) | COVERED |
| test_output_formatter_interrogate_line_formatter_windows (L319) | COVERED |
| test_output_formatter_get_table_formatter (L343) | COVERED |
| test_output_formatter_get_table_formatter_py38 (L381) | COVERED |
| test_output_formatter_get_table_formatter_raises (L395) | COVERED |
|---------------------------------------------------------------------|---------|
------------------------------------ Summary ------------------------------------
| Name | Total | Miss | Cover | Cover% |
|---------------------------------------|---------|--------|---------|----------|
| src/interrogate/__init__.py | 1 | 0 | 1 | 100% |
| src/interrogate/__main__.py | 1 | 0 | 1 | 100% |
| src/interrogate/badge_gen.py | 6 | 0 | 6 | 100% |
| src/interrogate/cli.py | 2 | 0 | 2 | 100% |
| src/interrogate/config.py | 8 | 0 | 8 | 100% |
| src/interrogate/coverage.py | 27 | 0 | 27 | 100% |
| src/interrogate/utils.py | 10 | 0 | 10 | 100% |
| src/interrogate/visit.py | 18 | 0 | 18 | 100% |
| tests/functional/__init__.py | 1 | 0 | 1 | 100% |
| tests/functional/test_cli.py | 8 | 0 | 8 | 100% |
| tests/functional/test_coverage.py | 10 | 0 | 10 | 100% |
| tests/unit/__init__.py | 1 | 0 | 1 | 100% |
| tests/unit/test_badge_gen.py | 8 | 0 | 8 | 100% |
| tests/unit/test_config.py | 10 | 0 | 10 | 100% |
| tests/unit/test_utils.py | 13 | 0 | 13 | 100% |
|---------------------------------------|---------|--------|---------|----------|
| TOTAL | 124 | 0 | 124 | 100.0% |
---------------- RESULT: PASSED (minimum: 80.0%, actual: 100.0%) ----------------
Other Usage
===========
Generate a `shields.io <https://shields.io/>`_ badge (like this one! |interrogate-badge| ):
.. code-block:: console
$ interrogate --generate-badge PATH
RESULT: PASSED (minimum: 80.0%, actual: 100.0%)
Generated badge to /Users/lynn/dev/interrogate/docs/_static/interrogate_badge.svg
`See below <#badge-options>`_ for more badge configuration.
Add it to your ``tox.ini`` file to enforce a level of coverage:
.. code-block:: ini
[testenv:doc]
deps = interrogate
skip_install = true
commands =
interrogate --quiet --fail-under 95 src tests
Or use it with `pre-commit <https://pre-commit.com/>`_:
.. code-block:: yaml
repos:
- repo: https://github.com/econchick/interrogate
rev: 1.7.0 # or master if you're bold
hooks:
- id: interrogate
args: [--quiet, --fail-under=95]
pass_filenames: false # needed if excluding files with pyproject.toml or setup.cfg
Use it within your code directly:
.. code-block:: pycon
>>> from interrogate import coverage
>>> cov = coverage.InterrogateCoverage(paths=["src"])
>>> results = cov.get_coverage()
>>> results
InterrogateResults(total=68, covered=65, missing=3)
Use ``interrogate`` with `GitHub Actions <https://github.com/features/actions>`_. Check out the `action <https://github.com/marketplace/actions/python-interrogate-check>`_ written & maintained by `Jack McKew <https://github.com/JackMcKew>`_ (thank you, Jack!).
Or use ``interrogate`` in VSCode with the `interrogate extension <https://marketplace.visualstudio.com/items?itemName=kennethlove.interrogate>`_ written & maintained by `Kenneth Love <https://thekennethlove.com/>`_ (thank you, Kenneth!).
Configuration
=============
Configure within your ``pyproject.toml`` (``interrogate`` will automatically detect a ``pyproject.toml`` file and pick up default values for the command line options):
.. code-block:: console
$ interrogate -c pyproject.toml [OPTIONS] [PATHS]...
.. code-block:: toml
[tool.interrogate]
ignore-init-method = true
ignore-init-module = false
ignore-magic = false
ignore-semiprivate = false
ignore-private = false
ignore-property-decorators = false
ignore-module = false
ignore-nested-functions = false
ignore-nested-classes = true
ignore-setters = false
ignore-overloaded-functions = false
fail-under = 95
exclude = ["setup.py", "docs", "build"]
ignore-regex = ["^get$", "^mock_.*", ".*BaseClass.*"]
ext = []
# possible values: sphinx (default), google
style = sphinx
# possible values: 0 (minimal output), 1 (-v), 2 (-vv)
verbose = 0
quiet = false
whitelist-regex = []
color = true
omit-covered-files = false
generate-badge = "."
badge-format = "svg"
Or configure within your ``setup.cfg`` (``interrogate`` will automatically detect a ``setup.cfg`` file and pick up default values for the command line options):
.. code-block:: console
$ interrogate -c setup.cfg [OPTIONS] [PATHS]...
.. code-block:: ini
[tool:interrogate]
ignore-init-method = true
ignore-init-module = false
ignore-magic = false
ignore-semiprivate = false
ignore-private = false
ignore-property-decorators = false
ignore-module = false
ignore-nested-functions = false
ignore-nested-classes = true
ignore-setters = false
ignore-overloaded-functions = false
fail-under = 95
exclude = setup.py,docs,build
ignore-regex = ^get$,^mock_.*,.*BaseClass.*
ext = []
; possible values: sphinx (default), google
style = sphinx
; possible values: 0 (minimal output), 1 (-v), 2 (-vv)
verbose = 0
quiet = false
whitelist-regex =
color = true
omit-covered-files = false
generate-badge = .
badge-format = svg
.. warning::
The use of ``setup.cfg`` is not recommended unless for very simple use cases. ``.cfg`` files use a different parser than ``pyproject.toml`` which might cause hard to track down problems. When possible, it is recommended to use ``pyproject.toml`` to define your interrogate configuration.
.. _badge-opts:
Badge Options
=============
Badge Format
------------
The default file format is ``svg``. Use the ``--badge-format`` flag to create a ``png`` file instead.
**Note**: ``interrogate`` must be installed with ``interrogate[png]`` in order to generate ``png`` files (see `above <#extras>`_).
.. code-block:: console
$ interrogate --generate-badge PATH --badge-format png
RESULT: PASSED (minimum: 80.0%, actual: 100.0%)
Generated badge to /Users/lynn/dev/interrogate/docs/_static/interrogate_badge.png
Badge Style
-----------
The following badge styles are available via the ``--badge-style`` flag:
+------------------------------------+--------------------------------+
| option | example |
+====================================+================================+
| ``flat`` | |flat-example| |
+------------------------------------+--------------------------------+
| ``flat-square`` | |flat-square-example| |
+------------------------------------+--------------------------------+
| ``flat-square-modified`` (default) | |interrogate-badge| |
+------------------------------------+--------------------------------+
| ``for-the-badge`` | |for-the-badge-example| |
+------------------------------------+--------------------------------+
| ``plastic`` | |plastic-example| |
+------------------------------------+--------------------------------+
| ``social`` | |social-example| |
+------------------------------------+--------------------------------+
.. end-readme
Command Line Options
====================
To view all options available, run ``interrogate --help``:
.. code-block:: console
interrogate -h
Usage: interrogate [OPTIONS] [PATHS]...
Measure and report on documentation coverage in Python modules.
Options:
--version Show the version and exit.
-v, --verbose Level of verbosity.
NOTE: When configuring verbosity in
pyproject.toml or setup.cfg, `verbose=1`
maps to `-v`, and `verbose=2` maps to `-vv`.
`verbose=0` is the equivalent of no verbose
flags used, producing minimal output.
-q, --quiet Do not print output [default: False]
-f, --fail-under INT | FLOAT Fail when coverage % is less than a given
amount. [default: 80.0]
-e, --exclude PATH Exclude PATHs of files and/or directories.
Multiple `-e/--exclude` invocations
supported.
-i, --ignore-init-method Ignore `__init__` method of classes.
[default: False]
-I, --ignore-init-module Ignore `__init__.py` modules. [default:
False]
-m, --ignore-magic Ignore all magic methods of classes.
[default: False]
NOTE: This does not include the `__init__`
method. To ignore `__init__` methods, use
`--ignore-init-method`.
-M, --ignore-module Ignore module-level docstrings. [default:
False]
-n, --ignore-nested-functions Ignore nested functions and methods.
[default: False]
-C, --ignore-nested-classes Ignore nested classes. [default: False]
-O, --ignore-overloaded-functions
Ignore `@typing.overload`-decorated functions.
[default: False]
-p, --ignore-private Ignore private classes, methods, and
functions starting with two underscores.
[default: False]
NOTE: This does not include magic methods;
use `--ignore-magic` and/or `--ignore-init-
method` instead.
-P, --ignore-property-decorators
Ignore methods with property setter/getter/deleter
decorators. [default: False]
-S, --ignore-setters Ignore methods with property setter
decorators. [default: False]
-s, --ignore-semiprivate Ignore semiprivate classes, methods, and
functions starting with a single underscore.
[default: False]
-r, --ignore-regex STR Regex identifying class, method, and
function names to ignore. Multiple
`-r/--ignore-regex` invocations supported.
--ext Include Python-like files with the given
extension (supported: ``pyi``). Multiple
`--ext` invocations supported.
-w, --whitelist-regex STR Regex identifying class, method, and
function names to include. Multiple
`-w/--whitelist-regex` invocations
supported.
--style [sphinx|google] Style of docstrings to honor. Using `google`
will consider a class and its `__init__`
method both covered if there is either a
class-level docstring, or an `__init__`
method docstring, instead of enforcing both.
Mutually exclusive with `-i`/`--ignore-init`
flag. [default: sphinx]
-o, --output FILE Write output to a given FILE. [default:
stdout]
--color / --no-color Toggle color output on/off when printing to
stdout. [default: True]
--omit-covered-files Omit reporting files that have 100%
documentation coverage. This option is
ignored if verbosity is not set. [default:
False]
-g, --generate-badge PATH Generate a 'shields.io' status badge (an SVG
image) in at a given file or directory. Will
not generate a badge if results did not
change from an existing badge of the same
path.
--badge-format [svg|png] File format for the generated badge. Used
with the `-g/--generate-badge` flag.
[default: svg]
NOTE: To generate a PNG file, interrogate
must be installed with `interrogate[png]`,
i.e. `pip install interrogate[png]`.
--badge-style [flat|flat-square|flat-square-modified|for-the-badge|plastic|social]
Desired style of shields.io badge. Used with
the `-g/--generate-badge` flag. [default:
flat-square-modified]
-h, --help Show this message and exit.
-c, --config FILE Read configuration from `pyproject.toml` or
`setup.cfg`.
.. start-uses-this
Users of Interrogate
====================
* `attrs <https://github.com/python-attrs/attrs>`_
* `OpenMMLab <https://github.com/open-mmlab>`_'s ecosystem
* `pyjanitor <https://github.com/ericmjl/pyjanitor>`_
* `klio <https://github.com/spotify/klio>`_
Interrogate in the Wild
-----------------------
* `Why You Should Document Your Tests <https://hynek.me/articles/document-your-tests/>`_ by `Hynek Schlawack <https://twitter.com/hynek>`_
* `Episode #181: It's time to interrogate your Python code <https://pythonbytes.fm/episodes/show/181/it-s-time-to-interrogate-your-python-code>`_ - `PythonBytes podcast <https://pythonbytes.fm/>`_
.. end-uses-this
.. start-credits
Credits
=======
.. role:: smol
``interrogate`` was inspired by |docstr-coverage|_, which was forked from Alexey "DataGreed" Strelkov's |docstring-coverage|_, which was inspired by a 2004 `recipe from James Harlow <http://code.activestate.com/recipes/355731/>`_ :smol:`(turtles...)`.
The cute |sloth| logo is by `JustineW <https://thenounproject.com/wojcik.justine/>`_ purchased via `the Noun Project <https://thenounproject.com/>`_ (but also available under the `Creative Commons License <https://creativecommons.org/licenses/by/3.0/us/legalcode>`_ with attribution).
.. |interrogate-badge| image:: https://interrogate.readthedocs.io/en/latest/_static/interrogate_badge.svg
.. |flat-example| image:: https://interrogate.readthedocs.io/en/latest/_static/badge_examples/interrogate_badge_f.svg
.. |flat-square-example| image:: https://interrogate.readthedocs.io/en/latest/_static/badge_examples/interrogate_badge_fs.svg
.. |for-the-badge-example| image:: https://interrogate.readthedocs.io/en/latest/_static/badge_examples/interrogate_badge_ftb.svg
.. |plastic-example| image:: https://interrogate.readthedocs.io/en/latest/_static/badge_examples/interrogate_badge_p.svg
.. |social-example| image:: https://interrogate.readthedocs.io/en/latest/_static/badge_examples/interrogate_badge_s.svg
.. |sloth| image:: https://interrogate.readthedocs.io/en/latest/_static/logo_smol.png
.. |docstr-coverage| replace:: ``docstr-coverage``
.. _docstr-coverage: https://pypi.org/project/docstr-coverage
.. |docstring-coverage| replace:: ``docstring-coverage``
.. _docstring-coverage: https://bitbucket.org/DataGreed/docstring-coverage
.. end-credits
Release Information
===================
1.7.0 (2024-04-07)
------------------
Added
^^^^^
* `tomli` dependency for Python versions < 3.11, making use of `tomllib` in the standard library with 3.11+ (`#150 <https://github.com/econchick/interrogate/issues/150>`_).
* Support for ``pyi`` file extensions (and leave room for other file extensions to be added, like maybe ``ipynb``).
* Support for Google-style docstrings for class ``__init__`` methods with new ``--style [sphinx|google]`` flag (`#128 <https://github.com/econchick/interrogate/issues/128>`_).
Fixed
^^^^^
* Include support for deleters when ignoring property decorators (`#126 <https://github.com/econchick/interrogate/issues/126>_`).
* Support floats for `--fail-under` values (`#114 <https://github.com/econchick/interrogate/issues/114>`_).
Removed
^^^^^^^
* `toml` dependency for all Python versions (`#150 <https://github.com/econchick/interrogate/issues/150>`_).
`Full changelog <https://interrogate.readthedocs.io/en/latest/#changelog>`_.
Raw data
{
"_id": null,
"home_page": "https://interrogate.readthedocs.io",
"name": "interrogate",
"maintainer": "Lynn Root",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "lynn@lynnroot.com",
"keywords": "documentation, coverage, quality",
"author": "Lynn Root",
"author_email": "lynn@lynnroot.com",
"download_url": "https://files.pythonhosted.org/packages/8b/22/74f7fcc96280eea46cf2bcbfa1354ac31de0e60a4be6f7966f12cef20893/interrogate-1.7.0.tar.gz",
"platform": null,
"description": ".. image:: https://interrogate.readthedocs.io/en/latest/_static/logo_pink.png\n :alt: Pink Sloth Logo\n\n=================================\n``interrogate``: explain yourself\n=================================\n\n.. image:: https://interrogate.readthedocs.io/en/latest/_static/interrogate_badge.svg\n :target: https://github.com/econchick/interrogate\n :alt: Documentation Coverage\n\n.. image:: https://codecov.io/gh/econchick/interrogate/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/econchick/interrogate\n :alt: Testing Coverage\n\n.. image:: https://readthedocs.org/projects/interrogate/badge/?version=latest&style=flat\n :target: https://interrogate.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n\n.. image:: https://github.com/econchick/interrogate/workflows/CI/badge.svg?branch=master\n :target: https://github.com/econchick/interrogate/actions?workflow=CI\n :alt: CI Status\n\n.. start-readme\n\nInterrogate a codebase for docstring coverage.\n\nWhy Do I Need This?\n===================\n\n``interrogate`` checks your code base for missing docstrings.\n\nDocumentation should be as important as code itself. And it should live *within* code. Python `standardized <https://www.python.org/dev/peps/pep-0257/>`_ docstrings, allowing for developers to navigate libraries as simply as calling ``help()`` on objects, and with powerful tools like `Sphinx <https://www.sphinx-doc.org/en/master/>`_, `pydoc <https://docs.python.org/3/library/pydoc.html>`_, and `Docutils <https://docutils.sourceforge.io/>`_ to automatically generate HTML, LaTeX, PDFs, etc.\n\n*Enter:* ``interrogate``.\n\n``interrogate`` will tell you which methods, functions, classes, and modules have docstrings, and which do not. Use ``interrogate`` to:\n\n* Get an understanding of how well your code is documented;\n* Add it to CI/CD checks to enforce documentation on newly-added code;\n* Assess a new code base for (one aspect of) code quality and maintainability.\n\nLet's get started.\n\nRequirements\n============\n\n``interrogate`` supports Python 3.8 and above.\n\n\nInstallation\n============\n\n``interrogate`` is available on `PyPI <https://pypi.org/project/interrogate/>`_ and `GitHub <https://github.com/econchick/interrogate>`_. The recommended installation method is `pip <https://pip.pypa.io/en/stable/>`_-installing into a `virtualenv <https://hynek.me/articles/virtualenv-lives/>`_:\n\n.. code-block:: console\n\n $ pip install interrogate\n\nExtras\n------\n\n``interrogate`` provides a way to generate a `shields.io-like coverage badge <#other-usage>`_ as an **SVG file**.\nTo generate a **PNG file** instead, install ``interrogate`` with the extras ``[png]``:\n\n.. code-block:: console\n\n $ pip install interrogate[png]\n\n**NOTICE:** Additional system libraries/tools may be required in order to generate a PNG file of the coverage badge:\n\n* on Windows, install Visual C++ compiler for Cairo;\n* on macOS, install ``cairo`` and ``libffi`` (with Homebrew for example);\n* on Linux, install the ``cairo``, ``python3-dev`` and ``libffi-dev`` packages (names may vary depending on distribution).\n\nRefer to the ``cairosvg`` `documentation <https://cairosvg.org/documentation/>`_ for more information.\n\nUsage\n=====\n\nTry it out on a Python project:\n\n.. code-block:: console\n\n $ interrogate [PATH]\n RESULT: PASSED (minimum: 80.0%, actual: 100.0%)\n\n\nAdd verbosity to see a summary:\n\n.. code-block:: console\n\n $ interrogate -v [PATH]\n\n ================== Coverage for /Users/lynn/dev/interrogate/ ====================\n ------------------------------------ Summary ------------------------------------\n | Name | Total | Miss | Cover | Cover% |\n |---------------------------------------|---------|--------|---------|----------|\n | src/interrogate/__init__.py | 1 | 0 | 1 | 100% |\n | src/interrogate/__main__.py | 1 | 0 | 1 | 100% |\n | src/interrogate/badge_gen.py | 6 | 0 | 6 | 100% |\n | src/interrogate/cli.py | 2 | 0 | 2 | 100% |\n | src/interrogate/config.py | 8 | 0 | 8 | 100% |\n | src/interrogate/coverage.py | 27 | 0 | 27 | 100% |\n | src/interrogate/utils.py | 10 | 0 | 10 | 100% |\n | src/interrogate/visit.py | 18 | 0 | 18 | 100% |\n | tests/functional/__init__.py | 1 | 0 | 1 | 100% |\n | tests/functional/test_cli.py | 8 | 0 | 8 | 100% |\n | tests/functional/test_coverage.py | 10 | 0 | 10 | 100% |\n | tests/unit/__init__.py | 1 | 0 | 1 | 100% |\n | tests/unit/test_badge_gen.py | 8 | 0 | 8 | 100% |\n | tests/unit/test_config.py | 10 | 0 | 10 | 100% |\n | tests/unit/test_utils.py | 13 | 0 | 13 | 100% |\n |---------------------------------------|---------|--------|---------|----------|\n | TOTAL | 124 | 0 | 124 | 100.0% |\n ---------------- RESULT: PASSED (minimum: 80.0%, actual: 100.0%) ----------------\n\n\nAdd even *more* verbosity:\n\n\n.. code-block:: console\n\n $ interrogate -vv [PATH]\n\n ================== Coverage for /Users/lynn/dev/interrogate/ ====================\n ------------------------------- Detailed Coverage -------------------------------\n | Name | Status |\n |---------------------------------------------------------------------|---------|\n | src/interrogate/__init__.py (module) | COVERED |\n |---------------------------------------------------------------------|---------|\n | src/interrogate/__main__.py (module) | COVERED |\n |---------------------------------------------------------------------|---------|\n | src/interrogate/badge_gen.py (module) | COVERED |\n | save_badge (L42) | COVERED |\n | get_badge (L87) | COVERED |\n | should_generate_badge (L103) | COVERED |\n | get_color (L160) | COVERED |\n | create (L173) | COVERED |\n |---------------------------------------------------------------------|---------|\n | src/interrogate/cli.py (module) | COVERED |\n | main (L258) | COVERED |\n |---------------------------------------------------------------------|---------|\n | src/interrogate/config.py (module) | COVERED |\n | InterrogateConfig (L19) | COVERED |\n | find_project_root (L61) | COVERED |\n | find_project_config (L89) | COVERED |\n | parse_pyproject_toml (L100) | COVERED |\n | sanitize_list_values (L116) | COVERED |\n | parse_setup_cfg (L139) | COVERED |\n | read_config_file (L173) | COVERED |\n |---------------------------------------------------------------------|---------|\n | src/interrogate/coverage.py (module) | COVERED |\n | BaseInterrogateResult (L23) | COVERED |\n | BaseInterrogateResult.perc_covered (L37) | COVERED |\n | InterrogateFileResult (L54) | COVERED |\n | InterrogateFileResult.combine (L67) | COVERED |\n | InterrogateResults (L81) | COVERED |\n | InterrogateResults.combine (L93) | COVERED |\n | InterrogateCoverage (L101) | COVERED |\n | InterrogateCoverage._add_common_exclude (L121) | COVERED |\n | InterrogateCoverage._filter_files (L128) | COVERED |\n | InterrogateCoverage.get_filenames_from_paths (L141) | COVERED |\n | InterrogateCoverage._filter_nodes (L168) | COVERED |\n | InterrogateCoverage._filter_inner_nested (L194) | COVERED |\n | InterrogateCoverage._get_file_coverage (L203) | COVERED |\n | InterrogateCoverage._get_coverage (L231) | COVERED |\n | InterrogateCoverage.get_coverage (L248) | COVERED |\n | InterrogateCoverage._get_filename (L253) | COVERED |\n | InterrogateCoverage._get_detailed_row (L264) | COVERED |\n | InterrogateCoverage._create_detailed_table (L281) | COVERED |\n | InterrogateCoverage._create_detailed_table._sort_nodes (L288) | COVERED |\n | InterrogateCoverage._print_detailed_table (L315) | COVERED |\n | InterrogateCoverage._create_summary_table (L338) | COVERED |\n | InterrogateCoverage._print_summary_table (L381) | COVERED |\n | InterrogateCoverage._sort_results (L399) | COVERED |\n | InterrogateCoverage._get_header_base (L429) | COVERED |\n | InterrogateCoverage._print_omitted_file_count (L438) | COVERED |\n | InterrogateCoverage.print_results (L469) | COVERED |\n |---------------------------------------------------------------------|---------|\n | src/interrogate/utils.py (module) | COVERED |\n | parse_regex (L21) | COVERED |\n | smart_open (L40) | COVERED |\n | get_common_base (L60) | COVERED |\n | OutputFormatter (L80) | COVERED |\n | OutputFormatter.should_markup (L90) | COVERED |\n | OutputFormatter.set_detailed_markup (L105) | COVERED |\n | OutputFormatter.set_summary_markup (L129) | COVERED |\n | OutputFormatter._interrogate_line_formatter (L158) | COVERED |\n | OutputFormatter.get_table_formatter (L226) | COVERED |\n |---------------------------------------------------------------------|---------|\n | src/interrogate/visit.py (module) | COVERED |\n | CovNode (L15) | COVERED |\n | CoverageVisitor (L44) | COVERED |\n | CoverageVisitor._has_doc (L58) | COVERED |\n | CoverageVisitor._visit_helper (L65) | COVERED |\n | CoverageVisitor._is_nested_func (L112) | COVERED |\n | CoverageVisitor._is_nested_cls (L121) | COVERED |\n | CoverageVisitor._is_private (L133) | COVERED |\n | CoverageVisitor._is_semiprivate (L141) | COVERED |\n | CoverageVisitor._is_ignored_common (L151) | COVERED |\n | CoverageVisitor._has_property_decorators (L168) | COVERED |\n | CoverageVisitor._has_setters (L182) | COVERED |\n | CoverageVisitor._is_func_ignored (L193) | COVERED |\n | CoverageVisitor._is_class_ignored (L217) | COVERED |\n | CoverageVisitor.visit_Module (L221) | COVERED |\n | CoverageVisitor.visit_ClassDef (L228) | COVERED |\n | CoverageVisitor.visit_FunctionDef (L237) | COVERED |\n | CoverageVisitor.visit_AsyncFunctionDef (L246) | COVERED |\n |---------------------------------------------------------------------|---------|\n | tests/functional/__init__.py (module) | COVERED |\n |---------------------------------------------------------------------|---------|\n | tests/functional/test_cli.py (module) | COVERED |\n | runner (L22) | COVERED |\n | test_run_no_paths (L30) | COVERED |\n | test_run_shortflags (L77) | COVERED |\n | test_run_longflags (L106) | COVERED |\n | test_run_multiple_flags (L124) | COVERED |\n | test_generate_badge (L135) | COVERED |\n | test_incompatible_options (L170) | COVERED |\n |---------------------------------------------------------------------|---------|\n | tests/functional/test_coverage.py (module) | COVERED |\n | test_coverage_simple (L60) | COVERED |\n | test_coverage_errors (L73) | COVERED |\n | test_print_results (L101) | COVERED |\n | test_print_results_omit_covered (L130) | COVERED |\n | test_print_results_omit_none (L156) | COVERED |\n | test_print_results_omit_all_summary (L174) | COVERED |\n | test_print_results_omit_all_detailed (L198) | COVERED |\n | test_print_results_ignore_module (L226) | COVERED |\n | test_print_results_single_file (L253) | COVERED |\n |---------------------------------------------------------------------|---------|\n | tests/unit/__init__.py (module) | COVERED |\n |---------------------------------------------------------------------|---------|\n | tests/unit/test_badge_gen.py (module) | COVERED |\n | test_save_badge (L26) | COVERED |\n | test_save_badge_windows (L50) | COVERED |\n | test_save_badge_no_cairo (L62) | COVERED |\n | test_get_badge (L73) | COVERED |\n | test_should_generate (L96) | COVERED |\n | test_get_color (L115) | COVERED |\n | test_create (L136) | COVERED |\n |---------------------------------------------------------------------|---------|\n | tests/unit/test_config.py (module) | COVERED |\n | test_find_project_root (L29) | COVERED |\n | test_find_project_config (L48) | COVERED |\n | test_parse_pyproject_toml (L57) | COVERED |\n | test_sanitize_list_values (L93) | COVERED |\n | test_parse_setup_cfg (L98) | COVERED |\n | test_parse_setup_cfg_raises (L123) | COVERED |\n | test_read_config_file_none (L134) | COVERED |\n | test_read_config_file (L193) | COVERED |\n | test_read_config_file_raises (L207) | COVERED |\n |---------------------------------------------------------------------|---------|\n | tests/unit/test_utils.py (module) | COVERED |\n | test_parse_regex (L32) | COVERED |\n | test_smart_open (L39) | COVERED |\n | test_get_common_base (L69) | COVERED |\n | test_get_common_base_windows (L100) | COVERED |\n | test_output_formatter_should_markup (L132) | COVERED |\n | test_output_formatter_set_detailed_markup (L163) | COVERED |\n | test_output_formatter_set_summary_markup (L206) | COVERED |\n | test_output_formatter_interrogate_line_formatter (L258) | COVERED |\n | test_output_formatter_interrogate_line_formatter_windows (L319) | COVERED |\n | test_output_formatter_get_table_formatter (L343) | COVERED |\n | test_output_formatter_get_table_formatter_py38 (L381) | COVERED |\n | test_output_formatter_get_table_formatter_raises (L395) | COVERED |\n |---------------------------------------------------------------------|---------|\n\n ------------------------------------ Summary ------------------------------------\n | Name | Total | Miss | Cover | Cover% |\n |---------------------------------------|---------|--------|---------|----------|\n | src/interrogate/__init__.py | 1 | 0 | 1 | 100% |\n | src/interrogate/__main__.py | 1 | 0 | 1 | 100% |\n | src/interrogate/badge_gen.py | 6 | 0 | 6 | 100% |\n | src/interrogate/cli.py | 2 | 0 | 2 | 100% |\n | src/interrogate/config.py | 8 | 0 | 8 | 100% |\n | src/interrogate/coverage.py | 27 | 0 | 27 | 100% |\n | src/interrogate/utils.py | 10 | 0 | 10 | 100% |\n | src/interrogate/visit.py | 18 | 0 | 18 | 100% |\n | tests/functional/__init__.py | 1 | 0 | 1 | 100% |\n | tests/functional/test_cli.py | 8 | 0 | 8 | 100% |\n | tests/functional/test_coverage.py | 10 | 0 | 10 | 100% |\n | tests/unit/__init__.py | 1 | 0 | 1 | 100% |\n | tests/unit/test_badge_gen.py | 8 | 0 | 8 | 100% |\n | tests/unit/test_config.py | 10 | 0 | 10 | 100% |\n | tests/unit/test_utils.py | 13 | 0 | 13 | 100% |\n |---------------------------------------|---------|--------|---------|----------|\n | TOTAL | 124 | 0 | 124 | 100.0% |\n ---------------- RESULT: PASSED (minimum: 80.0%, actual: 100.0%) ----------------\n\nOther Usage\n===========\n\nGenerate a `shields.io <https://shields.io/>`_ badge (like this one! |interrogate-badge| ):\n\n.. code-block:: console\n\n $ interrogate --generate-badge PATH\n RESULT: PASSED (minimum: 80.0%, actual: 100.0%)\n Generated badge to /Users/lynn/dev/interrogate/docs/_static/interrogate_badge.svg\n\n`See below <#badge-options>`_ for more badge configuration.\n\nAdd it to your ``tox.ini`` file to enforce a level of coverage:\n\n.. code-block:: ini\n\n [testenv:doc]\n deps = interrogate\n skip_install = true\n commands =\n interrogate --quiet --fail-under 95 src tests\n\nOr use it with `pre-commit <https://pre-commit.com/>`_:\n\n.. code-block:: yaml\n\n repos:\n - repo: https://github.com/econchick/interrogate\n rev: 1.7.0 # or master if you're bold\n hooks:\n - id: interrogate\n args: [--quiet, --fail-under=95]\n pass_filenames: false # needed if excluding files with pyproject.toml or setup.cfg\n\nUse it within your code directly:\n\n.. code-block:: pycon\n\n >>> from interrogate import coverage\n >>> cov = coverage.InterrogateCoverage(paths=[\"src\"])\n >>> results = cov.get_coverage()\n >>> results\n InterrogateResults(total=68, covered=65, missing=3)\n\n\nUse ``interrogate`` with `GitHub Actions <https://github.com/features/actions>`_. Check out the `action <https://github.com/marketplace/actions/python-interrogate-check>`_ written & maintained by `Jack McKew <https://github.com/JackMcKew>`_ (thank you, Jack!).\n\nOr use ``interrogate`` in VSCode with the `interrogate extension <https://marketplace.visualstudio.com/items?itemName=kennethlove.interrogate>`_ written & maintained by `Kenneth Love <https://thekennethlove.com/>`_ (thank you, Kenneth!).\n\nConfiguration\n=============\n\nConfigure within your ``pyproject.toml`` (``interrogate`` will automatically detect a ``pyproject.toml`` file and pick up default values for the command line options):\n\n.. code-block:: console\n\n $ interrogate -c pyproject.toml [OPTIONS] [PATHS]...\n\n.. code-block:: toml\n\n [tool.interrogate]\n ignore-init-method = true\n ignore-init-module = false\n ignore-magic = false\n ignore-semiprivate = false\n ignore-private = false\n ignore-property-decorators = false\n ignore-module = false\n ignore-nested-functions = false\n ignore-nested-classes = true\n ignore-setters = false\n ignore-overloaded-functions = false\n fail-under = 95\n exclude = [\"setup.py\", \"docs\", \"build\"]\n ignore-regex = [\"^get$\", \"^mock_.*\", \".*BaseClass.*\"]\n ext = []\n # possible values: sphinx (default), google\n style = sphinx\n # possible values: 0 (minimal output), 1 (-v), 2 (-vv)\n verbose = 0\n quiet = false\n whitelist-regex = []\n color = true\n omit-covered-files = false\n generate-badge = \".\"\n badge-format = \"svg\"\n\n\nOr configure within your ``setup.cfg`` (``interrogate`` will automatically detect a ``setup.cfg`` file and pick up default values for the command line options):\n\n.. code-block:: console\n\n $ interrogate -c setup.cfg [OPTIONS] [PATHS]...\n\n.. code-block:: ini\n\n [tool:interrogate]\n ignore-init-method = true\n ignore-init-module = false\n ignore-magic = false\n ignore-semiprivate = false\n ignore-private = false\n ignore-property-decorators = false\n ignore-module = false\n ignore-nested-functions = false\n ignore-nested-classes = true\n ignore-setters = false\n ignore-overloaded-functions = false\n fail-under = 95\n exclude = setup.py,docs,build\n ignore-regex = ^get$,^mock_.*,.*BaseClass.*\n ext = []\n ; possible values: sphinx (default), google\n style = sphinx\n ; possible values: 0 (minimal output), 1 (-v), 2 (-vv)\n verbose = 0\n quiet = false\n whitelist-regex =\n color = true\n omit-covered-files = false\n generate-badge = .\n badge-format = svg\n\n\n.. warning::\n\n The use of ``setup.cfg`` is not recommended unless for very simple use cases. ``.cfg`` files use a different parser than ``pyproject.toml`` which might cause hard to track down problems. When possible, it is recommended to use ``pyproject.toml`` to define your interrogate configuration.\n\n.. _badge-opts:\n\nBadge Options\n=============\n\nBadge Format\n------------\n\nThe default file format is ``svg``. Use the ``--badge-format`` flag to create a ``png`` file instead.\n**Note**: ``interrogate`` must be installed with ``interrogate[png]`` in order to generate ``png`` files (see `above <#extras>`_).\n\n.. code-block:: console\n\n $ interrogate --generate-badge PATH --badge-format png\n RESULT: PASSED (minimum: 80.0%, actual: 100.0%)\n Generated badge to /Users/lynn/dev/interrogate/docs/_static/interrogate_badge.png\n\nBadge Style\n-----------\n\nThe following badge styles are available via the ``--badge-style`` flag:\n\n+------------------------------------+--------------------------------+\n| option | example |\n+====================================+================================+\n| ``flat`` | |flat-example| |\n+------------------------------------+--------------------------------+\n| ``flat-square`` | |flat-square-example| |\n+------------------------------------+--------------------------------+\n| ``flat-square-modified`` (default) | |interrogate-badge| |\n+------------------------------------+--------------------------------+\n| ``for-the-badge`` | |for-the-badge-example| |\n+------------------------------------+--------------------------------+\n| ``plastic`` | |plastic-example| |\n+------------------------------------+--------------------------------+\n| ``social`` | |social-example| |\n+------------------------------------+--------------------------------+\n\n.. end-readme\n\nCommand Line Options\n====================\n\nTo view all options available, run ``interrogate --help``:\n\n.. code-block:: console\n\n interrogate -h\n Usage: interrogate [OPTIONS] [PATHS]...\n\n Measure and report on documentation coverage in Python modules.\n\n Options:\n --version Show the version and exit.\n -v, --verbose Level of verbosity.\n\n NOTE: When configuring verbosity in\n pyproject.toml or setup.cfg, `verbose=1`\n maps to `-v`, and `verbose=2` maps to `-vv`.\n `verbose=0` is the equivalent of no verbose\n flags used, producing minimal output.\n -q, --quiet Do not print output [default: False]\n -f, --fail-under INT | FLOAT Fail when coverage % is less than a given\n amount. [default: 80.0]\n\n -e, --exclude PATH Exclude PATHs of files and/or directories.\n Multiple `-e/--exclude` invocations\n supported.\n\n -i, --ignore-init-method Ignore `__init__` method of classes.\n [default: False]\n\n -I, --ignore-init-module Ignore `__init__.py` modules. [default:\n False]\n\n -m, --ignore-magic Ignore all magic methods of classes.\n [default: False]\n\n NOTE: This does not include the `__init__`\n method. To ignore `__init__` methods, use\n `--ignore-init-method`.\n\n -M, --ignore-module Ignore module-level docstrings. [default:\n False]\n\n -n, --ignore-nested-functions Ignore nested functions and methods.\n [default: False]\n\n -C, --ignore-nested-classes Ignore nested classes. [default: False]\n\n -O, --ignore-overloaded-functions\n Ignore `@typing.overload`-decorated functions.\n [default: False]\n\n -p, --ignore-private Ignore private classes, methods, and\n functions starting with two underscores.\n [default: False]\n\n NOTE: This does not include magic methods;\n use `--ignore-magic` and/or `--ignore-init-\n method` instead.\n\n -P, --ignore-property-decorators\n Ignore methods with property setter/getter/deleter\n decorators. [default: False]\n\n -S, --ignore-setters Ignore methods with property setter\n decorators. [default: False]\n\n -s, --ignore-semiprivate Ignore semiprivate classes, methods, and\n functions starting with a single underscore.\n [default: False]\n\n -r, --ignore-regex STR Regex identifying class, method, and\n function names to ignore. Multiple\n `-r/--ignore-regex` invocations supported.\n\n --ext Include Python-like files with the given\n extension (supported: ``pyi``). Multiple\n `--ext` invocations supported.\n\n -w, --whitelist-regex STR Regex identifying class, method, and\n function names to include. Multiple\n `-w/--whitelist-regex` invocations\n supported.\n\n --style [sphinx|google] Style of docstrings to honor. Using `google`\n will consider a class and its `__init__`\n method both covered if there is either a\n class-level docstring, or an `__init__`\n method docstring, instead of enforcing both.\n Mutually exclusive with `-i`/`--ignore-init`\n flag. [default: sphinx]\n\n -o, --output FILE Write output to a given FILE. [default:\n stdout]\n\n --color / --no-color Toggle color output on/off when printing to\n stdout. [default: True]\n\n --omit-covered-files Omit reporting files that have 100%\n documentation coverage. This option is\n ignored if verbosity is not set. [default:\n False]\n\n -g, --generate-badge PATH Generate a 'shields.io' status badge (an SVG\n image) in at a given file or directory. Will\n not generate a badge if results did not\n change from an existing badge of the same\n path.\n\n --badge-format [svg|png] File format for the generated badge. Used\n with the `-g/--generate-badge` flag.\n [default: svg]\n\n NOTE: To generate a PNG file, interrogate\n must be installed with `interrogate[png]`,\n i.e. `pip install interrogate[png]`.\n\n --badge-style [flat|flat-square|flat-square-modified|for-the-badge|plastic|social]\n Desired style of shields.io badge. Used with\n the `-g/--generate-badge` flag. [default:\n flat-square-modified]\n\n -h, --help Show this message and exit.\n -c, --config FILE Read configuration from `pyproject.toml` or\n `setup.cfg`.\n\n\n.. start-uses-this\n\nUsers of Interrogate\n====================\n\n* `attrs <https://github.com/python-attrs/attrs>`_\n* `OpenMMLab <https://github.com/open-mmlab>`_'s ecosystem\n* `pyjanitor <https://github.com/ericmjl/pyjanitor>`_\n* `klio <https://github.com/spotify/klio>`_\n\nInterrogate in the Wild\n-----------------------\n\n* `Why You Should Document Your Tests <https://hynek.me/articles/document-your-tests/>`_ by `Hynek Schlawack <https://twitter.com/hynek>`_\n* `Episode #181: It's time to interrogate your Python code <https://pythonbytes.fm/episodes/show/181/it-s-time-to-interrogate-your-python-code>`_ - `PythonBytes podcast <https://pythonbytes.fm/>`_\n\n.. end-uses-this\n\n.. start-credits\n\nCredits\n=======\n\n.. role:: smol\n\n``interrogate`` was inspired by |docstr-coverage|_, which was forked from Alexey \"DataGreed\" Strelkov's |docstring-coverage|_, which was inspired by a 2004 `recipe from James Harlow <http://code.activestate.com/recipes/355731/>`_ :smol:`(turtles...)`.\n\nThe cute |sloth| logo is by `JustineW <https://thenounproject.com/wojcik.justine/>`_ purchased via `the Noun Project <https://thenounproject.com/>`_ (but also available under the `Creative Commons License <https://creativecommons.org/licenses/by/3.0/us/legalcode>`_ with attribution).\n\n\n.. |interrogate-badge| image:: https://interrogate.readthedocs.io/en/latest/_static/interrogate_badge.svg\n.. |flat-example| image:: https://interrogate.readthedocs.io/en/latest/_static/badge_examples/interrogate_badge_f.svg\n.. |flat-square-example| image:: https://interrogate.readthedocs.io/en/latest/_static/badge_examples/interrogate_badge_fs.svg\n.. |for-the-badge-example| image:: https://interrogate.readthedocs.io/en/latest/_static/badge_examples/interrogate_badge_ftb.svg\n.. |plastic-example| image:: https://interrogate.readthedocs.io/en/latest/_static/badge_examples/interrogate_badge_p.svg\n.. |social-example| image:: https://interrogate.readthedocs.io/en/latest/_static/badge_examples/interrogate_badge_s.svg\n.. |sloth| image:: https://interrogate.readthedocs.io/en/latest/_static/logo_smol.png\n\n.. |docstr-coverage| replace:: ``docstr-coverage``\n.. _docstr-coverage: https://pypi.org/project/docstr-coverage\n.. |docstring-coverage| replace:: ``docstring-coverage``\n.. _docstring-coverage: https://bitbucket.org/DataGreed/docstring-coverage\n\n.. end-credits\n\nRelease Information\n===================\n\n1.7.0 (2024-04-07)\n------------------\n\nAdded\n^^^^^\n\n* `tomli` dependency for Python versions < 3.11, making use of `tomllib` in the standard library with 3.11+ (`#150 <https://github.com/econchick/interrogate/issues/150>`_).\n* Support for ``pyi`` file extensions (and leave room for other file extensions to be added, like maybe ``ipynb``).\n* Support for Google-style docstrings for class ``__init__`` methods with new ``--style [sphinx|google]`` flag (`#128 <https://github.com/econchick/interrogate/issues/128>`_).\n\nFixed\n^^^^^\n\n* Include support for deleters when ignoring property decorators (`#126 <https://github.com/econchick/interrogate/issues/126>_`).\n* Support floats for `--fail-under` values (`#114 <https://github.com/econchick/interrogate/issues/114>`_).\n\nRemoved\n^^^^^^^\n\n* `toml` dependency for all Python versions (`#150 <https://github.com/econchick/interrogate/issues/150>`_).\n\n\n`Full changelog <https://interrogate.readthedocs.io/en/latest/#changelog>`_.\n",
"bugtrack_url": null,
"license": null,
"summary": "Interrogate a codebase for docstring coverage.",
"version": "1.7.0",
"project_urls": {
"Bug Tracker": "https://github.com/econchick/interrogate/issues",
"Documentation": "https://interrogate.readthedocs.io",
"Homepage": "https://interrogate.readthedocs.io",
"Source Code": "https://github.com/econchick/interrogate"
},
"split_keywords": [
"documentation",
" coverage",
" quality"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "12c96869a1dcf4aaf309b9543ec070be3ec3adebee7c9bec9af8c230494134b9",
"md5": "79a89ce732b57fc7563c9f04c81f0135",
"sha256": "b13ff4dd8403369670e2efe684066de9fcb868ad9d7f2b4095d8112142dc9d12"
},
"downloads": -1,
"filename": "interrogate-1.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "79a89ce732b57fc7563c9f04c81f0135",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 46982,
"upload_time": "2024-04-07T22:30:44",
"upload_time_iso_8601": "2024-04-07T22:30:44.277143Z",
"url": "https://files.pythonhosted.org/packages/12/c9/6869a1dcf4aaf309b9543ec070be3ec3adebee7c9bec9af8c230494134b9/interrogate-1.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8b2274f7fcc96280eea46cf2bcbfa1354ac31de0e60a4be6f7966f12cef20893",
"md5": "0097042f229339942e77072ee33591c3",
"sha256": "a320d6ec644dfd887cc58247a345054fc4d9f981100c45184470068f4b3719b0"
},
"downloads": -1,
"filename": "interrogate-1.7.0.tar.gz",
"has_sig": false,
"md5_digest": "0097042f229339942e77072ee33591c3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 159636,
"upload_time": "2024-04-07T22:30:46",
"upload_time_iso_8601": "2024-04-07T22:30:46.217966Z",
"url": "https://files.pythonhosted.org/packages/8b/22/74f7fcc96280eea46cf2bcbfa1354ac31de0e60a4be6f7966f12cef20893/interrogate-1.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-07 22:30:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "econchick",
"github_project": "interrogate",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "interrogate"
}
JSON
