[gaborbernat]

Projects that ship wheels have no reusable way to put a software bill of materials where PEP 770 tells installers to keep it, in .dist-info/sboms/. virtualenv carries its own generator, and the other tox-dev projects carry none. python-sbom turns that generator into a package: a hatchling project enables a build hook with one table in pyproject.toml, a project on another backend such as meson-python runs python-sbom embed on the built wheel, and python-sbom archive describes other zip artifacts, such as virtualenv's zipapp. 📦

The CycloneDX 1.6 document records the project, the runtime dependencies it declares, the wheels it bundles, and the build toolchain down to file hashes. Nothing about the build machine goes in, so a rebuild with the same inputs reproduces it byte for byte. python-sbom spdx renders it as SPDX 2.3. python-sbom validate takes CycloneDX input only: it checks the document against the official CycloneDX schema, shipped with the package so validation works offline. For documents python-sbom wrote, it also checks the references and the SPDX rendering, plus an optional licence allow-list.

Architecture

The hatch hook and the command line sit at the edge: they gather the options, the content provider, the build scripts and the build facts, then call the pipeline for their artifact. Each pipeline opens the wheel or archive once and reads it into a tree, then a pure function of the model maps that tree to components. One shared step adds what every artifact of the project carries, and the result is written back. Nothing below the hook imports hatchling, so the command line installs without it.

flowchart LR
    hook[hatch hook] --> pipelines
    cli[CLI: embed / archive / spdx / validate] --> pipelines
    pipelines[wheel and archive pipelines] --> collect[collect: settings, facts, revision, wheel or archive tree]
    collect --> reader[artifact reader: one checked handle per build]
    pipelines --> model[model: pure document building, shared graph rules]
    pipelines --> formats[CycloneDX JSON / SPDX 2.3]
    pipelines --> write[wheel and archive writing]
    provider[ContentProvider] --> pipelines
    cli --> validate[validate: schemas, references, licences]
    validate --> model
    classDef edge fill:#cfe4ff,stroke:#1f6feb,color:#0b1f3a;
    classDef core fill:#d8f3dc,stroke:#2d6a4f,color:#081c15;
    class hook,cli,provider edge;
    class pipelines,collect,reader,model,formats,write,validate core;

Loading

The SBOM describes the bytes the artifact ships. Bundled wheels are matched to the artifact's own copies by digest and read from there, so a source wheel that changed after the build is refused rather than described. Generation, validation and the licence policy share one definition of what an artifact holds and one reference check, so they judge the same components wherever the document places them.

Projects extend the document through one seam: a ContentProvider receives a ProviderContext (project root, settings, identity, and a reader for the artifact's members) and returns Contributions: extra components, dependencies, root properties and tools. virtualenv uses it to describe the pip and setuptools wheels it seeds, in both its wheel and its zipapp, with no private imports. The public API is that seam plus every type it exposes, and a test fails if a public signature reaches a private type.

Behaviour worth knowing

• Wheels are read and rewritten in place: unchanged members keep their bytes, and only RECORD and the new SBOM are written. Bundled wheels are checked against their RECORD before anything about them is recorded.
• The source commit comes from git when the project is tracked, from an sdist built by the hook, or from .git_archival.txt; a modified checkout is marked dirty.
• Validation uses jsonschema-rs, which agreed with python-jsonschema on every document except cases where python-jsonschema contradicts the RFCs. Hostile documents are bounded by size, depth and a component cap of 100,000 (adjustable with --max-components).
• python-sbom's own wheel carries its own SBOM, and the package check validates it.