Package: interrogate
interrogate: explain yourselfInterrogate a codebase for docstring coverage.Why Do I Need This?interrogatechecks your code base for missing docstrings.Documentation should be as important as code itself. And it should livewithincode. Pythonstandardizeddocstrings, allowing for developers to navigate libraries as simply as callinghelp()on objects, and with powerful tools likeSphinx,pydoc, andDocutilsto automatically generate HTML, LaTeX, PDFs, etc.Enter:interrogate.interrogatewill tell you which methods, functions, classes, and modules have docstrings, and which do not. Useinterrogateto: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.Requirementsinterrogatesupports Python 3.6 and above.Installationinterrogateis available onPyPIandGitHub. The recommended installation method ispip-installing into avirtualenv:$pipinstallinterrogateExtrasinterrogateprovides a way to generate ashields.io-like coverage badgeas anSVG file.
To generate aPNG fileinstead, installinterrogatewith the extras[png]:$pipinstallinterrogate[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, installcairoandlibffi(with Homebrew for example);on Linux, install thecairo,python3-devandlibffi-devpackages (names may vary depending on distribution).Refer to thecairosvgdocumentationfor more information.UsageTry it out on a Python project:$interrogate[PATH]RESULT: PASSED (minimum: 80.0%, actual: 100.0%)Add verbosity to see a summary:$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 evenmoreverbosity:$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 UsageGenerate ashields.iobadge (like this one!):$interrogate--generate-badgePATHRESULT: PASSED (minimum: 80.0%, actual: 100.0%)
Generated badge to /Users/lynn/dev/interrogate/docs/_static/interrogate_badge.svgSee belowfor more badge configuration.Add it to yourtox.inifile to enforce a level of coverage:[testenv:doc]deps=interrogateskip_install=truecommands=interrogate --quiet --fail-under 95 src testsOr use it withpre-commit:repos:-repo:https://github.com/econchick/interrogaterev:1.5.0# or master if you're boldhooks:-id:interrogateargs:[--quiet,--fail-under=95]Use it within your code directly:>>>frominterrogateimportcoverage>>>cov=coverage.InterrogateCoverage(paths=["src"])>>>results=cov.get_coverage()>>>resultsInterrogateResults(total=68, covered=65, missing=3)UseinterrogatewithGitHub Actions. Check out theactionwritten & maintained byJack McKew(thank you, Jack!).ConfigurationConfigure within yourpyproject.toml(interrogatewill automatically detect apyproject.tomlfile and pick up default values for the command line options):$interrogate-cpyproject.toml[OPTIONS][PATHS]...[tool.interrogate]ignore-init-method=trueignore-init-module=falseignore-magic=falseignore-semiprivate=falseignore-private=falseignore-property-decorators=falseignore-module=falseignore-nested-functions=falseignore-nested-classes=trueignore-setters=falsefail-under=95exclude=["setup.py","docs","build"]ignore-regex=["^get$","^mock_.*",".*BaseClass.*"]# possible values: 0 (minimal output), 1 (-v), 2 (-vv)verbose=0quiet=falsewhitelist-regex=[]color=trueomit-covered-files=falsegenerate-badge="."badge-format="svg"Or configure within yoursetup.cfg(interrogatewill automatically detect asetup.cfgfile and pick up default values for the command line options):$interrogate-csetup.cfg[OPTIONS][PATHS]...[tool:interrogate]ignore-init-method=trueignore-init-module=falseignore-magic=falseignore-semiprivate=falseignore-private=falseignore-property-decorators=falseignore-module=falseignore-nested-functions=falseignore-nested-classes=trueignore-setters=falsefail-under=95exclude=setup.py,docs,buildignore-regex=^get$,^mock_.*,.*BaseClass.*; possible values: 0 (minimal output), 1 (-v), 2 (-vv)verbose=0quiet=falsewhitelist-regex=color=trueomit-covered-files=falsegenerate-badge=.badge-format=svgWarningThe use ofsetup.cfgis not recommended unless for very simple use cases..cfgfiles use a different parser thanpyproject.tomlwhich might cause hard to track down problems. When possible, it is recommended to usepyproject.tomlto define your interrogate configuration.Badge OptionsBadge FormatThe default file format issvg. Use the--badge-formatflag to create apngfile instead.Note:interrogatemust be installed withinterrogate[png]in order to generatepngfiles (seeabove).$interrogate--generate-badgePATH--badge-formatpngRESULT: PASSED (minimum: 80.0%, actual: 100.0%)
Generated badge to /Users/lynn/dev/interrogate/docs/_static/interrogate_badge.pngBadge StyleThe following badge styles are available via the--badge-styleflag:optionexampleflatflat-squareflat-square-modified(default)for-the-badgeplasticsocialTo view all options available, runinterrogate--help: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]

  -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
                                  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.

  -w, --whitelist-regex STR       Regex identifying class, method, and
                                  function names to include. Multiple
                                  `-w/--whitelist-regex` invocations
                                  supported.

  -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`.Users of InterrogateattrsOpenMMLab’s ecosystempyjanitorklioInterrogate in the WildWhy You Should Document Your TestsbyHynek SchlawackEpisode #181: It’s time to interrogate your Python code-PythonBytes podcastCreditsinterrogatewas inspired bydocstr-coverage, which was forked from Alexey “DataGreed” Strelkov’sdocstring-coverage, which was inspired by a 2004recipe from James Harlow(turtles…).The cutelogo is byJustineWpurchased viathe Noun Project(but also available under theCreative Commons Licensewith attribution).Release Information1.5.0 (2021-09-10)AddedSet minimumclickversion (thank you bildzeitung!#81,#82).Add--omit-covered-filesflag to skip reporting fully-covered files (#85).Add support for different badge styles via new--badge-styleflag (#86).Add 3.10 support!FixedClarifyverboseconfiguration (#83).Full changelog.