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.

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	True
enable_debuginfod	bool	False
debuginfod_url	str \| None	None
env_matrix	EnvironmentMatrix \| None	None
diagnostic_comparison	bool	False
contract_evaluation	bool	False
contract_mode	str \| None	None
depth	str \| None	None
budget_s	float \| 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'
lang_explicit	bool	False
pack_policy_overrides	tuple[tuple[ChangeKind, Verdict], ...] \| None	None
project_policy_overrides	tuple[tuple[ChangeKind, Verdict], ...] \| None	None
acknowledgments_path	Path \| None	None
acknowledgment_unacknowledged_additions	str \| None	None
pack_internal_namespaces	tuple[str, ...] \| None	None
severity_preset	str \| None	None
changed_paths	tuple[str, ...]	()
abi3_floor	tuple[int, int] \| None	None
collapse_versioned_symbols	bool	False
allow_build_query	bool	False
performance_profile	PerformanceProfile \| None	None

CompareResult

What one :class:CompareRequest produced — the typed result.

Dataclass.

Field	Type	Default
diff	DiffResult	(required)
old_snapshot	AbiSnapshot	(required)
new_snapshot	AbiSnapshot	(required)
suppression	SuppressionList \| None	None
exit_decision	ExitDecision \| None	None
severity_config	SeverityConfig \| None	None
resolved_execution_context	object \| 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, ...]	()
defines	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 (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'
lang_explicit	bool	False
resolved_collect_mode	str \| None	None

InputSpec

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

Dataclass.

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

OutputSpec

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

Dataclass.

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

ReleaseComparePlan

request's resolved pre-execution outcome.

Dataclass.

Field	Type	Default
request	ReleaseCompareRequest	(required)
scope	ReleaseScopePlan	(required)
gate	GateOptions	(required)
old_debug_dir	Path \| None	(required)
new_debug_dir	Path \| None	(required)
old_headers	tuple[Path, ...]	(required)
new_headers	tuple[Path, ...]	(required)
old_includes	tuple[Path, ...]	(required)
new_includes	tuple[Path, ...]	(required)
warnings	tuple[str, ...]	(required)
old_unclassified	dict[str, str]	{}
new_unclassified	dict[str, str]	{}
old_inventory	PackageInventory \| None	None
new_inventory	PackageInventory \| None	None
degraded	StoredDegradedMembers \| None	None
temp_dirs	tuple[Path, ...]	()

ReleaseCompareRequest

A fully-specified directory/package release-comparison resolution request -- the release fan-out's counterpart to :class:abicheck.workflows.contracts.CompareRequest, scoped to the pre-execution half (:func:resolve_release_compare_plan resolves it; it does not itself run any per-library dump/compare).

Dataclass.

Field	Type	Default
old_dir	Path	(required)
new_dir	Path	(required)
debug_info1	Path \| None	None
debug_info2	Path \| None	None
devel_pkg1	Path \| None	None
devel_pkg2	Path \| None	None
include_private_dso	bool	False
dso_only	bool	False
headers	tuple[Path, ...]	()
old_headers_only	tuple[Path, ...]	()
new_headers_only	tuple[Path, ...]	()
includes	tuple[Path, ...]	()
old_includes_only	tuple[Path, ...]	()
new_includes_only	tuple[Path, ...]	()
config_includes	tuple[Path, ...]	()
old_variant	str \| None	None
new_variant	str \| None	None
release_selection	ReleaseSelection \| None	None
pack_application	_GatePackApplicationLike \| None	None
severity_preset	str \| None	None
severity_abi_breaking	str \| None	None
severity_potential_breaking	str \| None	None
severity_quality_issues	str \| None	None
severity_addition	str \| None	None
on_incomplete_scope	str	'warn'
fail_on_removed_library	bool	False

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)
resolved_execution_context	ResolvedExecutionContext \| None	None

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

cleanup_release_compare_plan

Remove every directory :func:resolve_release_compare_plan allocated for plan (plan.temp_dirs) -- the direct-call counterpart of compare_release_cmd's own tracked _make_temp_dir/ _cleanup_temp_dirs pair (Codex review, PR #1215: a direct caller that lets a package/debug-package/devel-package/stored-package operand use the default make_temp_dir factory would otherwise leak the extracted directories for the process's lifetime, since nothing else ever removes them). A no-op, per entry, when a directory is already gone.

Parameter	Type	Default
plan	ReleaseComparePlan	(required)

Returns: None

collect_metadata

Compute SHA-256 and file size for a library artifact, or None for a text-based snapshot/manifest (JSON, Module.symvers) -- not a binary, so a same-binary comparison must never claim it.

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	True
collapse_versioned_symbols	bool	False
public_surface_allowlist	set[str] \| None	None
env_matrix	EnvironmentMatrix \| None	None
diagnostic_comparison	bool	False
contract_evaluation	bool	False
contract_mode	str \| None	None
acknowledgments	AcknowledgmentList \| None	None
acknowledgment_policy	AcknowledgmentPolicy \| 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 one comparison operand for this project. Probes the project (TU count, header fan-out) and returns one :class:CostEstimate per L-layer the level would touch -- without running any compiler or parsing any binary. Coarse anchors (see _COST_PER_*): ranks layers for a depth/budget pick, not a precise wall-clock prediction.

Parameter	Type	Default
side	InputSpec	(required)
(keyword-only below)
resolved_level	tuple[SourceMethod, EvidenceDepth]	(required)
collect_mode	str	(required)
changed_paths	Sequence[str]	()

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
severity_config	SeverityConfig \| None	None
demangle	bool \| None	None
contract_evaluation	bool	False
show_recommendation	bool	True
require_complete_analysis	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++'

Returns: AbiSnapshot

resolve_release_compare

Resolve request into a :class:ReleaseComparePlan -- the same four-step sequence (_prepare_compare_release_inputs -> release_inventory_evidence -> resolve_release_scope_plan -> resolve_release_gate_options), plus each side's stored-degraded markers, that compare_release_cmd itself now calls this function to perform, rather than repeating inline.

Parameter	Type	Default
request	ReleaseCompareRequest	(required)
(keyword-only below)
make_temp_dir	Callable[[str], Path] \| None	None

Returns: ReleaseComparePlan

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++'
lang_explicit	bool	False
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	True
public_surface_allowlist	set[str] \| None	None
debuginfod_url	str \| None	None
diagnostic_comparison	bool	False
contract_evaluation	bool	False
include_dependencies	bool	False
contract_mode	str \| None	None
pack_policy_overrides	dict[Any, Any] \| None	None
pack_internal_namespaces	tuple[str, ...] \| None	None
compile_context	CompileContext \| None	None
depth	str \| None	None
(keyword-only below)
severity_preset	str \| None	None
public_header_dirs	list[Path] \| None	None
collapse_versioned_symbols	bool	False
project_policy_overrides	dict[Any, Any] \| None	None
env_matrix	EnvironmentMatrix \| None	None
exclude_headers	tuple[str, ...]	()
acknowledgments_path	Path \| None	None
acknowledgment_unacknowledged_additions	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)
lang_explicit	bool	False
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
public_include_search_dirs	list[Path] \| None	None
include_dependencies	bool	False

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

sniff_text_format

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

Parameter	Type	Default
path	Path	(required)

Returns: str

to_stat

One-line summary for CI gates.

Parameter	Type	Default
result	DiffResult	(required)
(keyword-only below)
severity_config	SeverityConfig \| None	None

Returns: str

to_stat_json

JSON output for --stat mode: summary only, no changes array.

Parameter	Type	Default
result	DiffResult	(required)
indent	int	2
(keyword-only below)
severity_config	SeverityConfig \| None	None
require_complete_analysis	bool	False
show_only	str \| None	None
contract_evaluation	bool	False

Returns: str