[juliosuas]

Description

Early draft to showcase the results for #597, as suggested in #597 (comment).

Implements the expected outcome from #597 (comment) for cyclonedx-py environment only:
when CycloneDX 1.7 is requested, the Python runtime of the analyzed environment is added as a component with type=platform and isExternal=true.

Example (cyclonedx-py environment --sv 1.7 --pyproject pyproject.toml .venv):

"components": [
  {
    "bom-ref": "python-runtime",
    "isExternal": true,
    "name": "python",
    "type": "platform",
    "version": "3.13.5"
  }
],
"dependencies": [
  { "ref": "python-runtime" },
  { "dependsOn": ["python-runtime"], "ref": "root-component" }
]

<component type="platform" bom-ref="python-runtime" isExternal="true">
  <name>python</name>
  <version>3.13.5</version>
</component>

Behavior:

• Only for spec version 1.7+. Output for 1.6 and lower is unchanged, and so is the default (--sv 1.6).
• name is python, version is platform.python_version() of the analyzed interpreter. For a target <python> (and for -S/-E without a target) the version is probed from that interpreter with the same flags as the path detection. The implementation (CPython, PyPy, etc.) is not recorded.
• If a root component is known (--pyproject), it depends on the runtime component. Without a root component, the runtime appears as a standalone node in the dependency graph.
• isExternal needs cyclonedx-python-lib>=11.12. The supported range stays >=8, <12; with an older lib the runtime component is omitted, so nothing breaks.
• poetry, requirements and pipenv are not covered in this draft.

Details open for discussion:

• Scope: keep this to environment only, or should poetry/requirements/pipenv also emit the runtime component (e.g. from python-requires / markers) in this PR or a follow-up?
• Enabled implicitly by --sv 1.7, or behind an explicit switch?
• bom-ref value python-runtime.
• Whether to add a PURL/CPE or properties (OS, architecture). Left out for now.
• Feature detection of is_external vs. raising the lib floor to >=11.12.

Tests:

• 1.7 environment snapshots regenerated with CDX_TEST_RECREATE_SNAPSHOTS=1. The runtime version is normalized in tests/__init__.py (pythonVersion-testing), so snapshots do not depend on the interpreter running the tests.
• New integration tests: runtime component and root dependency for 1.7; version matches the analyzed interpreter (target, current, -S, -E); omitted for spec versions < 1.7; omitted when the lib lacks is_external.
• Docs: docs/usage.rst, environment section.

Resolves or fixes issue: #597

AI Tool Disclosure

• My contribution does not include any AI-generated content
• My contribution includes AI-generated content, as disclosed below:
  • AI Tools: Grok Bot (coding agent)
  • LLMs and versions: not exposed by the tool
  • Prompts: Implement the expected outcome from #597 (python runtime as type=platform, isExternal=true, CycloneDX 1.7) in "cyclonedx-py environment" only, following CONTRIBUTING.md; regenerate snapshots; add tests and docs. I reviewed the changes and ran the test suite and linters locally.

Affirmation

• My code follows the CONTRIBUTING.md guidelines

[read-the-docs-community]

Documentation build overview

📚 CycloneDX Python SBOM Tool | 🛠️ Build #35907794 | 📁 Comparing 366e900 against latest (9d0acc7)

  🔍 Preview build  

1 file changed

± usage.html

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 14 complexity · 0 duplication

Metric	Results
Complexity	✅ 14 (≤ 20 complexity)
Duplication	0

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}