Python API

The Python API is what a build backend loads and what a project needs to add its own knowledge to the SBOM: the backend integrations and the content provider they call, with the types those take and return. Everything else, from embedding to validation, runs through the Command line interface. The core is importable from python_sbom without any build backend; each integration lives in a module of its own and imports only its backend.

python_sbom.__version__: str

The installed version of python-sbom.

Backend integrations

class python_sbom.hatch.SbomBuildHook(root, config, build_config, metadata, directory, target_name, app=None)

Bases: BuildHookInterface

Hatchling build hook that writes a CycloneDX SBOM into the wheel’s .dist-info/sboms/, as PEP 770 describes.

It runs once hatchling has written the wheel, so the SBOM describes the wheel’s final metadata and file name whatever other hooks changed. Options come from [tool.python-sbom], the one place python-sbom embed and python-sbom archive read them too. For an sdist it records the source revision, so a wheel built from that sdist still names its commit.

Variables:

PLUGIN_NAME – the hook’s name in [tool.hatch.build.hooks]

Parameters:

  • root (str)

  • config (dict[str, Any])

  • build_config (BuilderConfigBound)

  • metadata (ProjectMetadata)

  • directory (str)

  • target_name (str)

  • app (Application | None, default: None)

content_provider()

Return what the project adds to its SBOM.

Override it in a hatchling custom build hook to build the provider with what the hook knows; the content-provider option is then ignored.

Return type:

ContentProvider

Returns:

the content-provider option’s provider, or one that adds nothing

class python_sbom.pdm.SbomBuildHook

Bases: object

Write the SBOM into a wheel pdm-backend built, and record the source revision in an sdist.

pdm_build_hook_enabled(context)

Act only on a project that asks for an SBOM.

Parameters:

context (Context) – pdm-backend’s build context

Return type:

bool

Returns:

whether [tool.python-sbom] exists and the build is a wheel or an sdist

pdm_build_initialize(context)

Read the source revision, before the build writes into the checkout.

Parameters:

context (Context) – pdm-backend’s build context

Return type:

None

pdm_build_update_files(context, files)

Add the source revision to an sdist, so a wheel built from it still names its commit.

Parameters:

  • context (Context) – pdm-backend’s build context

  • files (dict[str, Path]) – the files the artifact will hold, by their path in it

Return type:

None

pdm_build_finalize(context, artifact)

Write the SBOM into the wheel pdm-backend built.

Parameters:

  • context (Context) – pdm-backend’s build context

  • artifact (Path) – the built wheel or sdist

Return type:

None

python_sbom.setuptools.finalize_distribution_options(distribution)

Wrap the wheel and sdist commands of a project that asks for an SBOM.

Parameters:

distribution (Distribution) – the distribution setuptools is about to build

Raises:

SbomError – when the project’s pyproject.toml is not valid TOML or replaces the wheel or sdist command, or the wheel command writes no wheel

Return type:

None

python_sbom.backend.build_wheel(wheel_directory, config_settings=None, metadata_directory=None)

Build a wheel with the wrapped backend, then write the SBOM into it.

Parameters:

  • wheel_directory (str) – where the wheel goes

  • config_settings (Mapping[str, str | list[str]] | None, default: None) – the frontend’s settings, passed on unchanged

  • metadata_directory (str | None, default: None) – the .dist-info an earlier prepare_metadata_for_build_wheel call wrote

Return type:

str

Returns:

the wheel’s file name

python_sbom.backend.build_sdist(sdist_directory, config_settings=None)

Build an sdist with the wrapped backend, then record the source revision in it.

Parameters:

  • sdist_directory (str) – where the sdist goes

  • config_settings (Mapping[str, str | list[str]] | None, default: None) – the frontend’s settings, passed on unchanged

Return type:

str

Returns:

the sdist’s file name

Content provider

class python_sbom.ContentProvider

Bases: object

Adds what a project knows beyond its metadata to its SBOM; subclass it and override what the project needs.

Name a subclass in the content-provider option, which the hook, python-sbom embed and python-sbom archive load, or return an instance from python_sbom.hatch.SbomBuildHook.content_provider(). When the class lives in the project, the SBOM lists its module among the build tools.

bundled_wheel(context, wheel)

Describe what the project does with a wheel it bundles, as a file or unpacked into a directory.

Parameters:

  • context (ProviderContext) – the project and the artifact being described

  • wheel (PurePosixPath) – the wheel’s path inside the artifact

Return type:

BundledWheelInfo

Returns:

its extra properties, and whether the project’s supplier supplies it; neither by default

contributions(context)

Add components, their dependencies, root properties and build tools, before references and the serial derive.

Parameters:

context (ProviderContext) – the project and the artifact being described

Return type:

Contributions

Returns:

the contributions; none by default

class python_sbom.ProviderContext(*, root, settings, identity, read)

Bases: object

What a content provider may use about the build it contributes to.

Parameters:

  • root (Path) – the project directory

  • settings (Settings) – the project’s options

  • identity (ProjectIdentity) – how the project’s SBOMs name it, including the prefix of its properties

  • read (Callable[[PurePosixPath], bytes]) – reads a member of the artifact being described, for read()

read(path)

Read a file of the artifact being described: a member of the built wheel or of the archive.

Parameters:

path (PurePosixPath) – the file’s path inside the artifact, as a bundled wheel’s path is given

Return type:

bytes

Returns:

the file’s bytes

Raises:

KeyError – when the artifact holds no such file

class python_sbom.BundledWheelInfo(*, properties=list(), supplier=None)

Bases: object

What a project adds to the component of one bundled wheel.

Both fields default to empty, so a provider names only what it adds.

Parameters:

  • properties (list[Property], default: list()) – properties after <prefix>:bundled-wheel, before those from the wheel’s metadata

  • supplier (OrganizationalEntity | None, default: None) – the wheel’s supplier, or None to name none; only the project decides a bundled wheel’s supplier, never the wheel’s own metadata

class python_sbom.Contributions(*, components=list(), dependencies=list(), root_properties=list(), tools=list())

Bases: object

What a project adds to the document beyond its bundled wheels, merged before references and the serial are derived.

Each field defaults to empty, so a provider names only what it adds. The build fails when a component or tool lacks type, bom-ref or name, a bom-ref repeats, the formula: and workflow: refs of the build’s formulation included, a dependency names one that does not exist, or a bom-ref gets a second dependency entry, as the root does if a provider adds one, since python-sbom writes the root’s.

Parameters:

  • components (list[Component], default: list()) – extra top-level components, such as vendored C libraries; the root depends on each, and a component’s own parts nest under its components

  • dependencies (list[Dependency], default: list()) – extra dependency entries, such as the dependencies of those components

  • root_properties (list[Property], default: list()) – extra properties of the root component; their names must not start with the project’s prefix, which python-sbom’s own properties use

  • tools (list[Component], default: list()) – extra build tools

class python_sbom.Settings(*, supplier, repository, default_branch, bundled_wheels, content_provider, build_backend)

Bases: object

The project’s options, from [tool.python-sbom].

Parameters:

  • supplier (OrganizationalEntity | None) – the organization that supplies the project, or None to name none

  • repository (str | None) – the repository URL, or None to take the first Source, Repository or GitHub project URL

  • default_branch (str) – the branch in links to files in the repository when the build’s commit is unknown or has uncommitted changes

  • bundled_wheels (tuple[str, ...]) – glob patterns, relative to the project directory, of wheels the project ships as data files

  • content_provider (str | None) – module:attribute of the content provider, or None

  • build_backend (str | None) – the build backend python_sbom.backend wraps, as module or module:object, or None

class python_sbom.ProjectIdentity(*, property_prefix, repository, serial_namespace)

Bases: object

How every SBOM of a project names it.

Parameters:

  • property_prefix (str) – the project’s normalized name, which starts the names of the properties python-sbom writes, such as virtualenv in virtualenv:bundled-wheel

  • repository (str | None) – the repository URL, from the options or the first Source, Repository or GitHub project URL, or None

  • serial_namespace (UUID) – the UUID namespace of the serial numbers of the project’s SBOMs

Component types

These TypedDict types describe the JSON a provider builds. Each follows the CycloneDX 1.6 object of the same name; the CycloneDX 1.6 reference describes every key.

class python_sbom.Component

A CycloneDX 1.6 component, a distribution, an application, the interpreter or a file, as a dictionary with the keys the CycloneDX component object defines. python-sbom uses type, bom-ref, name, version, purl, supplier (an OrganizationalEntity), authors (Contact), description, licenses (License), copyright, hashes (Hash), externalReferences (ExternalReference), properties (Property), evidence (Evidence) and the nested components.

class python_sbom.Property

Bases: TypedDict

A name and value pair attached to a component or the document.

Variables:

  • name (str) – the property’s name; names this package writes start with the project’s prefix or python:

  • value (str) – the property’s value

class python_sbom.Dependency

Bases: TypedDict

The components one component depends on.

Variables:

  • ref (str) – the bom-ref of the dependent component

  • dependsOn (NotRequired[list[str]]) – the bom-ref values of its dependencies

class python_sbom.OrganizationalEntity

Bases: TypedDict

An organization that supplies or makes a component.

Variables:

  • name (str) – the organization’s name

  • url (list[str]) – the organization’s web sites

class python_sbom.Contact

Bases: TypedDict

A person who wrote or maintains a component.

Variables:
class python_sbom.ExternalReference

Bases: TypedDict

A link from a component to something about it.

Variables:

  • type (str) – the CycloneDX reference type, such as vcs or website

  • url (str) – the link

  • comment (NotRequired[str]) – what the link is, such as the Project-URL label it came from

  • hashes (NotRequired[list[Hash]]) – digests of what the link points at

class python_sbom.Hash

Bases: TypedDict

A digest of a component’s bytes.

Variables:

  • alg (str) – the algorithm as CycloneDX names it, such as SHA-256

  • content (str) – the digest as lowercase hex

class python_sbom.License

Bases: TypedDict

One license entry of a component: a license or an SPDX expression.

Variables:
class python_sbom.LicenseInfo

Bases: TypedDict

One license, by SPDX id or by name.

Variables:

  • id (NotRequired[str]) – the SPDX license id

  • name (NotRequired[str]) – the license’s name, when it has no SPDX id

  • acknowledgement (str) – declared when the metadata names it, concluded when python-sbom resolved it

class python_sbom.Evidence

Bases: TypedDict

Why a component is what it says it is.

Variables:

identity (list[Identity]) – the evidence per field

class python_sbom.Identity

Bases: TypedDict

The evidence for one field of a component’s identity.

Variables:

  • field (str) – the field it supports, such as purl or hash

  • confidence (int) – from 0 to 1

  • methods (list[IdentityMethod]) – how it was established

class python_sbom.IdentityMethod

Bases: TypedDict

How a component’s identity was established.

Variables:

  • technique (str) – the CycloneDX technique, such as manifest-analysis or hash-comparison

  • confidence (int) – from 0 to 1

  • value (str) – what the technique read, such as the path of a METADATA file or a digest

Errors

exception python_sbom.SbomError

Bases: Exception

Base of the errors this package raises; the command line reports them without a traceback.

exception python_sbom.MissingExtraError

Bases: SbomError

Raised when validation needs an optional dependency that is not installed.