Merge branch 'main' of https://github.com/saquibsaifee/cyclonedx-python-lib

Author: saquibsaifee

CHANGELOG.md

@@ -2,6 +2,61 @@
 
 
 
+## v8.0.0 (2024-10-14)
+
+### Breaking
+
+* feat!: v8.0.0 (#665)
+
+### BREAKING Changes
+
+* Removed `cyclonedx.mode.ThisTool`, utilize `cyclonedx.builder.this.this_tool()` instead. 
+* Moved `cyclonedx.model.Tool` to `cyclonedx.model.tool.Tool`.
+* Property `cyclonedx.mode.bom.BomMetaData.tools` is of type `cyclonedx.model.tool.ToolRepository` now, was `SortedSet[cyclonedx.model.Tool]`.  
+  The getter will act accordingly; the setter might act in a backwards-compatible way.
+* Property `cyclonedx.mode.vulnerability.Vulnerability.tools` is of type `cyclonedx.model.tool.ToolRepository` now, was `SortedSet[cyclonedx.model.Tool]`.  
+  The getter will act accordingly; the setter might act in a backwards-compatible way.
+* Constructor `cyclonedx.model.license.LicenseExpression()` accepts optional argument `acknowledgement` only as key-word argument, no longer as positional argument.  
+  
+
+### Changes
+
+* Constructor of `cyclonedx.model.bom.BomMetaData` also accepts an instance of `cyclonedx.model.tool.ToolRepository` for argument `tools`.
+* Constructor of `cyclonedx.model.bom.BomMetaData` no longer adds this very library as a tool.  
+  Downstream users SHOULD add it manually, like `my-bom.metadata.tools.components.add(cyclonedx.builder.this.this_component())`. 
+
+### Fixes
+
+* Deserialization of CycloneDX that do not include tools in the metadata are no longer unexpectedly modified/altered.
+
+### Added
+
+Enabled Metadata Tools representation and serialization in accordance with CycloneDX 1.5 
+
+* New class `cyclonedx.model.tool.ToolRepository`.
+* New function `cyclonedx.builder.this.this_component()` -- representation of this very python library as a `Component`.
+* New function `cyclonedx.builder.this.this_tool()` -- representation of this very python library as a `Tool`.
+* New function `cyclonedx.model.tool.Tool.from_component()`.
+
+### Dependencies
+
+* Raised runtime dependency `py-serializable>=1.1.1,<2`, was `>=1.1.0,<2`.
+
+---------
+
+Signed-off-by: Jan Kowalleck <[email protected]>
+Signed-off-by: Joshua Kugler <[email protected]>
+Signed-off-by: semantic-release <[email protected]>
+Co-authored-by: Joshua Kugler <[email protected]>
+Co-authored-by: semantic-release <[email protected]> ([`002f966`](https://github.com/CycloneDX/cyclonedx-python-lib/commit/002f96630ce8fc6f1766ee6cc92a16b35a821c69))
+
+### Documentation
+
+* docs(chaneglog): omit chore/ci/refactor/style/test/build (#703)
+
+Signed-off-by: Jan Kowalleck <[email protected]> ([`a210809`](https://github.com/CycloneDX/cyclonedx-python-lib/commit/a210809efb34c2dc895fc0c6d96a3412a9097625))
+
+
 ## v7.6.2 (2024-10-07)
 
 ### Documentation

CONTRIBUTING.md

@@ -52,6 +52,8 @@ Run all tests in dedicated environments, via:
 poetry run tox run
 ```
 
+See also: [python test snapshots docs](tests/_data/snapshots/README.md)
+
 ## Sign off your commits
 
 Please sign off your commits, to show that you agree to publish your changes under the current terms and licenses of the project

cyclonedx/__init__.py

@@ -22,4 +22,4 @@
 
 # !! version is managed by semantic_release
 # do not use typing here, or else `semantic_release` might have issues finding the variable
-__version__ = "7.6.2"  # noqa:Q000
+__version__ = "8.0.0"  # noqa:Q000

cyclonedx/builder/__init__.py

@@ -0,0 +1,20 @@
+# This file is part of CycloneDX Python Library
+#
+# 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,83 @@
+# This file is part of CycloneDX Python Library
+#
+# 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_component', 'this_tool', ]
+
+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`
+
+
+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=(
+            # let's assume this is not a fork
+            ExternalReference(
+                type=ExternalReferenceType.WEBSITE,
+                url=XsUri('https://github.com/CycloneDX/cyclonedx-python-lib/#readme')
+            ),
+            ExternalReference(
+                type=ExternalReferenceType.DOCUMENTATION,
+                url=XsUri('https://cyclonedx-python-library.readthedocs.io/')
+            ),
+            ExternalReference(
+                type=ExternalReferenceType.VCS,
+                url=XsUri('https://github.com/CycloneDX/cyclonedx-python-lib')
+            ),
+            ExternalReference(
+                type=ExternalReferenceType.BUILD_SYSTEM,
+                url=XsUri('https://github.com/CycloneDX/cyclonedx-python-lib/actions')
+            ),
+            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')
+            ),
+            # we cannot assert where the lib was fetched from, but we can give a hint
+            ExternalReference(
+                type=ExternalReferenceType.DISTRIBUTION,
+                url=XsUri('https://pypi.org/project/cyclonedx-python-lib/')
+            ),
+        ),
+        # to be extended...
+    )
+
+
+def this_tool() -> Tool:
+    """Representation of this very python library as a :class:`Tool`."""
+    return Tool.from_component(this_component())

cyclonedx/model/__init__.py

@@ -34,7 +34,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,
@@ -1129,139 +1128,6 @@ def __repr__(self) -> str:
         return f'<Note id={id(self)}, locale={self.locale}>'
 
 
-@serializable.serializable_class
-class Tool:
-    """
-    This is our internal representation of the `toolType` complex type within the CycloneDX standard.
-
-    Tool(s) are the things used in the creation of the CycloneDX document.
-
-    Tool might be deprecated since CycloneDX 1.5, but it is not deprecated in this library.
-    In fact, this library will try to provide a compatibility layer if needed.
-
-    .. note::
-        See the CycloneDX Schema for toolType: https://cyclonedx.org/docs/1.3/#type_toolType
-    """
-
-    def __init__(
-        self, *,
-        vendor: Optional[str] = None,
-        name: Optional[str] = None,
-        version: Optional[str] = None,
-        hashes: Optional[Iterable[HashType]] = None,
-        external_references: Optional[Iterable[ExternalReference]] = None,
-    ) -> None:
-        self.vendor = vendor
-        self.name = name
-        self.version = version
-        self.hashes = hashes or []  # type:ignore[assignment]
-        self.external_references = external_references or []  # type:ignore[assignment]
-
-    @property
-    @serializable.xml_sequence(1)
-    @serializable.xml_string(serializable.XmlStringSerializationType.NORMALIZED_STRING)
-    def vendor(self) -> Optional[str]:
-        """
-        The name of the vendor who created the tool.
-
-        Returns:
-            `str` if set else `None`
-        """
-        return self._vendor
-
-    @vendor.setter
-    def vendor(self, vendor: Optional[str]) -> None:
-        self._vendor = vendor
-
-    @property
-    @serializable.xml_sequence(2)
-    @serializable.xml_string(serializable.XmlStringSerializationType.NORMALIZED_STRING)
-    def name(self) -> Optional[str]:
-        """
-        The name of the tool.
-
-        Returns:
-             `str` if set else `None`
-        """
-        return self._name
-
-    @name.setter
-    def name(self, name: Optional[str]) -> None:
-        self._name = name
-
-    @property
-    @serializable.xml_sequence(3)
-    @serializable.xml_string(serializable.XmlStringSerializationType.NORMALIZED_STRING)
-    def version(self) -> Optional[str]:
-        """
-        The version of the tool.
-
-        Returns:
-             `str` if set else `None`
-        """
-        return self._version
-
-    @version.setter
-    def version(self, version: Optional[str]) -> None:
-        self._version = version
-
-    @property
-    @serializable.type_mapping(_HashTypeRepositorySerializationHelper)
-    @serializable.xml_sequence(4)
-    def hashes(self) -> 'SortedSet[HashType]':
-        """
-        The hashes of the tool (if applicable).
-
-        Returns:
-            Set of `HashType`
-        """
-        return self._hashes
-
-    @hashes.setter
-    def hashes(self, hashes: Iterable[HashType]) -> None:
-        self._hashes = SortedSet(hashes)
-
-    @property
-    @serializable.view(SchemaVersion1Dot4)
-    @serializable.view(SchemaVersion1Dot5)
-    @serializable.view(SchemaVersion1Dot6)
-    @serializable.xml_array(serializable.XmlArraySerializationType.NESTED, 'reference')
-    @serializable.xml_sequence(5)
-    def external_references(self) -> 'SortedSet[ExternalReference]':
-        """
-        External References provides a way to document systems, sites, and information that may be relevant but which
-        are not included with the BOM.
-
-        Returns:
-            Set of `ExternalReference`
-        """
-        return self._external_references
-
-    @external_references.setter
-    def external_references(self, external_references: Iterable[ExternalReference]) -> None:
-        self._external_references = SortedSet(external_references)
-
-    def __eq__(self, other: object) -> bool:
-        if isinstance(other, Tool):
-            return hash(other) == hash(self)
-        return False
-
-    def __lt__(self, other: Any) -> bool:
-        if isinstance(other, Tool):
-            return _ComparableTuple((
-                self.vendor, self.name, self.version
-            )) < _ComparableTuple((
-                other.vendor, other.name, other.version
-            ))
-        return NotImplemented
-
-    def __hash__(self) -> int:
-        return hash((self.vendor, self.name, self.version, tuple(self.hashes), tuple(self.external_references)))
-
-    def __repr__(self) -> str:
-        return f'<Tool name={self.name}, version={self.version}, vendor={self.vendor}>'
-
-
 @serializable.serializable_class
 class IdentifiableAction:
     """
@@ -1397,43 +1263,3 @@ def __hash__(self) -> int:
 
     def __repr__(self) -> str:
         return f'<Copyright text={self.text}>'
-
-
-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')
-        )
-    ])