API Reference¶

Auto-generated from source docstrings.

`trace`¶

trace ¶

trace(path: str | PathLike[str], variable: str, *, follow_parents: bool = True, include_labels: bool = False) -> TraceResult

Trace a variable through a Stata do file and its includes.

PARAMETER	DESCRIPTION
`path`	Path to the root do file. TYPE: `str \| PathLike[str]`
`variable`	Variable name to trace. TYPE: `str`
`follow_parents`	When False, leave `ancestors` empty while retaining the target's ranges and the global audit inventory. TYPE: `bool` DEFAULT: `True`
`include_labels`	When True, include label lifecycle events in the target and ancestor traces. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`TraceResult`	A frozen, JSON-lossless `TraceResult`. The output depends only
`TraceResult`	on the input file and the registry version -- no network, randomness,
`TraceResult`	or environment-dependent behaviour.

Example

trace("data/clean.do", "income", include_labels=True) returns a TraceResult whose ranges contain the physical source lines for income.

CLI¶

main ¶

main(argv: list[str] | None = None) -> int

Run the do2screen CLI.

PARAMETER	DESCRIPTION
`argv`	Optional argument list; `None` reads `sys.argv[1:]`. TYPE: `list[str] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`int`	Exit code: `0` for a legacy result or complete/partial project
`int`	result, `1` for an unreadable input, project registry incompatibility,
`int`	or a project with no readable roots, and `2` for invalid arguments or
`int`	manifest schema. Successful invocations write exactly one
`int`	`TraceResult` JSON document to stdout. Project diagnostics are part of
`int`	that JSON; human-readable failures and warnings go to stderr.

The legacy form is do2screen PATH VARIABLE. Project forms use --variable with exactly one of --dir, --files, or --manifest.

Project Tracing¶

The three project functions return the same TraceResult contract as trace(). They differ only in ingestion: explicit file lists and manifests are ordered; directory discovery is deterministic but unordered.

trace_files ¶

trace_files(files: list[str | PathLike[str]] | tuple[str | PathLike[str], ...], variable: str, *, follow_parents: bool = True, include_labels: bool = False) -> TraceResult

Trace variable through an explicitly ordered list of source files.

Duplicate paths are retained as separate root occurrences so execution order remains observable; each physical source is still parsed once.

PARAMETER	DESCRIPTION
`files`	Non-empty list or tuple of source paths. The supplied order is the execution order for project lineage. TYPE: `list[str \| PathLike[str]] \| tuple[str \| PathLike[str], ...]`
`variable`	Variable name to trace. TYPE: `str`
`follow_parents`	When False, leave `ancestors` empty while retaining the target's ranges and the global audit inventory. TYPE: `bool` DEFAULT: `True`
`include_labels`	When True, include label lifecycle events in the target and ancestor traces. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`TraceResult`	A project `TraceResult` with `input_mode="files"`.

RAISES	DESCRIPTION
`ValueError`	If `files` is empty or contains an invalid path-like value.
`RegistryIncompatibilityError`	If the installed registry cannot provide the source-driver capability required by project tracing.

trace_directory ¶

trace_directory(directory: str | PathLike[str], variable: str, *, recursive: bool = False, follow_parents: bool = True, include_labels: bool = False) -> TraceResult

Trace variable through visible .do/.ado files in a directory.

Discovery is deterministic but semantically unordered. Cross-file lineage is therefore omitted when no explicit occurrence order exists and is reported in project_diagnostics.

PARAMETER	DESCRIPTION
`directory`	Directory containing the project source files. TYPE: `str \| PathLike[str]`
`variable`	Variable name to trace. TYPE: `str`
`recursive`	When True, discover files in nested visible directories. TYPE: `bool` DEFAULT: `False`
`follow_parents`	When False, leave `ancestors` empty while retaining the target's ranges and the global audit inventory. TYPE: `bool` DEFAULT: `True`
`include_labels`	When True, include label lifecycle events in the target and ancestor traces. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`TraceResult`	A project `TraceResult` with `input_mode="directory"`. Missing
`TraceResult`	inputs and unordered cross-file references are reported in
`TraceResult`	`project_diagnostics`.

RAISES	DESCRIPTION
`RegistryIncompatibilityError`	If the installed registry cannot provide the source-driver capability required by project tracing.

trace_manifest ¶

trace_manifest(manifest_path: str | PathLike[str], variable: str, *, follow_parents: bool = True, include_labels: bool = False) -> TraceResult

Trace variable through the ordered files in a manifest V1 document.

Manifest V1 accepts exactly {"version": 1, "files": [strings]}.

PARAMETER	DESCRIPTION
`manifest_path`	Path to a Manifest V1 JSON document. TYPE: `str \| PathLike[str]`
`variable`	Variable name to trace. TYPE: `str`
`follow_parents`	When False, leave `ancestors` empty while retaining the target's ranges and the global audit inventory. TYPE: `bool` DEFAULT: `True`
`include_labels`	When True, include label lifecycle events in the target and ancestor traces. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`TraceResult`	A project `TraceResult` with `input_mode="manifest"` and the
`TraceResult`	canonical `manifest_path`.

RAISES	DESCRIPTION
`ValueError`	If the manifest cannot be read or does not match the Manifest V1 schema.
`RegistryIncompatibilityError`	If the installed registry cannot provide the source-driver capability required by project tracing.

Models¶

TraceResult¶

TraceResult ¶

Bases: BaseModel

The full result of tracing one variable through one source graph.

ATTRIBUTE	DESCRIPTION
`variable`	The traced target variable. TYPE: `str`
`ranges`	Lifecycle ranges of the target variable across all sources; label events are included only when label tracking is enabled. TYPE: `list[LineRange]`
`ancestors`	Recursively resolved ancestors of the target. TYPE: `list[str]`
`attributed_ranges`	Complete ordered audit inventory of every attribution (lifecycle and dependency references) for all variables. TYPE: `list[RangeAttribution]`
`unresolved_blocks`	Every region that could not be attributed. TYPE: `list[UnresolvedBlock]`
`coverage`	Fraction of executable physical lines covered by at least one attributed range. Sentinel 1.0 when there are no executable lines. TYPE: `float`
`sources`	Provenance of every traversed source, in traversal order. TYPE: `list[SourceProvenance]`
`source`	Provenance of the root source; in project mode, this is the first requested source and does not establish semantic order. TYPE: `SourceProvenance`
`input_mode`	Project input mode, or `None` for a legacy trace. TYPE: `ProjectInputMode \| None`
`project_files`	Canonical physical sources accepted by a project input. TYPE: `list[str]`
`variable_identities`	Occurrence-qualified project definition contexts. TYPE: `list[VariableIdentity]`
`manifest_path`	Canonical manifest path for manifest input, if any. TYPE: `str \| None`
`project_diagnostics`	Non-terminal project uncertainty and input facts. TYPE: `list[ProjectDiagnostic]`
`provenance_chunk`	Human-auditable resolved lineage slice for the target. TYPE: `VariableProvenanceChunk \| None`

LineRange¶

LineRange ¶

Bases: BaseModel

An inclusive range of physical source lines.

ATTRIBUTE	DESCRIPTION
`source`	Path of the source file the range belongs to. TYPE: `str`
`start_line`	First physical line (1-based, inclusive). TYPE: `int`
`end_line`	Last physical line (1-based, inclusive). TYPE: `int`
`comment_start_line`	Optional first line of the contiguous full-line comment immediately preceding the statement. TYPE: `int \| None`
`comment_end_line`	Optional last line of that preceding comment. TYPE: `int \| None`
`source_lines`	Decoded physical source lines covered by this inclusive range, without line terminators. The list length is `end_line - start_line + 1`. TYPE: `list[str]`

RangeAttribution¶

RangeAttribution ¶

Bases: BaseModel

One attributed executable statement tied to one variable.

ATTRIBUTE	DESCRIPTION
`range`	The physical line range of the statement. TYPE: `LineRange`
`variable`	The variable the statement affects or references. TYPE: `str`
`kind`	Lifecycle or dependency kind of the attribution. TYPE: `Kind`

VariableTrace¶

VariableTrace ¶

Bases: BaseModel

Everything the tracer learned about one variable.

ATTRIBUTE	DESCRIPTION
`variable`	The variable name. TYPE: `str`
`ranges`	Lifecycle line ranges in source order (created, modified, and dropped; labelled when label tracking is enabled). Dependency-only (`referenced`) records are excluded to preserve do2screen (Stata) line-set parity. TYPE: `list[LineRange]`
`parents`	Unique direct dependency variables in first-reference order. TYPE: `list[str]`
`ancestors`	Recursively resolved ancestors (empty when `follow_parents=False`). TYPE: `list[str]`

UnresolvedBlock¶

UnresolvedBlock ¶

Bases: BaseModel

A region of recognized-but-unattributed code, reported explicitly.

ATTRIBUTE	DESCRIPTION
`range`	Physical line range of the unresolved region. TYPE: `LineRange`
`reason`	One of the seven unresolved categories. TYPE: `UnresolvedReason`
`context`	Source/parser facts only (for example the unresolved include target path or the enclosing brace block range). TYPE: `dict[str, str]`
`statement`	Optional raw text of the statement, when one exists. TYPE: `str \| None`

SourceProvenance¶

SourceProvenance ¶

Bases: BaseModel

Provenance metadata for one traversed source file.

ATTRIBUTE	DESCRIPTION
`path`	Normalized filesystem path of the source. TYPE: `str`
`line_count`	Number of physical lines in the source. TYPE: `int`
`used_delimit`	True when the source uses `#delimit ;` anywhere. TYPE: `bool`
`traversal_index`	Ordered index of this source in physical-source traversal order (0 is the first registered source). TYPE: `int`

VariableContext¶

VariableContext ¶

Bases: BaseModel

One occurrence-qualified definition context for a variable.

VariableIdentity¶

VariableIdentity ¶

Bases: BaseModel

A variable name and its occurrence-qualified definition contexts.

ProjectDiagnostic¶

ProjectDiagnostic ¶

Bases: BaseModel

Non-terminal uncertainty or input fact from a project trace.

Diagnostics are separate from unresolved_blocks: a diagnostic may have no physical range and never changes the parser's terminal line partition.

VariableEffect¶

VariableEffect ¶

Bases: BaseModel

One lifecycle effect retained in a provenance statement.

ProvenanceStatement¶

ProvenanceStatement ¶

Bases: BaseModel

One physical statement occurrence in a resolved lineage slice.

VariableProvenanceChunk¶

VariableProvenanceChunk ¶

Bases: BaseModel

Human-auditable lifecycle slice for one requested variable.

The text is a contiguous, marked source block for display. It is not a standalone executable Stata program: dataset loading, macros, control flow, restructuring, and user-written commands may still be required.

Exceptions¶

RegistryIncompatibilityError¶

RegistryIncompatibilityError ¶

Bases: RuntimeError

Raised when the registry is absent or its API does not match the documented contract. Carries version information when available.

API Reference¶

trace¶

trace ¶

CLI¶

main ¶

Project Tracing¶

trace_files ¶

trace_directory ¶

trace_manifest ¶

Models¶

TraceResult¶

TraceResult ¶

LineRange¶

LineRange ¶

RangeAttribution¶

RangeAttribution ¶

VariableTrace¶

VariableTrace ¶

UnresolvedBlock¶

UnresolvedBlock ¶

SourceProvenance¶

SourceProvenance ¶

VariableContext¶

VariableContext ¶

VariableIdentity¶

VariableIdentity ¶

ProjectDiagnostic¶

ProjectDiagnostic ¶

VariableEffect¶

VariableEffect ¶

ProvenanceStatement¶

ProvenanceStatement ¶

VariableProvenanceChunk¶

VariableProvenanceChunk ¶

Exceptions¶

RegistryIncompatibilityError¶

RegistryIncompatibilityError ¶

`trace`¶