Python API

Python API reference

Typed Python interface to the same Rust engine used by the depsmith CLI.

Discover targets, prepare a reviewable proposal, inspect its file and dependency changes, suggestions and scans, then apply it exactly as reviewed. Functions never prompt or exit the interpreter; failures raise ConfigurationError, OperationError, StaleProposalError or PolicyError. Terms follow the project glossary (CONTEXT.md).

Functions

discover(root: Path = '.') -> tuple[Target, ...]

Find the targets under root, skipping ignored and environment directories.

Args

• root: Repository root.

Returns

• The discovered targets.

prepare(root: Path = '.', *, targets: Sequence[str] = (), options: UpdateOptions | None = None) -> Proposal

Prepare a reviewable proposal for the selected targets.

Each target is resolved in a stage; the repository is not modified. A target that cannot be prepared is recorded in Proposal.failures.

Args

• root: Repository root.
• targets: Target identifiers; empty uses the saved selection.
• options: Options overriding the repository settings.

Returns

• The proposal to review and apply.

Raises

• ConfigurationError: Invalid options, no or unknown targets, or selected packages that are not direct dependencies.

Example

>>> import pathlib, tempfile, depsmith
>>> repo = tempfile.mkdtemp()
>>> _ = pathlib.Path(repo, "pixi.toml").write_text("[workspace]\nname = 'demo'\n")
>>> options = depsmith.UpdateOptions(pixi="no-such-pixi")
>>> proposal = depsmith.prepare(repo, targets=["pixi:pixi.toml"], options=options)
>>> [f.code for f in proposal.failures]
[3]

scan(root: Path = '.', *, targets: Sequence[str] = (), options: UpdateOptions | None = None) -> tuple[ScanReport, ...]

Scan the current locks of the selected targets without updating.

There is no baseline to compare against, so every report is candidate-only.

Args

• root: Repository root.
• targets: Target identifiers; empty uses the saved selection.
• options: Options; scanning is enabled by default.

Returns

• One report per target.

Raises

• ConfigurationError: Invalid options, unknown targets, or a target without a lock to scan.
• OperationError: The scanner failed.

Example

>>> import tempfile, depsmith
>>> depsmith.scan(tempfile.mkdtemp(), targets=["missing"])
Traceback (most recent call last):
...
depsmith.ConfigurationError: invalid request: unknown target: missing

doctor(root: Path = '.', *, options: UpdateOptions | None = None) -> dict[str, Any]

Report adapter capabilities and whether each native tool is available.

Args

• root: Repository root whose settings apply.
• options: Options overriding the repository settings.

Returns

• The same report as depsmith doctor --json.

recover(root: Path = '.') -> tuple[str, ...]

Restore the files of an interrupted apply from its journal.

Args

• root: Repository root.

Returns

• The restored paths, relative to the root.

Raises

• ConfigurationError: There is no interrupted operation to recover.
• StaleProposalError: A file changed after the interruption.

Classes

ApplyResult(schema_version: int, applied: tuple[str, ...], partial: bool)

What applying a proposal wrote.

Attributes

• schema_version: Version of the report format.
• applied: Files written, relative to the repository root.
• partial: Whether only the successful targets were applied.

DependencyChange(before: Package | None, after: Package | None, introducers: tuple[str, ...], paths: tuple[tuple[str, ...], ...])

A package that differs between the baseline and the candidate.

Attributes

• before: The package before the update; None when added.
• after: The package after the update; None when removed.
• introducers: The declared dependencies whose dependency paths reach the package; empty for a declared package, or when the target's adapter reads no lock graph.
• paths: The shortest dependency path from each introducer to the package.

Failure(target: str, message: str, code: int)

A target whose candidate could not be prepared.

Attributes

• target: Identifier of the failed target.
• message: What went wrong, with redacted backend output.
• code: CLI exit status category of the failure.

FileChange(target: str, path: str, before: str | None, after: str, diff: str)

The exact new content of one file in a proposal.

Attributes

• target: Identifier of the target the file belongs to.
• path: Path relative to the repository root.
• before: Current content; None when the file does not exist yet.
• after: Content that applying the proposal writes.
• diff: Unified diff from before to after.

Finding(id: str, namespace: str, package: str, version: str, severity: str, evidence: Any, identity: str, applicability: str, artifact: str, suppression: Suppression | None)

One advisory matched to one inventory package.

Attributes

• id: Advisory identifier.
• namespace: Advisory namespace reported by the scanner.
• package: Name of the affected package.
• version: Version of the affected package.
• severity: Severity as reported, such as High.
• evidence: The scanner's match details, verbatim.
• identity: ecosystem:name:platform of the package.
• applicability: upstream, or why applicability to this build is unknown.
• artifact: The resolved artifact.
• suppression: The suppression covering this finding, if any.

IdentityMapping(ecosystem: str, name: str, purl: str, evidence: str)

A reviewed statement that a package is the same software as an upstream identity.

Attributes

• ecosystem: Ecosystem of the mapped package, such as conda.
• name: Package name in that ecosystem.
• purl: Unversioned Package URL, such as pkg:pypi/urllib3.
• evidence: HTTPS link to the provenance that establishes the mapping.

Package(ecosystem: str, name: str, version: str, artifact: str, platform: str)

One resolved package in an inventory.

Attributes

• ecosystem: Ecosystem of the identity, such as conda or pypi.
• name: Package name as the ecosystem spells it.
• version: Resolved version; empty when the lock records none.
• artifact: The exact artifact or reference resolved.
• platform: Platform resolved for, such as linux-64.

Proposal

The reviewable outcome of preparing one or more targets.

A read-only report with an opaque native handle to the reviewed candidate. JSON reports cannot be imported as executable proposals, so preparation and application must occur in the same process.

Attributes

• schema_version: Version of the report format.
• root: Canonical repository root.
• targets: Targets that were prepared.
• changes: Exact file changes that applying writes.
• dependencies: Packages that change, including transitive ones.
• suggestions: Suggestions about declared constraints.
• unresolved: References left unchanged because they could not be resolved.
• failures: Targets that could not be prepared.
• validation: Validation levels completed and acceptance notes.
• scans: Vulnerability scan reports, when scanning was requested.

Proposal.to_dict(self) -> dict[str, Any]

Return the proposal as the same JSON-compatible report the CLI prints.

Proposal.apply(self, *, allow_partial: bool = False) -> ApplyResult

Write exactly the reviewed files, without resolving again.

Args

• allow_partial: Apply the successful targets of a proposal with failures instead of refusing.

Returns

• The files written.

Raises

• StaleProposalError: The repository changed since preparation.
• OperationError: Targets failed and allow_partial is false, or another operation holds the repository lock.

Example

>>> import pathlib, tempfile, depsmith
>>> repo = tempfile.mkdtemp()
>>> _ = pathlib.Path(repo, "pixi.toml").write_text("[workspace]\nname = 'demo'\n")
>>> options = depsmith.UpdateOptions(pixi="no-such-pixi")
>>> proposal = depsmith.prepare(repo, targets=["pixi:pixi.toml"], options=options)
>>> proposal.apply()
Traceback (most recent call last):
...
depsmith.OperationError: operation failed: some targets failed; explicit partial application required

ScanReport(target: str, baseline_available: bool, comparison: str, database: dict[str, Any], findings: tuple[Finding, ...], introduced: tuple[Finding, ...], resolved: tuple[Finding, ...], remaining: tuple[Finding, ...], unknown_before: tuple[Package, ...], unknown_after: tuple[Package, ...], applicability: str, expired_suppressions: tuple[Suppression, ...], policy_passed: bool)

Vulnerability findings for one target, classified against the baseline.

Packages that could not be assessed are listed as unknown, never treated as clean.

Attributes

• target: Identifier of the scanned target.
• baseline_available: Whether a baseline lock existed.
• comparison: baseline, or candidate-only without a baseline.
• database: Status of the vulnerability database snapshot used.
• findings: Every candidate finding.
• introduced: Findings in the candidate but not the baseline.
• resolved: Findings in the baseline but not the candidate.
• remaining: Findings in both.
• unknown_before: Baseline packages that could not be assessed.
• unknown_after: Candidate packages that could not be assessed.
• applicability: What the findings establish about applicability.
• expired_suppressions: Suppressions that had expired and were ignored.
• policy_passed: Whether the configured policy accepted the findings.

Suggestion(target: str, package: str, requirement: str, reason: str, evidence: tuple[str, ...])

An evidence-backed report that a declared constraint is worth revisiting.

Attributes

• target: Identifier of the target that declares the constraint.
• package: The constrained direct dependency.
• requirement: The declared requirement, as written.
• reason: Why it is reported and how to act on it.
• evidence: Sources of the claim, such as artifact URLs with SHA-256.

Suppression(id: str, reason: str, package: str | None, target: str | None, expires: str | None)

A documented, scoped exception for one advisory.

Suppressed findings stay in reports and are only excluded from policy gates. A reason and a package or target scope are required.

Attributes

• id: Advisory identifier, such as GHSA-… or CVE-….
• reason: Why the finding is acceptable.
• package: ecosystem:name scope, such as pypi:urllib3.
• target: Target identifier scope, such as pixi:pixi.toml.
• expires: Last day (YYYY-MM-DD, UTC) the suppression applies.

Target(id: str, manager: str, manifest: str)

A manifest or workflow file that depsmith updates.

Attributes

• id: Stable identifier manager:path, such as pixi:pixi.toml.
• manager: The package manager that owns the target.
• manifest: Path of the file, relative to the repository root.

Unresolved(target: str, package: str, reference: str, reason: str)

A reference left unchanged because it could not be resolved.

Attributes

• target: Identifier of the target containing the reference.
• package: The referenced package, such as an action repository.
• reference: The reference as written, such as org/repo@main.
• reason: Why no release could be matched.

UpdateOptions(packages: Sequence[str] | None, accept: Sequence[str] | None, upgrade: bool | None, refresh_git: bool | None, cooldown_days: int | None, install: bool | None, scan: bool | None, fail_on: str | None, only_new: bool | None, tools: Mapping[str, str] | None, pixi: str | None, grype: str | None, timeout_seconds: int | None, identity_mappings: Sequence[IdentityMapping] | None, suppressions: Sequence[Suppression] | None)

Options for preparing, scanning and applying updates.

None inherits the repository settings from depsmith.toml; explicit values override them.

Attributes

• packages: Direct dependencies to update; empty means the whole target.
• accept: NAME or NAME=REQUIREMENT suggestions to accept.
• upgrade: Allow the selected packages' constraints to change.
• refresh_git: Allow Git pins to move to newer commits.
• cooldown_days: Minimum release age; rejected where not enforceable.
• install: Also install the candidate's default environment on this host.
• scan: Scan the baseline and candidate for known vulnerabilities.
• fail_on: Lowest severity that rejects the proposal.
• only_new: Apply fail_on only to introduced findings.
• tools: Executable paths by tool name, such as {"pixi": "/opt/pixi"}; doctor() lists the tool names.
• pixi: Deprecated alias for tools["pixi"].
• grype: Deprecated alias for tools["grype"].
• timeout_seconds: Time limit for each backend process.
• identity_mappings: Reviewed identity mappings used when scanning.
• suppressions: Scoped, documented suppressions.

Exceptions

ConfigurationError

Invalid options, configuration or targets, or an unmet precondition (CLI exit 2).

OperationError

A package manager, scanner or other operation failed (CLI exit 3).

PolicyError

A configured policy, such as a vulnerability gate, rejected the proposal (CLI exit 4).

StaleProposalError

The repository changed since the proposal was prepared; prepare it again.