Audit CLI#

DepDigest includes a lightweight CLI command to detect imports of soft dependencies in source scopes that can execute while a module is imported.

This helps you enforce lazy-import architecture in CI before regressions reach users.

Basic command#

depdigest audit --src-root my_pkg --soft-deps openmm,mdtraj

Behavior:

  • exit code 0: no violations found;

  • exit code 1: one or more top-level soft-dependency imports found.

What the audit scans#

The audit includes imports inside module-level if, try (including handlers, else and finally), loops, with, match and class bodies. It skips function and async-function bodies, including classes defined inside those functions. Original source line numbers are retained in text and JSON output.

From 0.15.2 (#47/#48), relative imports such as from .vina import VinaBackend name an internal adapter and are excluded from external-package findings. Absolute from vina import Vina and import vina remain reportable. Version 0.15.1 predates this correction. Publication and exact-file admission are tracked in #49; source-only checks do not qualify a package.

Simple type-check-only branches are excluded when their guard uses an explicit import from typing, including aliases:

from typing import TYPE_CHECKING as TC

if TC:
    import openmm  # excluded: this branch is only for type checking
else:
    import mdtraj  # reported: this is a runtime branch

import typing as t followed by if t.TYPE_CHECKING: and negated guards are also recognized. If the name is rebound anywhere in eager source, a wildcard import can shadow it, or the condition has another shape, both branches are scanned conservatively. Assignments to a recognized module’s TYPE_CHECKING attribute also disable its exemption. Rebindings inside delayed function bodies do not change this scan.

Other conditions are not evaluated: even if False: is scanned. The audit does not follow calls, dynamic imports or module reachability. An optional adapter loaded only on request can still contain an import that is reported when its source is audited; inspect that boundary before choosing an explicit exemption. Syntax-error files retain the historical behavior of producing no findings. A zero exit code is therefore not a syntax check or proof of absent runtime import leaks; pair the audit with compilation and relevant import regressions.

CI-friendly JSON output#

depdigest audit --src-root my_pkg --soft-deps openmm --json

Exemptions#

Use exemptions for generated files or intentionally eager modules:

depdigest audit \
  --src-root my_pkg \
  --soft-deps openmm \
  --exempt-file my_pkg/legacy_bridge.py \
  --exempt-dir my_pkg/tests

Allow violations temporarily#

If you need a non-blocking transition period:

depdigest audit --src-root my_pkg --soft-deps openmm --allow-violations

This still reports violations but returns exit code 0.

Next#

Use the Production Checklist to finalize release readiness.