feat!: this-builder (#649)

reworked `ThisTool` for #635 --------- Signed-off-by: Jan Kowalleck <jan.kowalleck@gmail.com>
CycloneDX · Sep 16, 2024 · cf5d2c7 · cf5d2c7
1 parent 0172564
commit cf5d2c7
Show file tree

Hide file tree

Showing 42 changed files with 884 additions and 76 deletions.
diff --git a/cyclonedx/builder/__init__.py b/cyclonedx/builder/__init__.py
@@ -0,0 +1,18 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) OWASP Foundation. All Rights Reserved.
+
+"""
+Builders used in this library.
+"""
diff --git a/cyclonedx/builder/this.py b/cyclonedx/builder/this.py
@@ -0,0 +1,97 @@
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) OWASP Foundation. All Rights Reserved.
+
+"""Representation of this very python library."""
+
+__all__ = ['this_tool', 'this_component']
+
+from typing import Iterable
+
+from .. import __version__ as __ThisVersion  # noqa: N812
+from ..model import ExternalReference, ExternalReferenceType, XsUri
+from ..model.component import Component, ComponentType
+from ..model.license import DisjunctiveLicense, LicenseAcknowledgement
+from ..model.tool import Tool
+
+# !!! keep this file in sync with `pyproject.toml`
+
+# !!!
+# things in here are built on demand, rather than using prepared frozen constants.
+# this is currently a draft and may change in the future.
+# !!!
+
+
+def __ext_refs() -> Iterable[ExternalReference]:
+    return (
+        ExternalReference(
+            type=ExternalReferenceType.BUILD_SYSTEM,
+            url=XsUri('https://github.com/CycloneDX/cyclonedx-python-lib/actions')
+        ),
+        ExternalReference(
+            type=ExternalReferenceType.DISTRIBUTION,
+            url=XsUri('https://pypi.org/project/cyclonedx-python-lib/')
+        ),
+        ExternalReference(
+            type=ExternalReferenceType.DOCUMENTATION,
+            url=XsUri('https://cyclonedx-python-library.readthedocs.io/')
+        ),
+        ExternalReference(
+            type=ExternalReferenceType.ISSUE_TRACKER,
+            url=XsUri('https://github.com/CycloneDX/cyclonedx-python-lib/issues')
+        ),
+        ExternalReference(
+            type=ExternalReferenceType.LICENSE,
+            url=XsUri('https://github.com/CycloneDX/cyclonedx-python-lib/blob/main/LICENSE')
+        ),
+        ExternalReference(
+            type=ExternalReferenceType.RELEASE_NOTES,
+            url=XsUri('https://github.com/CycloneDX/cyclonedx-python-lib/blob/main/CHANGELOG.md')
+        ),
+        ExternalReference(
+            type=ExternalReferenceType.VCS,
+            url=XsUri('https://github.com/CycloneDX/cyclonedx-python-lib')
+        ),
+        ExternalReference(
+            type=ExternalReferenceType.WEBSITE,
+            url=XsUri('https://github.com/CycloneDX/cyclonedx-python-lib/#readme')
+        ),
+    )
+
+
+def this_tool() -> Tool:
+    """Representation of this very python library as a :class:`Tool`."""
+
+    return Tool(
+        vendor='CycloneDX',
+        name='cyclonedx-python-lib',
+        version=__ThisVersion or 'UNKNOWN',
+        external_references=__ext_refs(),
+    )
+
+
+def this_component() -> Component:
+    """Representation of this very python library as a :class:`Component`."""
+
+    return Component(
+        type=ComponentType.LIBRARY,
+        group='CycloneDX',
+        name='cyclonedx-python-lib',
+        version=__ThisVersion or 'UNKNOWN',
+        description='Python library for CycloneDX',
+        licenses=(DisjunctiveLicense(id='Apache-2.0',
+                                     acknowledgement=LicenseAcknowledgement.DECLARED),),
+        external_references=__ext_refs(),
+        # to be expanded ...
+    )
diff --git a/cyclonedx/model/__init__.py b/cyclonedx/model/__init__.py
@@ -32,7 +32,6 @@
 import serializable
 from sortedcontainers import SortedSet
 
-from .. import __version__ as __ThisToolVersion  # noqa: N812
 from .._internal.compare import ComparableTuple as _ComparableTuple
 from ..exception.model import (
     InvalidLocaleTypeException,
@@ -1262,47 +1261,3 @@ def __hash__(self) -> int:
 
     def __repr__(self) -> str:
         return f'<Copyright text={self.text}>'
-
-
-# Importing here to avoid a circular import
-from .tool import Tool  # pylint: disable=wrong-import-position # noqa: E402
-
-ThisTool = Tool(
-    vendor='CycloneDX',
-    name='cyclonedx-python-lib',
-    version=__ThisToolVersion or 'UNKNOWN',
-    external_references=[
-        ExternalReference(
-            type=ExternalReferenceType.BUILD_SYSTEM,
-            url=XsUri('https://github.com/CycloneDX/cyclonedx-python-lib/actions')
-        ),
-        ExternalReference(
-            type=ExternalReferenceType.DISTRIBUTION,
-            url=XsUri('https://pypi.org/project/cyclonedx-python-lib/')
-        ),
-        ExternalReference(
-            type=ExternalReferenceType.DOCUMENTATION,
-            url=XsUri('https://cyclonedx-python-library.readthedocs.io/')
-        ),
-        ExternalReference(
-            type=ExternalReferenceType.ISSUE_TRACKER,
-            url=XsUri('https://github.com/CycloneDX/cyclonedx-python-lib/issues')
-        ),
-        ExternalReference(
-            type=ExternalReferenceType.LICENSE,
-            url=XsUri('https://github.com/CycloneDX/cyclonedx-python-lib/blob/main/LICENSE')
-        ),
-        ExternalReference(
-            type=ExternalReferenceType.RELEASE_NOTES,
-            url=XsUri('https://github.com/CycloneDX/cyclonedx-python-lib/blob/main/CHANGELOG.md')
-        ),
-        ExternalReference(
-            type=ExternalReferenceType.VCS,
-            url=XsUri('https://github.com/CycloneDX/cyclonedx-python-lib')
-        ),
-        ExternalReference(
-            type=ExternalReferenceType.WEBSITE,
-            url=XsUri('https://github.com/CycloneDX/cyclonedx-python-lib/#readme')
-        )
-    ]
-)
diff --git a/pyproject.toml b/pyproject.toml
@@ -3,6 +3,7 @@ requires = ["poetry-core>=1.0.0"]
 build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
+# keep in sync with `cyclonedx/builder/this.py`
 name = "cyclonedx-python-lib"
 # !! version is managed by semantic_release
 version = "7.6.0"
@@ -63,13 +64,14 @@ keywords = [
 ]
 
 [tool.poetry.urls]
+# keep in sync with `cyclonedx/builder/this.py`
 "Bug Tracker" = "https://github.com/CycloneDX/cyclonedx-python-lib/issues"
 "Funding" = "https://owasp.org/donate/?reponame=www-project-cyclonedx&title=OWASP+CycloneDX"
 
 [tool.poetry.dependencies]
 python = "^3.8"
 packageurl-python = ">=0.11, <2"
-py-serializable =  "^1.1.0"
+py-serializable =  "^1.1.1"
 sortedcontainers = "^2.4.0"
 license-expression = "^30"
 jsonschema = { version = "^4.18", extras=['format'], optional=true }

diff --git a/tests/_data/models.py b/tests/_data/models.py
@@ -26,6 +26,7 @@
 # See https://github.com/package-url/packageurl-python/issues/65
 from packageurl import PackageURL
 
+from cyclonedx.builder.this import this_component, this_tool
 from cyclonedx.model import (
     AttachedText,
     Copyright,
@@ -38,7 +39,6 @@
     Note,
     NoteText,
     Property,
-    ThisTool,
     XsUri,
 )
 from cyclonedx.model.bom import Bom, BomMetaData
@@ -1052,7 +1052,7 @@ def get_bom_with_tools() -> Bom:
     return _make_bom(
         metadata=BomMetaData(
             tools=(
-                ThisTool,
+                this_tool(),
                 Tool(name='test-tool-b'),
                 Tool(vendor='example',
                      name='test-tool-a',
@@ -1071,6 +1071,7 @@ def get_bom_with_tools_with_component_migrate() -> Bom:
         metadata=BomMetaData(
             tools=ToolsRepository(
                 components=(
+                    this_component(),
                     Component(name='test-component', bom_ref='test-component'),
                     Component(type=ComponentType.APPLICATION,
                               bom_ref='other-component',
@@ -1108,6 +1109,7 @@ def get_bom_with_tools_with_component_and_service_migrate() -> Bom:
         metadata=BomMetaData(
             tools=ToolsRepository(
                 components=(
+                    this_component(),
                     Component(name='test-component', bom_ref='test-component'),
                     Component(type=ComponentType.APPLICATION,
                               bom_ref='other-component',
@@ -1137,6 +1139,7 @@ def get_bom_with_tools_with_component_and_service_and_tools_irreversible_migrate
     tserv = tools.services
     ttools = tools.tools
     tcomp.update((
+        this_component(),
         Component(name='test-component', bom_ref='test-component'),
         Component(type=ComponentType.APPLICATION,
                   bom_ref='other-component',
@@ -1156,7 +1159,7 @@ def get_bom_with_tools_with_component_and_service_and_tools_irreversible_migrate
                 ),
     ))
     ttools.update((
-        ThisTool,
+        this_tool(),
         Tool(name='test-tool-b'),
         Tool(vendor='example',
              name='test-tool-a',

diff --git a/...get_bom_with_tools_with_component_and_service_and_tools_irreversible_migrate-1.2.json.bin b/...get_bom_with_tools_with_component_and_service_and_tools_irreversible_migrate-1.2.json.bin
@@ -31,6 +31,11 @@
         "name": "other-component",
         "vendor": "acme"
       },
+      {
+        "name": "cyclonedx-python-lib",
+        "vendor": "CycloneDX",
+        "version": "TESTING"
+      },
       {
         "name": "test-component"
       },

diff --git a/.../get_bom_with_tools_with_component_and_service_and_tools_irreversible_migrate-1.2.xml.bin b/.../get_bom_with_tools_with_component_and_service_and_tools_irreversible_migrate-1.2.xml.bin
@@ -26,6 +26,11 @@
           <hash alg="SHA-256">49b420bd8d8182542a76d4422e0c7890dcc88a3d8ddad04da06366d8c40ac8ca</hash>
         </hashes>
       </tool>
+      <tool>
+        <vendor>CycloneDX</vendor>
+        <name>cyclonedx-python-lib</name>
+        <version>TESTING</version>
+      </tool>
       <tool>
         <name>test-component</name>
       </tool>

diff --git a/...get_bom_with_tools_with_component_and_service_and_tools_irreversible_migrate-1.3.json.bin b/...get_bom_with_tools_with_component_and_service_and_tools_irreversible_migrate-1.3.json.bin
@@ -31,6 +31,11 @@
         "name": "other-component",
         "vendor": "acme"
       },
+      {
+        "name": "cyclonedx-python-lib",
+        "vendor": "CycloneDX",
+        "version": "TESTING"
+      },
       {
         "name": "test-component"
       },

diff --git a/.../get_bom_with_tools_with_component_and_service_and_tools_irreversible_migrate-1.3.xml.bin b/.../get_bom_with_tools_with_component_and_service_and_tools_irreversible_migrate-1.3.xml.bin
@@ -26,6 +26,11 @@
           <hash alg="SHA-256">49b420bd8d8182542a76d4422e0c7890dcc88a3d8ddad04da06366d8c40ac8ca</hash>
         </hashes>
       </tool>
+      <tool>
+        <vendor>CycloneDX</vendor>
+        <name>cyclonedx-python-lib</name>
+        <version>TESTING</version>
+      </tool>
       <tool>
         <name>test-component</name>
       </tool>

diff --git a/...get_bom_with_tools_with_component_and_service_and_tools_irreversible_migrate-1.4.json.bin b/...get_bom_with_tools_with_component_and_service_and_tools_irreversible_migrate-1.4.json.bin
@@ -91,6 +91,45 @@
         "name": "other-component",
         "vendor": "acme"
       },
+      {
+        "externalReferences": [
+          {
+            "type": "build-system",
+            "url": "https://github.com/CycloneDX/cyclonedx-python-lib/actions"
+          },
+          {
+            "type": "distribution",
+            "url": "https://pypi.org/project/cyclonedx-python-lib/"
+          },
+          {
+            "type": "documentation",
+            "url": "https://cyclonedx-python-library.readthedocs.io/"
+          },
+          {
+            "type": "issue-tracker",
+            "url": "https://github.com/CycloneDX/cyclonedx-python-lib/issues"
+          },
+          {
+            "type": "license",
+            "url": "https://github.com/CycloneDX/cyclonedx-python-lib/blob/main/LICENSE"
+          },
+          {
+            "type": "release-notes",
+            "url": "https://github.com/CycloneDX/cyclonedx-python-lib/blob/main/CHANGELOG.md"
+          },
+          {
+            "type": "vcs",
+            "url": "https://github.com/CycloneDX/cyclonedx-python-lib"
+          },
+          {
+            "type": "website",
+            "url": "https://github.com/CycloneDX/cyclonedx-python-lib/#readme"
+          }
+        ],
+        "name": "cyclonedx-python-lib",
+        "vendor": "CycloneDX",
+        "version": "TESTING"
+      },
       {
         "name": "test-component"
       },

diff --git a/.../get_bom_with_tools_with_component_and_service_and_tools_irreversible_migrate-1.4.xml.bin b/.../get_bom_with_tools_with_component_and_service_and_tools_irreversible_migrate-1.4.xml.bin
@@ -70,6 +70,37 @@
           </reference>
         </externalReferences>
       </tool>
+      <tool>
+        <vendor>CycloneDX</vendor>
+        <name>cyclonedx-python-lib</name>
+        <version>TESTING</version>
+        <externalReferences>
+          <reference type="build-system">
+            <url>https://github.com/CycloneDX/cyclonedx-python-lib/actions</url>
+          </reference>
+          <reference type="distribution">
+            <url>https://pypi.org/project/cyclonedx-python-lib/</url>
+          </reference>
+          <reference type="documentation">
+            <url>https://cyclonedx-python-library.readthedocs.io/</url>
+          </reference>
+          <reference type="issue-tracker">
+            <url>https://github.com/CycloneDX/cyclonedx-python-lib/issues</url>
+          </reference>
+          <reference type="license">
+            <url>https://github.com/CycloneDX/cyclonedx-python-lib/blob/main/LICENSE</url>
+          </reference>
+          <reference type="release-notes">
+            <url>https://github.com/CycloneDX/cyclonedx-python-lib/blob/main/CHANGELOG.md</url>
+          </reference>
+          <reference type="vcs">
+            <url>https://github.com/CycloneDX/cyclonedx-python-lib</url>
+          </reference>
+          <reference type="website">
+            <url>https://github.com/CycloneDX/cyclonedx-python-lib/#readme</url>
+          </reference>
+        </externalReferences>
+      </tool>
       <tool>
         <name>test-component</name>
       </tool>