docstr_coverage package

Submodules

docstr_coverage.coverage module

The central module for coverage collection and file-walking

docstr_coverage.coverage.analyze(filenames: list, ignore_config: docstr_coverage.ignore_config.IgnoreConfig = <docstr_coverage.ignore_config.IgnoreConfig object>, show_progress=True) → docstr_coverage.result_collection.ResultCollection

EXPERIMENTAL: More expressive alternative to get_docstring_coverage.

Checks contents of filenames for missing docstrings, and produces a report detailing

docstring status

Note that this method, as well as its parameters and return types

are still experimental and may change in future versions.

filenames: List

List of filename strings that are absolute or relative paths

ignore_config: IgnoreConfig

Information about which docstrings are to be ignored

show_progress: Boolean, default=True

If True, prints a progress bar to stdout

Returns:The collected information about docstring presence Return type:ResultCollection

docstr_coverage.coverage.get_docstring_coverage(filenames: list, skip_magic: bool = False, skip_file_docstring: bool = False, skip_init: bool = False, skip_class_def: bool = False, skip_private: bool = False, verbose: int = 0, ignore_names: Tuple[List[str], ...] = ()) → Tuple[Dict, Dict]

Checks contents of filenames for missing docstrings, and produces a report detailing docstring status.

Note: For a method with a more expressive return type, you may want to try the experimental docstr_coverage.analyze function.

Parameters:

• filenames (List) – List of filename strings that are absolute or relative paths
• skip_magic (Boolean, default=False) – If True, skips all magic methods (double-underscore-prefixed), except ‘__init__’ and does not include them in the report
• skip_file_docstring (Boolean, default=False) – If True, skips check for a module-level docstring
• skip_init (Boolean, default=False) – If True, skips methods named ‘__init__’ and does not include them in the report
• skip_class_def (Boolean, default=False) – If True, skips class definitions and does not include them in the report. If this is True, the class’s methods will still be checked
• skip_private (Boolean, default=False) – If True, skips function definitions beginning with a single underscore and does not include them in the report.
• verbose (Int in [0, 1, 2, 3], default=0) –
  0. No printing.
  1. Print total stats only.
  2. Print stats for all files.
  3. Print missing docstrings for all files.
• ignore_names (Tuple[List[str], ..], default=()) – Patterns to ignore when checking documentation. Each list in ignore_names defines a different pattern to be ignored. The first element in each list is the regular expression for matching filenames. All remaining arguments in each list are regexes for matching names of functions/classes. A node is ignored if it matches the filename regex and at least one of the remaining regexes

Returns:

• Dict – Links filename keys to a dict of stats for that filename. Example:

  >>> {
  ...     '<filename>': {
  ...         'missing': ['<method_or_class_name>', '...'],
  ...         'module_doc': '<Boolean>',
  ...         'missing_count': '<missing_count int>',
  ...         'needed_count': '<needed_docstrings_count int>',
  ...         'coverage': '<percent_of_coverage float>',
  ...         'empty': '<Boolean>'
  ...     }, ...
  ... }
  

• Dict – Total summary stats for all files analyzed. Example:

  >>> {
  ...     'missing_count': '<total_missing_count int>',
  ...     'needed_count': '<total_needed_docstrings_count int>',
  ...     'coverage': '<total_percent_of_coverage float>'
  ... }
  

Module contents

docstr_coverage.analyze(filenames: list, ignore_config: docstr_coverage.ignore_config.IgnoreConfig = <docstr_coverage.ignore_config.IgnoreConfig object>, show_progress=True) → docstr_coverage.result_collection.ResultCollection

EXPERIMENTAL: More expressive alternative to get_docstring_coverage.

Checks contents of filenames for missing docstrings, and produces a report detailing

docstring status

Note that this method, as well as its parameters and return types

are still experimental and may change in future versions.

filenames: List

List of filename strings that are absolute or relative paths

ignore_config: IgnoreConfig

Information about which docstrings are to be ignored

show_progress: Boolean, default=True

If True, prints a progress bar to stdout

Returns:The collected information about docstring presence Return type:ResultCollection

docstr_coverage.get_docstring_coverage(filenames: list, skip_magic: bool = False, skip_file_docstring: bool = False, skip_init: bool = False, skip_class_def: bool = False, skip_private: bool = False, verbose: int = 0, ignore_names: Tuple[List[str], ...] = ()) → Tuple[Dict, Dict]

Checks contents of filenames for missing docstrings, and produces a report detailing docstring status.

Note: For a method with a more expressive return type, you may want to try the experimental docstr_coverage.analyze function.

Parameters:

• filenames (List) – List of filename strings that are absolute or relative paths
• skip_magic (Boolean, default=False) – If True, skips all magic methods (double-underscore-prefixed), except ‘__init__’ and does not include them in the report
• skip_file_docstring (Boolean, default=False) – If True, skips check for a module-level docstring
• skip_init (Boolean, default=False) – If True, skips methods named ‘__init__’ and does not include them in the report
• skip_class_def (Boolean, default=False) – If True, skips class definitions and does not include them in the report. If this is True, the class’s methods will still be checked
• skip_private (Boolean, default=False) – If True, skips function definitions beginning with a single underscore and does not include them in the report.
• verbose (Int in [0, 1, 2, 3], default=0) –
  0. No printing.
  1. Print total stats only.
  2. Print stats for all files.
  3. Print missing docstrings for all files.
• ignore_names (Tuple[List[str], ..], default=()) – Patterns to ignore when checking documentation. Each list in ignore_names defines a different pattern to be ignored. The first element in each list is the regular expression for matching filenames. All remaining arguments in each list are regexes for matching names of functions/classes. A node is ignored if it matches the filename regex and at least one of the remaining regexes

Returns:

• Dict – Links filename keys to a dict of stats for that filename. Example:

  >>> {
  ...     '<filename>': {
  ...         'missing': ['<method_or_class_name>', '...'],
  ...         'module_doc': '<Boolean>',
  ...         'missing_count': '<missing_count int>',
  ...         'needed_count': '<needed_docstrings_count int>',
  ...         'coverage': '<percent_of_coverage float>',
  ...         'empty': '<Boolean>'
  ...     }, ...
  ... }
  

• Dict – Total summary stats for all files analyzed. Example:

  >>> {
  ...     'missing_count': '<total_missing_count int>',
  ...     'needed_count': '<total_needed_docstrings_count int>',
  ...     'coverage': '<total_percent_of_coverage float>'
  ... }
  

class docstr_coverage.IgnoreConfig(ignore_names: Tuple[List[str], ...] = (), skip_magic: bool = False, skip_file_docstring: bool = False, skip_init: bool = False, skip_class_def: bool = False, skip_private: bool = False, skip_property: bool = False, skip_setter: bool = True, skip_deleter: bool = True)

Bases: object

Data class storing information about docstring types to ignore when aggregating coverage

ignore_names

Patterns to ignore when checking documentation. Each list in ignore_names defines a different pattern to be ignored. The first element in each list is the regular expression for matching filenames. All remaining arguments in each list are regexes for matching names of functions/classes. A node is ignored if it matches the filename regex and at least one of the remaining regexes

skip_class_def

If True, skip class definition docstrings and exclude them from the report. If this is True, the class’s methods will still be checked

skip_deleter

If True, skip nodes with @deleter decorator.

skip_file_docstring

If True, skip check for a module-level docstring

skip_init

If True, skip methods named __init__ and exclude them from the report

skip_magic

If True, skip all magic methods (methods with both leading and trailing double underscores), except __init__ and exclude them from the report

skip_private

If True, skip function definitions beginning with a single underscore.

skip_property

If True, skip nodes with @property decorator.

skip_setter

If True, skip nodes with @setter decorator.

class docstr_coverage.LegacyPrinter(verbosity: int, ignore_config: docstr_coverage.ignore_config.IgnoreConfig = <docstr_coverage.ignore_config.IgnoreConfig object>)

Bases: object

Printing functionality consistent with the original early-versions docstr-coverage outputs.

In future versions, the interface of this class will be refined and an abstract superclass will be extracted. Thus, coding against the current interface will require refactorings with future versions of docstr-coverage.

print(results)

Prints a provided set of results to stdout.

Parameters:results (ResultCollection) – The information about docstr presence to be printed to stdout.

class docstr_coverage.ResultCollection

Bases: object

A result collection contains information about the presence of docstrings collected during the walk through the files. From the ResultCollection, information about missing docstrings for inspected files can be retrieved, and summary metrics (e.g. coverage) can be extracted without having to walk over the files again.

count_aggregate()

Walks through all the tracked files in this result collection, and counts overall statistics, such as #missing docstring.

Returns:A count instance containing a range of docstring counts. Return type:AggregatedCount

files()

View of all (file-name, file-info) tuples in this result collection

get_file(file_path)

Provides access to the docstring information for specific files. This primarily targets information collection phase (thus the docstr-coverage internal process).

If no file with the provided name is on record yet, a new empty File information instance is created and returned.

Parameters:file_path (String) – The path of the file for which the information is requested. Returns:The file (information) instance used to track docstring information Return type:File

to_legacy()

Converts the information in this ResultCollection into the less expressive dictionary of counts used since the early versions of docstr-coverage.

Returns:

• Dict – Links filename keys to a dict of stats for that filename. Example:

  >>> {
  ...     '<filename>': {
  ...         'missing': ['<method_or_class_name>', '...'],
  ...         'module_doc': '<Boolean>',
  ...         'missing_count': '<missing_count int>',
  ...         'needed_count': '<needed_docstrings_count int>',
  ...         'coverage': '<percent_of_coverage float>',
  ...         'empty': '<Boolean>'
  ...     }, ...
  ... }
  

• Dict – Total summary stats for all files analyzed. Example:

  >>> {
  ...     'missing_count': '<total_missing_count int>',
  ...     'needed_count': '<total_needed_docstrings_count int>',
  ...     'coverage': '<total_percent_of_coverage float>'
  ... }
  

class docstr_coverage.AggregatedCount(num_files: int = 0, num_empty_files: int = 0, needed: int = 0, found: int = 0, missing: int = 0)

Bases: docstr_coverage.result_collection._DocstrCount

Counts of docstrings by presence, such as #missing, representing a list of files

class docstr_coverage.ExpectedDocstring(node_identifier: str, has_docstring: bool, ignore_reason: Optional[str])

Bases: object

A class containing information about a single docstring and its presence

class docstr_coverage.FileCount

Bases: docstr_coverage.result_collection._DocstrCount

Counts of docstrings by presence, such as #missing, representing a single file

found_empty_file()

To be called to count the presence of an empty file.

found_needed_docstr()

To be called to count a present non-ignored docstring.

missed_needed_docstring()

To be called to count a missing non-ignored docstring.