Skip to content

Hatchling build hook

Use this when you build wheels with Hatchling and want an SBOM embedded automatically -- no separate CLI step to remember.

Pitloom embeds the SBOM at .dist-info/sboms/<name>-<version>.spdx3.json (e.g. .dist-info/sboms/mypackage-1.0.0.spdx3.json), per PEP 770 (wheels only), as compact canonical JSON.

Quick guide

[build-system]
requires = ["hatchling>=1.32.0", "pitloom>=0.16.4"]
build-backend = "hatchling.build"

[tool.hatch.build.hooks.pitloom]
# This can be empty

That's all -- hatch build and python -m build now embed the SBOM.

Installation

Add pitloom as a build requirement (Hatchling 1.29.0+ required) and add the [tool.hatch.build.hooks.pitloom] table to pyproject.toml (as shown above) -- both parts are required. Listing pitloom under [build-system] requires alone does not activate the hook: Hatchling only runs hooks whose name appears under [tool.hatch.build.hooks], so the table itself is what turns it on, even left empty.

No separate pip install step is needed beyond that -- the build front-end (pip, build, hatch) installs pitloom as a build-time dependency automatically, the same way it installs Hatchling itself.

Usage details

Every hatch build/python -m build invocation now:

  1. Generates a Source SBOM for the project being built.
  2. Merges in any fragments registered under [tool.pitloom.fragment] (see the Python API tracking decorator, or a hand-authored fragment).
  3. Embeds the result into the wheel's .dist-info/sboms/ directory.

The table's enabled key defaults to true, so an empty [tool.hatch.build.hooks.pitloom] is enough. Set enabled = false inside it to skip generation for a particular build without removing the table.

Configuration

Basename and fragments are configured under [tool.pitloom]:

[tool.pitloom]
sbom-basename = "custom-bom"       # -> "custom-bom.spdx3.json" (default: "<name>-<version>")

[tool.pitloom.fragment]
files = ["fragments/model.json"]   # merge externally tracked fragments

Creator/tool metadata uses the same [[tool.pitloom.creator]] / [[tool.pitloom.creation-tool]] / [tool.pitloom.creation] tables the CLI reads -- see Creation metadata. Provenance detail is controlled the same way too -- see Metadata provenance.

See also

  • Command line -- generate an SBOM manually or post-process built wheels with loom embed-wheel.
  • GitHub Action -- embed PEP 770 SBOMs in CI for any build backend.
  • Python API -- the tracking decorator that produces the fragments this hook merges.