# cyclonedx/cyclonedx-python architecture

> Architecture diagram of the GitHub repository cyclonedx/cyclonedx-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cyclonedx/cyclonedx-python
- Repository: https://github.com/cyclonedx/cyclonedx-python

## Overview

CycloneDX Python is a CLI tool that builds SBOMs from installed Python environments, requirements files, Poetry projects, or Pipenv projects. The user selects a source and options; the corresponding source handler reads package metadata and dependency declarations, constructs a CycloneDX BOM, and the CLI produces the requested document. The graph includes README-documented input branches, but their detailed wiring is not all visible in the sampled source. The environment and Poetry paths are supported by excerpts; other handler internals are represented at their exact tree paths.

Main entry points: [`cyclonedx_py/_internal/cli.py`](https://github.com/cyclonedx/cyclonedx-python/blob/main/cyclonedx_py/_internal/cli.py) (Command dispatcher), [`cyclonedx_py/_internal/environment.py`](https://github.com/cyclonedx/cyclonedx-python/blob/main/cyclonedx_py/_internal/environment.py) (Environment scan), [`cyclonedx_py/_internal/poetry.py`](https://github.com/cyclonedx/cyclonedx-python/blob/main/cyclonedx_py/_internal/poetry.py) (Poetry input), [`cyclonedx_py/_internal/requirements.py`](https://github.com/cyclonedx/cyclonedx-python/blob/main/cyclonedx_py/_internal/requirements.py) (Requirements input)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI entry"]
  node_module_entry["Module entry<br/>[__main__.py]"]
  node_cli["Command dispatcher<br/>[cli.py]"]
end

subgraph group_sources["Input sources"]
  node_env["Environment scan<br/>[environment.py]"]
  node_requirements["Requirements input<br/>[requirements.py]"]
  node_poetry["Poetry input<br/>[poetry.py]"]
  node_pipenv["Pipenv input<br/>[pipenv.py]"]
end

subgraph group_metadata["Metadata processing"]
  node_project_metadata["Project metadata<br/>[packagemetadata.py]"]
  node_pep621["PEP 621 parsing<br/>[pep621.py]"]
  node_license_map["License mapping"]
end

subgraph group_sbom["SBOM generation"]
  node_cdx_helpers["CycloneDX helpers<br/>[cdx.py]"]
  node_cyclonedx_lib["CycloneDX library"]
  node_sbom_output["SBOM document"]
end

node_user(("CLI user"))
node_environment_data[("Python environment")]
node_project_files["Project manifests"]

node_user -->|"runs module"| node_module_entry
node_user -->|"runs command"| node_cli
node_module_entry -->|"invokes"| node_cli
node_cli -->|"dispatches"| node_env
node_cli -->|"dispatches"| node_requirements
node_cli -->|"dispatches"| node_poetry
node_cli -->|"dispatches"| node_pipenv
node_environment_data -->|"provides packages"| node_env
node_project_files -->|"provides requirements"| node_requirements
node_project_files -->|"provides manifests"| node_poetry
node_project_files -->|"provides manifests"| node_pipenv
node_env -->|"reads metadata"| node_project_metadata
node_env -->|"uses BOM helpers"| node_cdx_helpers
node_poetry -->|"uses BOM helpers"| node_cdx_helpers
node_project_metadata -.->|"uses parsing"| node_pep621
node_pep621 -->|"maps classifiers"| node_license_map
node_env -->|"builds BOM"| node_cyclonedx_lib
node_requirements -->|"builds BOM"| node_cyclonedx_lib
node_poetry -->|"builds BOM"| node_cyclonedx_lib
node_pipenv -->|"builds BOM"| node_cyclonedx_lib
node_cli -->|"serializes BOM"| node_cyclonedx_lib
node_cyclonedx_lib -->|"emits document"| node_sbom_output

click node_module_entry "https://github.com/cyclonedx/cyclonedx-python/blob/main/cyclonedx_py/__main__.py"
click node_cli "https://github.com/cyclonedx/cyclonedx-python/blob/main/cyclonedx_py/_internal/cli.py"
click node_env "https://github.com/cyclonedx/cyclonedx-python/blob/main/cyclonedx_py/_internal/environment.py"
click node_requirements "https://github.com/cyclonedx/cyclonedx-python/blob/main/cyclonedx_py/_internal/requirements.py"
click node_poetry "https://github.com/cyclonedx/cyclonedx-python/blob/main/cyclonedx_py/_internal/poetry.py"
click node_pipenv "https://github.com/cyclonedx/cyclonedx-python/blob/main/cyclonedx_py/_internal/pipenv.py"
click node_project_metadata "https://github.com/cyclonedx/cyclonedx-python/blob/main/cyclonedx_py/_internal/py_interop/packagemetadata.py"
click node_pep621 "https://github.com/cyclonedx/cyclonedx-python/blob/main/cyclonedx_py/_internal/utils/pep621.py"
click node_license_map "https://github.com/cyclonedx/cyclonedx-python/blob/main/cyclonedx_py/_internal/utils/license_trove_classifier.py"
click node_cdx_helpers "https://github.com/cyclonedx/cyclonedx-python/blob/main/cyclonedx_py/_internal/utils/cdx.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_module_entry,node_cli,node_user toneBlue
class node_env,node_requirements,node_poetry,node_pipenv,node_environment_data toneAmber
class node_project_metadata,node_pep621,node_license_map toneMint
class node_cdx_helpers,node_cyclonedx_lib,node_sbom_output toneRose
class node_project_files toneIndigo
```

## Components

### CLI entry

- [Module entry](https://github.com/cyclonedx/cyclonedx-python/blob/main/cyclonedx_py/__main__.py): `cyclonedx_py/__main__.py`
- [Command dispatcher](https://github.com/cyclonedx/cyclonedx-python/blob/main/cyclonedx_py/_internal/cli.py): `cyclonedx_py/_internal/cli.py`

### Input sources

- [Environment scan](https://github.com/cyclonedx/cyclonedx-python/blob/main/cyclonedx_py/_internal/environment.py): `cyclonedx_py/_internal/environment.py`
- [Requirements input](https://github.com/cyclonedx/cyclonedx-python/blob/main/cyclonedx_py/_internal/requirements.py): `cyclonedx_py/_internal/requirements.py`
- [Poetry input](https://github.com/cyclonedx/cyclonedx-python/blob/main/cyclonedx_py/_internal/poetry.py): `cyclonedx_py/_internal/poetry.py`
- [Pipenv input](https://github.com/cyclonedx/cyclonedx-python/blob/main/cyclonedx_py/_internal/pipenv.py): `cyclonedx_py/_internal/pipenv.py`

### Metadata processing

- [Project metadata](https://github.com/cyclonedx/cyclonedx-python/blob/main/cyclonedx_py/_internal/py_interop/packagemetadata.py): `cyclonedx_py/_internal/py_interop/packagemetadata.py`
- [PEP 621 parsing](https://github.com/cyclonedx/cyclonedx-python/blob/main/cyclonedx_py/_internal/utils/pep621.py): `cyclonedx_py/_internal/utils/pep621.py`
- [License mapping](https://github.com/cyclonedx/cyclonedx-python/blob/main/cyclonedx_py/_internal/utils/license_trove_classifier.py): `cyclonedx_py/_internal/utils/license_trove_classifier.py`

### SBOM generation

- [CycloneDX helpers](https://github.com/cyclonedx/cyclonedx-python/blob/main/cyclonedx_py/_internal/utils/cdx.py): `cyclonedx_py/_internal/utils/cdx.py`
- **CycloneDX library**
- **SBOM document**

### Other components

- **CLI user**
- **Python environment**
- **Project manifests**

## Connections

- CLI user → Module entry: runs module
- CLI user → Command dispatcher: runs command
- Module entry → Command dispatcher: invokes
- Command dispatcher → Environment scan: dispatches
- Command dispatcher → Requirements input: dispatches
- Command dispatcher → Poetry input: dispatches
- Command dispatcher → Pipenv input: dispatches
- Python environment → Environment scan: provides packages
- Project manifests → Requirements input: provides requirements
- Project manifests → Poetry input: provides manifests
- Project manifests → Pipenv input: provides manifests
- Environment scan → Project metadata: reads metadata
- Environment scan → CycloneDX helpers: uses BOM helpers
- Poetry input → CycloneDX helpers: uses BOM helpers
- Project metadata → PEP 621 parsing: uses parsing
- PEP 621 parsing → License mapping: maps classifiers
- Environment scan → CycloneDX library: builds BOM
- Requirements input → CycloneDX library: builds BOM
- Poetry input → CycloneDX library: builds BOM
- Pipenv input → CycloneDX library: builds BOM
- Command dispatcher → CycloneDX library: serializes BOM
- CycloneDX library → SBOM document: emits document