API Stability#
This page defines the current public contract guarantees in DepDigest.
Public API surface#
The public API is defined by depdigest.__all__.
Current exported symbols:
is_installedcheck_dependencyget_infodep_digestLazyRegistryDeclaredRegistry(from 0.14.0)DepConfigresolve_configregister_package_configunregister_package_configtemporary_package_configclear_package_configs
Compatibility rule:
removing or renaming these symbols is a breaking change.
get_info schema contract#
For format="dict" and format="json", the schema is:
name:
depdigest.get_infoversion:
1.0
Top-level keys:
schemamodule_pathdependency_countinstalled_countmissing_countdependencies
Dependency entry keys:
libraryinstalledstatustypepackage_nameinstall
Compatibility rule:
changing/removing keys or schema version without migration notes is a breaking change.
CLI contract#
depdigest audit behavior expected by integrators:
returns
0when no violations are found;returns
1when violations exist (unless--allow-violations);--jsonoutput is machine-readable and deterministic.
From 0.13.0, audits include module/class control flow. An audit can report
additional imports and return 1 on unchanged consumer source. Function bodies
remain delayed; simple explicit, unrebound typing.TYPE_CHECKING guards exclude
their typing branch. Unresolved or compound conditions are scanned conservatively.
The audit is neither a runtime reachability proof nor a syntax validator.
See the audit CLI scope and the 0.13.0 migration notes
in CHANGELOG.md before upgrading an audit gate.
From 0.15.2, correction #47/#48 excludes relative internal adapter imports from external optional-dependency findings. Absolute imports and the CLI schema, source-line and exit contracts remain unchanged. Public 0.15.1 does not include this correction; exact-file admission is tracked in #49.
Change management guidance#
DeclaredRegistry retains legacy registry behavior and separates metadata from
materialization. Its ordering, mutation, filtering, discovery and cache contracts
are defined in the registry contract. Source
experiments must pin the implementation commit; consumer public adoption requires
published DepDigest >=0.14.0 before changing dependency floors. Publication is
tracked in DepDigest #35 and consumer qualification in MolSysMT #382.
From 0.15.0, #36 adds keyword-only load_policy="adapter" for explicit adapter
inspection. Omission or "strict" preserves 0.14.0’s dependency precheck; visibility,
identity, caching and execution guards retain their contracts. Public 0.14.0 does
not accept this option. Public adoption requires admitted DepDigest >=0.15.0, tracked in #37; controlled
source pins alone do not establish publication or consumer conversion parity.
From 0.15.1, #39 serializes overlapping declared value requests on a shared
DeclaredRegistry through initialization. Waiters share the cached value or
failure cause; genuine recursion still fails. The constructor, defaults and
legacy registry remain unchanged. Mutation/discovery/configuration changes and
arbitrary cross-registry cycles require separate coordination. See the bounded
concurrent reader contract.
Public use requires admitted DepDigest >=0.15.1; source-only checks do not admit it.
Before changing public behavior:
add/update contract tests first;
update this page and
standards/DEPDIGEST_GUIDE.md;call out compatibility impact in PR/release notes.