oct.complexity.coverage Namespace Reference

Classes
class	CoverageUnavailableError
class	CoverageRun
class	CoveredFunction

Functions
Any	_import_coverage ()
Any	_import_pytest ()
CoverageRun	run_pytest_with_coverage (str|Path project_root, Sequence[str] pytest_args=("tests",), str|Path data_file=".coverage", Sequence[str|Path] source=(), *, bool in_process=False, str|Path|None python_executable=None, dict[str, str]|None env=None)
CoverageRun	_run_pytest_in_process (Path project_root, tuple[str,...] pytest_args, Path data_file, tuple[str,...] source)
None	_remove_first (list[str] items, str value)
CoverageRun	_run_pytest_subprocess (Path project_root, tuple[str,...] pytest_args, Path data_file, tuple[str,...] source, *, str|Path|None python_executable, dict[str, str]|None env)
list[CoveredFunction]	map_coverage (Sequence[FunctionComplexity] records, str|Path data_file)
CoveredFunction	_map_one (Any coverage, dict[str, str] measured_files, FunctionComplexity record)
set[int]	_statement_lines (Any coverage, str filename)
str	_normalized_path (str|Path filename)

Detailed Description

Purpose
-------
Run pytest under coverage.py and map executed statements to function spans.

Responsibilities
----------------
- Execute subproject suites in process for witnesses or in a subprocess for probes.
- Preserve suite return codes and both output streams.
- Mark functions in unexecuted files as zero-coverage ``never-imported`` records.
- Intersect coverage.py statement data with the engine's pinned source spans.

Diagnostics
-----------
Domain: OCT-COMPLEXITY
Levels:
    L2 - suite lifecycle
    L3 - coverage mapping details
    L4 - deep tracing

Contracts
---------
- Third-party imports remain lazy so :mod:`oct.complexity` stays zero-dependency.
- Missing coverage.py produces an explicit error rather than an estimate.
- Failed suites retain their output for UNMEASURED probe reporting.

Dependencies
------------
- coverage (not imported; optional statement measurement and data reading, loaded by name through importlib and run as python -m coverage)
- pytest (not imported; test runner, loaded by name for in-process witnesses and run under coverage in probes)
- oct.complexity.engine (function spans)

Function Documentation

_import_coverage()

Any oct.complexity.coverage._import_coverage ( )

protected

Import coverage.py lazily and normalize the missing-extra error.

Definition at line 96 of file coverage.py.

Here is the caller graph for this function:

_import_pytest()

Any oct.complexity.coverage._import_pytest ( )

protected

Import pytest lazily for the in-process witness runner.

Definition at line 106 of file coverage.py.

Here is the caller graph for this function:

_map_one()

CoveredFunction oct.complexity.coverage._map_one ( Any coverage, dict[str, str] measured_files, FunctionComplexity record )

protected

Map one function record, preserving unseen files as zero coverage.

Definition at line 262 of file coverage.py.

Here is the call graph for this function:

Here is the caller graph for this function:

_normalized_path()

str oct.complexity.coverage._normalized_path ( str | Path filename )

protected

Normalize measured filenames for case-insensitive Windows matching.

Definition at line 312 of file coverage.py.

Here is the caller graph for this function:

_remove_first()

None oct.complexity.coverage._remove_first ( list[str] items, str value )

protected

Remove the first matching value without disturbing prior path state.

Definition at line 195 of file coverage.py.

Here is the caller graph for this function:

_run_pytest_in_process()

CoverageRun oct.complexity.coverage._run_pytest_in_process ( Path project_root, tuple[str, ...] pytest_args, Path data_file, tuple[str, ...] source )

protected

Run pytest under a Coverage instance in the current interpreter.

Definition at line 157 of file coverage.py.

Here is the call graph for this function:

Here is the caller graph for this function:

_run_pytest_subprocess()

CoverageRun oct.complexity.coverage._run_pytest_subprocess ( Path project_root, tuple[str, ...] pytest_args, Path data_file, tuple[str, ...] source, * , str | Path | None python_executable, dict[str, str] | None env )

protected

Run pytest under the coverage CLI in an isolated child process.

Definition at line 203 of file coverage.py.

Here is the call graph for this function:

Here is the caller graph for this function:

_statement_lines()

set[int] oct.complexity.coverage._statement_lines ( Any coverage, str filename )

protected

Return executable statement lines using coverage.py's own parser.

Definition at line 304 of file coverage.py.

Here is the caller graph for this function:

map_coverage()

list[CoveredFunction] oct.complexity.coverage.map_coverage	(	Sequence[FunctionComplexity]	records,
		str | Path	data_file )

Intersect coverage.py statements with each function's source span.

Definition at line 241 of file coverage.py.

Here is the call graph for this function:

run_pytest_with_coverage()

CoverageRun oct.complexity.coverage.run_pytest_with_coverage	(	str | Path	project_root,
		Sequence[str]	pytest_args = ("tests",),
		str | Path	data_file = ".coverage",
		Sequence[str | Path]	source = (),
		*	,
		bool	in_process = False,
		str | Path | None	python_executable = None,
		dict[str, str] | None	env = None )

Execute a subproject's pytest suite and retain its coverage data.

Production probes use the subprocess path so each subproject has clean
import state. The in-process path exists for worktree tests, where the
repository's editable install points at MAIN and subprocess assertions
would otherwise verify the wrong source tree.

Definition at line 116 of file coverage.py.

Here is the call graph for this function: