Python API Reference

Every name in abicheck.service.__all__ — the supported Tier-2 public entry point — with its full signature or dataclass field list, generated directly from the live objects. See Python API for the narrative walkthrough (comparing libraries, working with snapshots, rendering results); this page is the exhaustive signature list only.

Budget

Optional scan budget — a failure guard, never a scope-shrinker (ADR-035 D3).

Dataclass.

Field	Type	Default
total_timeout	float \| None	None
max_tus	int \| None	None
partial_ok	bool	True

CompareRequest

A fully-specified comparison request — the single input to run_compare.

Dataclass.

Field	Type	Default
old	InputSpec	(required)
new	InputSpec	(required)
lang	str	'c++'
frontend	str	'auto'
has_sources	bool	False
policy	str	'strict_abi'
policy_file_path	Path \| None	None
suppress	Path \| None	None
scope_public	bool	True
force_public_symbols	frozenset[str] \| None	None
public_surface_allowlist	frozenset[str] \| None	None
pattern_verdicts	bool	False
enable_debuginfod	bool	False
debuginfod_url	str \| None	None
reconcile_build_context	bool	False
env_matrix_path	Path \| None	None
diagnostic_comparison	bool	False
contract_evaluation	bool	False
contract_mode	str \| None	None
depth	str \| None	None
dwarf_only	bool	False
debug_format	str \| None	None
include_labels	tuple[tuple[Path, str], ...]	()
follow_dependencies	bool	False
dependency_search_paths	tuple[Path, ...]	()
ld_library_path	str	''
frontend_context	str	'host'

CompareResult

What one :class:CompareRequest produced — the typed result (ADR-055 D2).

Dataclass.

Field	Type	Default
diff	DiffResult	(required)
old_snapshot	AbiSnapshot	(required)
new_snapshot	AbiSnapshot	(required)
suppression	SuppressionList \| None	None

CompileContext

L2 header-AST compile context — shared by dump and scan.

Dataclass.

Field	Type	Default
gcc_path	str \| None	None
gcc_prefix	str \| None	None
gcc_options	str \| None	None
gcc_option_tokens	tuple[str, ...]	()
sysroot	Path \| None	None
nostdinc	bool	False
frontend	str	'auto'
frontend_context	str	'host'

CostEstimate

Projected cost of one L-layer for this project (ADR-035 D10 dry-run).

Dataclass.

Field	Type	Default
method	str \| None	(required)
layer	str	(required)
tus	int	(required)
est_seconds	float	(required)
cache_hit_rate	float	(required)
note	str	(required)

DumpRequest

A fully-specified snapshot-extraction request — the input to run_dump_request.

Dataclass.

Field	Type	Default
input	InputSpec	(required)
lang	str	'c++'
frontend	str	'auto'
has_sources	bool	False
depth	str \| None	None
dwarf_only	bool	False
debug_format	str \| None	None
enable_debuginfod	bool	False
debuginfod_url	str \| None	None
include_labels	tuple[tuple[Path, str], ...]	()
follow_dependencies	bool	False
dependency_search_paths	tuple[Path, ...]	()
ld_library_path	str	''
frontend_context	str	'host'

InputSpec

One side of a comparison: a binary/snapshot path plus its build context.

Dataclass.

Field	Type	Default
path	Path	(required)
headers	tuple[Path, ...]	()
includes	tuple[Path, ...]	()
version	str	''
pdb	Path \| None	None
debug_roots	tuple[Path, ...]	()
include_dependencies	bool	True
sources	Path \| None	None
build_info	Path \| None	None
dump_manifest	DumpManifest \| None	None
compile	CompileContext \| None	None
public_header_dirs	tuple[Path, ...]	()
follow_linker_scripts	bool	True

LayerResult

Per-layer coverage of an executed scan (ADR-035 D10; reuses LayerCoverage).

Dataclass.

Field	Type	Default
method	str \| None	(required)
layer	str	(required)
status	str	(required)
facts	int	0
elapsed_s	float	0.0
skipped_reason	str \| None	None
detail	str	''
counters	dict[str, int]	{}

OutputSpec

Where/how a result is rendered — the invocation-level output choice.

Dataclass.

Field	Type	Default
fmt	str	'text'
path	Path \| None	None

ResolvedComparePair

Both sides of a comparison, resolved and ready to classify.

Dataclass.

Field	Type	Default
old	AbiSnapshot	(required)
new	AbiSnapshot	(required)
old_fmt	str \| None	(required)
new_fmt	str \| None	(required)
old_evidence	SideEvidence	(required)
new_evidence	SideEvidence	(required)

ScanArtifactResult

One member's :class:ScanResult, with the identity that result alone doesn't carry (ADR-056 — neither ScanResult nor its nested report carries a binary path or library name anywhere).

Dataclass.

Field	Type	Default
artifact	Path	(required)
result	ScanResult	(required)

ScanRequest

Typed input to the scan engine (ADR-035 D10). All additive over dump/compare.

Dataclass.

Field	Type	Default
binaries	list[Path]	[]
headers	list[Path]	[]
includes	list[Path]	[]
public_header_dirs	list[Path]	[]
sources	Path \| None	None
compile_db	Path \| None	None
build_info	Path \| None	None
baseline	str \| Path \| None	None
mode	str	'pr'
source_method	str \| None	None
depth	str \| None	None
changed_paths	list[str]	[]
seeded	bool	False
budget	Budget	Budget(total_timeout=None, max_tus=None, partial_ok=True)
lang	str	'c++'
compile	CompileContext	CompileContext(gcc_path=None, gcc_prefix=None, gcc_options=None, gcc_option_tokens=(), sysroot=None, nostdinc=False, frontend='auto', frontend_context='host')
suppression	SuppressionList \| None	None
policy	str	'strict_abi'
policy_file	PolicyFile \| None	None
scope_to_public_surface	bool	True
force_public_symbols	set[str] \| None	None
pattern_verdicts	bool	False
env_matrix	EnvironmentMatrix \| None	None
collapse_versioned_symbols	bool	False
contract_evaluation	bool	False
contract_mode	str \| None	None
abi3_floor	tuple[int, int] \| None	None
enabled_checks	frozenset[str] \| None	None
severities	dict[str, str]	{}
build_config	Path \| None	None
allow_build_query	bool	False
risk_rules_path	Path \| None	None
bundle_system_providers	tuple[str, ...]	()
changed_src	str	'run_scan_set'

ScanResult

Typed result of an executed scan (ADR-035 D10) — the one object the CLI and library callers consume.

Dataclass.

Field	Type	Default
verdict	str	(required)
exit_code	int	(required)
findings	list[Any]	[]
layers	list[LayerResult]	[]
confidence	dict[str, list[str]]	{}
estimate	list[CostEstimate]	[]
report	dict[str, Any]	{}

ScanSetResult

Result of :func:run_scan_set — the --artifact-set sibling of :class:ScanResult (ADR-056). Not a change to what run_scan/ ScanResult return for the single-binary path.

Dataclass.

Field	Type	Default
verdict	str	(required)
exit_code	int	(required)
per_artifact	list[ScanArtifactResult]	[]
bundle_findings	list[Any]	[]
bundle_verdict	str \| None	None
bundle_incomplete	bool	False

classify_compare_pair

Classify an already-resolved pair — the second half of run_compare_request.

Parameter	Type	Default
request	CompareRequest	(required)
pair	ResolvedComparePair	(required)

Returns: CompareResult

collect_metadata

Compute SHA-256 and file size for a library artifact.

Parameter	Type	Default
path	Path	(required)

Returns: LibraryMetadata \| None

compare_snapshots

Classify two already-resolved snapshots — the Tier-2 snapshot verb.

Parameter	Type	Default
old	AbiSnapshot	(required)
new	AbiSnapshot	(required)
suppression	SuppressionList \| None	None
(keyword-only below)
policy	str	'strict_abi'
policy_file	PolicyFile \| None	None
scope_to_public_surface	bool	True
force_public_symbols	set[str] \| None	None
extra_changes	list[Change] \| None	None
pattern_verdicts	bool	False
surface_metrics	bool	False
collapse_versioned_symbols	bool	False
public_surface_allowlist	set[str] \| None	None
reconcile_build_context	bool	False
env_matrix	EnvironmentMatrix \| None	None
diagnostic_comparison	bool	False
contract_evaluation	bool	False
contract_mode	str \| None	None

Returns: DiffResult

detect_binary_format

Detect binary format from magic bytes.

Parameter	Type	Default
path	Path	(required)

Returns: str \| None

estimate_scan

Dry-run: projected per-layer cost of req for this project (ADR-035 D10).

Parameter	Type	Default
req	ScanRequest	(required)
(keyword-only below)
resolved_level	tuple[SourceMethod, EvidenceDepth] \| None	None

Returns: list[CostEstimate]

expand_header_inputs

Expand header inputs where each item can be a file or a directory.

Parameter	Type	Default
inputs	list[Path]	(required)

Returns: list[Path]

load_suppression_and_policy

Load suppression list and policy file from paths.

Parameter	Type	Default
suppress	Path \| None	(required)
policy	str	'strict_abi'
policy_file_path	Path \| None	None

Returns: tuple[SuppressionList \| None, PolicyFile \| None]

render_output

Render comparison result in the requested output format.

Parameter	Type	Default
fmt	str	(required)
result	DiffResult	(required)
old	AbiSnapshot	(required)
new	AbiSnapshot \| None	None
(keyword-only below)
follow_deps	bool	False
show_only	str \| None	None
report_mode	str	'full'
show_impact	bool	False
stat	bool	False
severity_config	SeverityConfig \| None	None
show_recommendation	bool	False
demangle	bool	False
contract_evaluation	bool	False

Returns: str

resolve_compare_request

Resolve both sides of request into a classifiable pair.

Parameter	Type	Default
request	CompareRequest	(required)
(keyword-only below)
notify	Callable[[str], None] \| None	None
allow_parallel	bool	True

Returns: ResolvedComparePair

resolve_input

Auto-detect input type and return an ABI snapshot.

Parameter	Type	Default
path	Path	(required)
headers	list[Path] \| None	None
includes	list[Path] \| None	None
version	str	''
lang	str	'c++'
(keyword-only below)
is_elf	bool \| None	None
pdb_path	Path \| None	None
dwarf_only	bool	False
debug_roots	list[Path] \| None	None
enable_debuginfod	bool	False
debuginfod_url	str \| None	None
debug_format	str \| None	None
symbols_only	bool	False
debug_presence_only	bool	False
public_headers	list[Path] \| None	None
public_header_dirs	list[Path] \| None	None
follow_linker_scripts	bool	True
header_backend	str	'auto'
compile	CompileContext \| None	None
notify	Callable[[str], None] \| None	None
include_labels	dict[Path, str] \| None	None
dump_manifest	DumpManifest \| None	None
include_dependencies	bool	True

Returns: AbiSnapshot

run_audit

Single-release hygiene audit — :func:run_scan with the AUDIT mode (no baseline, ADR-035 D8). A thin convenience wrapper so callers can name intent.

Parameter	Type	Default
req	ScanRequest	(required)

Returns: ScanResult

run_compare

Compare two ABI inputs and return the classified diff result.

Parameter	Type	Default
old_input	Path	(required)
new_input	Path	(required)
old_headers	list[Path] \| None	None
new_headers	list[Path] \| None	None
old_includes	list[Path] \| None	None
new_includes	list[Path] \| None	None
old_version	str	''
new_version	str	''
lang	str	'c++'
frontend	str	'auto'
suppress	Path \| None	None
policy	str	'strict_abi'
policy_file_path	Path \| None	None
old_pdb_path	Path \| None	None
new_pdb_path	Path \| None	None
old_debug_roots	list[Path] \| None	None
new_debug_roots	list[Path] \| None	None
enable_debuginfod	bool	False
scope_to_public_surface	bool	True
force_public_symbols	set[str] \| None	None
pattern_verdicts	bool	False
public_surface_allowlist	set[str] \| None	None
debuginfod_url	str \| None	None
diagnostic_comparison	bool	False
contract_evaluation	bool	False
include_dependencies	bool	True
contract_mode	str \| None	None

Returns: CompareResult

run_compare_request

Compare two ABI inputs described by a :class:CompareRequest.

Parameter	Type	Default
request	CompareRequest	(required)

Returns: CompareResult

run_dump

Extract an ABI snapshot from a native binary (ELF, PE, or Mach-O).

Parameter	Type	Default
path	Path	(required)
binary_fmt	str	(required)
headers	list[Path] \| None	None
includes	list[Path] \| None	None
version	str	''
lang	str	'c++'
(keyword-only below)
pdb_path	Path \| None	None
dwarf_only	bool	False
debug_roots	list[Path] \| None	None
enable_debuginfod	bool	False
debuginfod_url	str \| None	None
debug_format	str \| None	None
symbols_only	bool	False
debug_presence_only	bool	False
public_headers	list[Path] \| None	None
public_header_dirs	list[Path] \| None	None
header_backend	str	'auto'
compile	CompileContext \| None	None
notify	Callable[[str], None] \| None	None
include_labels	dict[Path, str] \| None	None
dump_manifest	DumpManifest \| None	None
include_dependencies	bool	True

Returns: AbiSnapshot

run_dump_request

Resolve request into one :class:~abicheck.model.AbiSnapshot.

Parameter	Type	Default
request	DumpRequest	(required)
(keyword-only below)
notify	Callable[[str], None] \| None	None

Returns: AbiSnapshot

run_scan

Execute a scan and return a typed :class:ScanResult (ADR-035 D10).

Parameter	Type	Default
req	ScanRequest	(required)

Returns: ScanResult

run_scan_set

Execute an audit-mode, no-old-side scan over a set of artifacts (ADR-056, scan --artifact-set).

Parameter	Type	Default
req	ScanRequest	(required)

Returns: ScanSetResult

run_scan_set_subprocess

Run :func:run_scan_set in a killable child process (ADR-056).

Parameter	Type	Default
req	ScanRequest	(required)
timeout	float	(required)

Returns: dict[str, Any]

run_scan_subprocess

Run :func:run_scan in a killable child process; return ScanResult.to_dict().

Parameter	Type	Default
req	ScanRequest	(required)
timeout	float	(required)

Returns: dict[str, Any]

sniff_text_format

Read a small header chunk and return 'json', 'perl', or 'unknown'.

Parameter	Type	Default
path	Path	(required)

Returns: str