Python API

The Python API is what a project needs to add its own knowledge to the SBOM: the hatchling build hook and the content provider it calls, 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 hatchling; the hook lives in python_sbom.hatch.

python_sbom.__version__: str

The installed version of python-sbom.

Hatchling build hook

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

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)

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

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

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.