pyEDAA.Reports.DocumentationCoverage.DocStrCoverage

Converter of docstr_coverage’s analysis to the documentation coverage model.

docstr_coverage counts modules, classes and functions only - no fields or variables -, and reports each by an identifier of its own and its parent’s name, without its kind or line. So the converter rebuilds the hierarchy from these identifiers, and every item but a module or package is of kind Other.

See also

pyEDAA.Reports.DocumentationCoverage.Python

→ The reader of Python source files, which counts fields and variables too.

Exceptions

• DocStrCoverageError: An analysis by docstr_coverage can’t be run or converted.

Classes

• DocStrCoverage: Runs docstr_coverage’s analysis on a package’s directory, and converts it to the documentation coverage model.

---

Exceptions

exception pyEDAA.Reports.DocumentationCoverage.DocStrCoverage.DocStrCoverageError(message='')

An analysis by docstr_coverage can’t be run or converted.

Inheritance

Parameters:

message (str)

Return type:

None

---

Classes

class pyEDAA.Reports.DocumentationCoverage.DocStrCoverage.DocStrCoverage(packageName, directory)

Runs docstr_coverage’s analysis on a package’s directory, and converts it to the documentation coverage model.

Inheritance

Parameters:

• packageName (str)

• directory (Path)

__init__(packageName, directory)

Initializes the analysis of a package’s directory, and searches it for Python source files.

Parameters:

• packageName (str) – Name of the package, which is the name of the top-level item, e.g. myPackage.

• directory (Path) – The package’s directory.

Raises:

• ValueError – If parameter packageName is None.

• TypeError – If parameter packageName isn’t of type str.

• ValueError – If parameter packageName is empty.

• ValueError – If parameter directory is None.

• TypeError – If parameter directory isn’t of type Path.

• DocStrCoverageError – If the directory doesn’t exist.

Return type:

None

_packageName: str

Name of the package.

_searchDirectory: Path

The directory searched for Python source files.

_moduleFiles: list[Path]

The Python source files found.

_coverageReport: ResultCollection | None

docstr_coverage’s analysis, or None before Analyze().

_analysisDuration: timedelta | None

Duration of Analyze(), or None before it ran.

_conversionDuration: timedelta | None

Duration of Convert(), or None before it ran.

property SearchDirectory: Path

Read-only property to access the directory searched for Python source files (_searchDirectory).

Returns:

Path to the search directory.

property PackageName: str

Read-only property to access the name of the analyzed package (_packageName).

Returns:

Name of the package.

classmethod GetMethodsWithAttributes(predicate=None)

Return the class’ methods that carry at least one matching attribute.

Parameters:

predicate (type[TAttr] | Iterable[type[TAttr]] | None) – Optional, an attribute class, an iterable of attribute classes, or None to accept every attribute.

Return type:

dict[Callable[..., Any], tuple[Attribute, ...]]

Returns:

Dictionary of methods and the matching attributes attached to them.

Raises:

• ValueError – If an element of parameter ‘predicate’ is not a sub-class of Attribute.

• ValueError – If parameter ‘predicate’ is neither an attribute class nor an iterable of those.

property ModuleFiles: list[Path]

Read-only property to access the Python source files found in the search directory (_moduleFiles).

Returns:

List of module file paths.

__getstate__()

Return the object’s state for pickling, collecting every slot of the class hierarchy.

Return type:

dict[str, Any]

Returns:

Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If a slot was never assigned, so it has no value to serialize.

__setstate__(state)

Restore the object’s state from unpickling, requiring exactly the slots of the class hierarchy.

Parameters:

state (dict[str, Any]) – Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If the given state misses a slot or carries an unexpected one.

Return type:

None

property CoverageReport: ResultCollection | None

Read-only property to access docstr_coverage’s analysis (_coverageReport).

Returns:

The analyzer’s result collection, or None before Analyze() ran.

property AnalysisDuration: timedelta | None

Read-only property to access the duration of docstr_coverage’s analysis (_analysisDuration).

Returns:

The duration, or None before Analyze() ran.

property ModelConversionDuration: timedelta | None

Read-only property to access the duration of Convert(): building the documentation coverage report (_conversionDuration).

Returns:

The duration, or None before Convert() ran.

Analyze()

Run docstr_coverage’s analysis on the Python source files found, and measure its duration.

Return type:

ResultCollection

Returns:

The analyzer’s result collection.

Convert()

Convert docstr_coverage’s analysis to a documentation coverage report, aggregate it, and measure the duration.

The report’s AnalysisDuration is the duration of docstr_coverage’s analysis.

A source file is a module, an __init__.py the package of its directory, and a directory without __init__.py a package without anything to document. docstr_coverage’s identifier of an item names its parent: the item is added to the innermost item of that name, which encloses the item reported before.

Return type:

DocumentationReport

Returns:

The report; its top-level item is the package.

Raises:

DocStrCoverageError – If Analyze() didn’t run.