feat!: this-builder

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.
+"""

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 ...
+    )

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')
-        )
-    ]
-)

cyclonedx/model/bom.py

@@ -26,6 +26,7 @@
 from sortedcontainers import SortedSet
 
 from .._internal.time import get_now_utc as _get_now_utc
+from ..builder.this import this_component
 from ..exception.model import LicenseExpressionAlongWithOthersException, UnknownComponentDependencyException
 from ..schema.schema import (
     SchemaVersion1Dot0,
@@ -37,7 +38,7 @@
     SchemaVersion1Dot6,
 )
 from ..serialization import LicenseRepositoryHelper, UrnUuidHelper
-from . import ExternalReference, Property, ThisTool
+from . import ExternalReference, Property
 from .bom_ref import BomRef
 from .component import Component
 from .contact import OrganizationalContact, OrganizationalEntity
@@ -90,7 +91,7 @@ def __init__(
                 DeprecationWarning)
 
         if not tools:
-            self.tools.tools.add(ThisTool)
+            self.tools.components.add(this_component())
 
     @property
     @serializable.type_mapping(serializable.helpers.XsdDateTime)

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,6 +64,7 @@ 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"
 

tests/_data/models.py

@@ -38,9 +38,9 @@
     Note,
     NoteText,
     Property,
-    ThisTool,
     XsUri,
 )
+from cyclonedx.builder.this import this_tool, this_component
 from cyclonedx.model.bom import Bom, BomMetaData
 from cyclonedx.model.bom_ref import BomRef
 from cyclonedx.model.component import (
@@ -130,10 +130,14 @@
 BOM_TIMESTAMP = datetime.fromisoformat('2023-01-07 13:44:32.312678+00:00')
 
 
-def _make_bom(**kwargs: Any) -> Bom:
+def _make_bom(
+    clear_tools=True,
+    **kwargs: Any) -> Bom:
     bom = Bom(**kwargs)
     bom.serial_number = BOM_SERIAL_NUMBER
     bom.metadata.timestamp = BOM_TIMESTAMP
+    if clear_tools:
+        bom.metadata.tools = ToolsRepository()
     bom.properties = get_properties_1()
     return bom
 
@@ -1050,9 +1054,10 @@ def get_bom_with_multiple_licenses() -> Bom:
 
 def get_bom_with_tools() -> Bom:
     return _make_bom(
+        clear_tools=False,
         metadata=BomMetaData(
             tools=(
-                ThisTool,
+                this_tool(),
                 Tool(name='test-tool-b'),
                 Tool(vendor='example',
                      name='test-tool-a',
@@ -1068,9 +1073,11 @@ def get_bom_with_tools() -> Bom:
 
 def get_bom_with_tools_with_component_migrate() -> Bom:
     return _make_bom(
+        clear_tools=False,
         metadata=BomMetaData(
             tools=ToolsRepository(
                 components=(
+                    this_component(),
                     Component(name='test-component', bom_ref='test-component'),
                     Component(type=ComponentType.APPLICATION,
                               bom_ref='other-component',
@@ -1088,6 +1095,7 @@ def get_bom_with_tools_with_component_migrate() -> Bom:
 
 def get_bom_with_tools_with_service_migrate() -> Bom:
     return _make_bom(
+        clear_tools=False,
         metadata=BomMetaData(
             tools=ToolsRepository(
                 services=(
@@ -1105,9 +1113,11 @@ def get_bom_with_tools_with_service_migrate() -> Bom:
 
 def get_bom_with_tools_with_component_and_service_migrate() -> Bom:
     return _make_bom(
+        clear_tools=False,
         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 +1147,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 +1167,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',
@@ -1166,8 +1177,10 @@ def get_bom_with_tools_with_component_and_service_and_tools_irreversible_migrate
              external_references=[get_external_reference_1()],
              ),
     ))
-    return _make_bom(metadata=BomMetaData(tools=tools))
+    return _make_bom(clear_tools=False, metadata=BomMetaData(tools=tools))
 
+def get_bom_with_tools_default_migrate() -> Bom:
+    return _make_bom(clear_tools=False)
 
 def get_bom_for_issue_497_urls() -> Bom:
     """regression test for issue #497

tests/_data/snapshots/enum_ComponentScope-1.2.json.bin

@@ -34,14 +34,7 @@
     }
   ],
   "metadata": {
-    "timestamp": "2023-01-07T13:44:32.312678+00:00",
-    "tools": [
-      {
-        "name": "cyclonedx-python-lib",
-        "vendor": "CycloneDX",
-        "version": "TESTING"
-      }
-    ]
+    "timestamp": "2023-01-07T13:44:32.312678+00:00"
   },
   "serialNumber": "urn:uuid:1441d33a-e0fc-45b5-af3b-61ee52a88bac",
   "version": 1,

tests/_data/snapshots/enum_ComponentScope-1.2.xml.bin

@@ -2,13 +2,6 @@
 <bom xmlns="http://cyclonedx.org/schema/bom/1.2" serialNumber="urn:uuid:1441d33a-e0fc-45b5-af3b-61ee52a88bac" version="1">
   <metadata>
     <timestamp>2023-01-07T13:44:32.312678+00:00</timestamp>
-    <tools>
-      <tool>
-        <vendor>CycloneDX</vendor>
-        <name>cyclonedx-python-lib</name>
-        <version>TESTING</version>
-      </tool>
-    </tools>
   </metadata>
   <components>
     <component type="library" bom-ref="scoped-EXCLUDED">

tests/_data/snapshots/enum_ComponentScope-1.3.json.bin

@@ -34,14 +34,7 @@
     }
   ],
   "metadata": {
-    "timestamp": "2023-01-07T13:44:32.312678+00:00",
-    "tools": [
-      {
-        "name": "cyclonedx-python-lib",
-        "vendor": "CycloneDX",
-        "version": "TESTING"
-      }
-    ]
+    "timestamp": "2023-01-07T13:44:32.312678+00:00"
   },
   "serialNumber": "urn:uuid:1441d33a-e0fc-45b5-af3b-61ee52a88bac",
   "version": 1,

tests/_data/snapshots/enum_ComponentScope-1.3.xml.bin

@@ -2,13 +2,6 @@
 <bom xmlns="http://cyclonedx.org/schema/bom/1.3" serialNumber="urn:uuid:1441d33a-e0fc-45b5-af3b-61ee52a88bac" version="1">
   <metadata>
     <timestamp>2023-01-07T13:44:32.312678+00:00</timestamp>
-    <tools>
-      <tool>
-        <vendor>CycloneDX</vendor>
-        <name>cyclonedx-python-lib</name>
-        <version>TESTING</version>
-      </tool>
-    </tools>
   </metadata>
   <components>
     <component type="library" bom-ref="scoped-EXCLUDED">