pyTooling.Sphinx.CondensedSource

A Python module’s source, condensed to what its documentation coverage is about: the headers and doc-strings of its classes and functions, its variables and fields; a body is elided to ....

CondensedSource holds the condensed lines, each marked by its documentation state; its classmethod Parse() condenses a module’s source. The pages of pyTooling.Sphinx.DocCoverage show it as a listing.

See also

Pages per package and module: → The pages and the condensed listing, with examples.

Variables

DEFINITIONS
ASSIGNMENTS
Definition

Functions

documentationState(): Return the state a listing marks a line with, for a coverage state of pyEDAA.Reports’ documentation coverage model.

Classes

CondensedSource: A Python module’s source, condensed to what its documentation coverage is about.

Variables

pyTooling.Sphinx.CondensedSource.DEFINITIONS

The statements expected to have a doc-string: a class and a function or method.

(<class 'ast.ClassDef'>,
 <class 'ast.FunctionDef'>,
 <class 'ast.AsyncFunctionDef'>)

pyTooling.Sphinx.CondensedSource.ASSIGNMENTS

The statements declaring a variable or a class’ field.

(<class 'ast.Assign'>, <class 'ast.AnnAssign'>, <class 'ast.TypeAlias'>)

pyTooling.Sphinx.CondensedSource.Definition

A statement expected to have a doc-string.

Definition

Functions

pyTooling.Sphinx.CondensedSource.documentationState(coverageState)[source]

Return the state a listing marks a line with, for a coverage state of pyEDAA.Reports’ documentation coverage model.

The state is chosen as the model counts it: excluded before ignored, then documented - covered - or undocumented. An item with nothing to document (Empty) isn’t counted, so it gets no state.

Parameters:: coverageState (CoverageState) – The model’s coverage state.
Return type:: str
Returns:: The listing’s state: documented, undocumented, ignored, excluded or "".

Classes

class pyTooling.Sphinx.CondensedSource.CondensedSource(lines)[source]

A Python module’s source, condensed to what its documentation coverage is about.

A line is taken as written, at its line number, or replaced by a ... line without a number:

The module’s doc-string is taken; its imports and other statements are elided.
A class or function is taken with its decorators, its header up to the : - a signature spanning lines too - and its doc-string. Its body follows: a class’ members, a function’s nested functions and classes; anything else is elided to one ... at the body’s indentation. A definition written in one line is taken as written.
A variable of the module and a field of a class is taken as written: with a #: comment on its line or in the lines above it, and a doc-string literal following it.
A statement holding a class or function - e.g. an if or a try -, and an if or try assigning a variable or field, is taken with the headers of its clauses as written; each clause’s block is taken like a body.
Comments between statements are left out; consecutive blank lines become one.

A class’, function’s, field’s or variable’s lines are marked by the documentation state of its item in pyEDAA.Reports’ model: the item declared in the module’s file, which starts at the definition’s first line or at the assignment. The module’s doc-string is marked by the module’s state. Every other line has no state, e.g. a repeated assignment of a variable, as its item starts at the first one.

Inheritance

Parameters:: lines (Iterable[tuple[Nullable[int], str, str]])

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.

__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

__init__(lines)[source]

Initialize a condensed source from its lines.

Parameters:

lines (Iterable[tuple[int | None, str, str]]) – The condensed lines (see Lines).

Raises:

ValueError – If parameter lines is None.
TypeError – If parameter lines isn’t iterable.
TypeError – If a line isn’t a tuple.

Return type:

None

_lines: list[tuple[int | None, str, str]]: The condensed lines; see Lines.

classmethod Parse(source, path, module)[source]

Condense a module’s source.

An analysis not matching the source - a class or function without an item of its name at its first line - is logged as a warning, and no class, function, field or variable is marked.

Parameters:

source (str) – The module’s source.
path (str) – The module’s path, as the warning names it.
module (Item) – The module’s or package’s item of pyEDAA.Reports’ model; its file lists the items declared in it.

Return type:

Self

Returns:

The condensed source.

property Lines: list[tuple[int | None, str, str]]

Read-only property to access the condensed lines (_lines).

Returns:: A tuple per line: the line number and its state, and ""; or for an elided body, None, "" and the body’s indentation.