feat!: v6.0.0

.github/workflows/python.yml

@@ -20,7 +20,7 @@ concurrency:
 env:
   REPORTS_DIR: CI_reports
   PYTHON_VERSION_DEFAULT: "3.11"
-  POETRY_VERSION: "1.4.1"
+  POETRY_VERSION: "1.7.1"
   TESTS_REPORTS_ARTIFACT: tests-reports
 
 jobs:

.github/workflows/release.yml

@@ -39,7 +39,7 @@ concurrency:
 
 env:
   PYTHON_VERSION_DEFAULT: "3.11"
-  POETRY_VERSION: "1.4.1"
+  POETRY_VERSION: "1.7.1"
 
 jobs:
   quicktest:

README.md

@@ -13,10 +13,13 @@
 
 ----
 
-This Python package can render and read valid [CycloneDX][link_website] documents.  
-CycloneDX is a lightweight BOM specification that is easily created, human-readable, and simple to parse.
+OWASP [CycloneDX][link_website] is a full-stack Bill of Materials (BOM) standard
+that provides advanced supply chain capabilities for cyber risk reduction.
 
-**This module is not designed for standalone use.**
+This Python package provides data models, validators and more, 
+to help you create/render/read CycloneDX documents.
+
+**This package is not designed for standalone use. It is a library.**
 
 As of version `3.0.0`, the internal data model was adjusted to allow CycloneDX VEX documents to be produced as per
 [official examples](https://cyclonedx.org/capabilities/bomlink/#linking-external-vex-to-bom-inventory) linking a VEX 
@@ -27,6 +30,8 @@ If you're looking for a CycloneDX tool to run to generate (SBOM) software bill-o
 
 Alternatively, you can use this module yourself in your application to programmatically generate CycloneDX BOMs.
 
+## Documentation
+
 View the documentation [here](https://cyclonedx-python-library.readthedocs.io/).
 
 ## Python Support

cyclonedx/__init__.py

@@ -21,4 +21,4 @@
 # !! version is managed by semantic_release
 # do not use typing here, or else `semantic_release` might have issues finding the variable
 # flake8: noqa
-__version__ = "5.2.0"
+__version__ = "6.0.0-rc.3"

cyclonedx/_internal/__init__.py

@@ -0,0 +1,20 @@
+# 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.
+
+
+"""
+!!! ALL SYMBOLS IN HERE ARE INTERNAL.
+Everything might change without any notice.
+"""

cyclonedx/_internal/compare.py

@@ -0,0 +1,54 @@
+# 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.
+
+
+"""
+!!! ALL SYMBOLS IN HERE ARE INTERNAL.
+Everything might change without any notice.
+"""
+
+
+from itertools import zip_longest
+from typing import Any, Optional, Tuple
+
+
+class ComparableTuple(Tuple[Optional[Any], ...]):
+    """
+    Allows comparison of tuples, allowing for None values.
+    """
+
+    def __lt__(self, other: Any) -> bool:
+        for s, o in zip_longest(self, other):
+            if s == o:
+                continue
+            # the idea is to have any consistent order, not necessarily "natural" order.
+            if s is None:
+                return False
+            if o is None:
+                return True
+            return True if s < o else False
+        return False
+
+    def __gt__(self, other: Any) -> bool:
+        for s, o in zip_longest(self, other):
+            if s == o:
+                continue
+            # the idea is to have any consistent order, not necessarily "natural" order.
+            if s is None:
+                return True
+            if o is None:
+                return False
+            return True if s > o else False
+        return False

cyclonedx/_internal/hash.py

@@ -0,0 +1,41 @@
+# 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.
+
+
+"""
+!!! ALL SYMBOLS IN HERE ARE INTERNAL.
+Everything might change without any notice.
+"""
+
+
+from hashlib import sha1
+
+
+def file_sha1sum(filename: str) -> str:
+    """
+    Generate a SHA1 hash of the provided file.
+
+    Args:
+        filename:
+            Absolute path to file to hash as `str`
+
+    Returns:
+        SHA-1 hash
+    """
+    h = sha1()  # nosec B303, B324
+    with open(filename, 'rb') as f:
+        for byte_block in iter(lambda: f.read(4096), b''):
+            h.update(byte_block)
+    return h.hexdigest()

cyclonedx/_internal/time.py

@@ -0,0 +1,27 @@
+# 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.
+
+
+"""
+!!! ALL SYMBOLS IN HERE ARE INTERNAL.
+Everything might change without any notice.
+"""
+
+
+from datetime import datetime, timezone
+
+
+def get_now_utc() -> datetime:
+    return datetime.now(tz=timezone.utc)

cyclonedx/exception/model.py

@@ -63,7 +63,6 @@ class NoPropertiesProvidedException(CycloneDxModelException):
     """
     Raised when attempting to construct a model class and providing NO values (where all properites are defined as
     Optional, but at least one is required).
-
     """
     pass
 

cyclonedx/exception/serialization.py

@@ -0,0 +1,50 @@
+# 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.
+
+
+"""
+Exceptions relating to specific conditions that occur when (de)serializing/(de)normalizing CycloneDX BOM.
+"""
+
+from . import CycloneDxException
+
+
+class CycloneDxSerializationException(CycloneDxException):
+    """
+    Base exception that covers all exceptions that may be thrown during model serializing/normalizing.
+    """
+    pass
+
+
+class CycloneDxDeserializationException(CycloneDxException):
+    """
+    Base exception that covers all exceptions that may be thrown during model deserializing/denormalizing.
+    """
+    pass
+
+
+class SerializationOfUnsupportedComponentTypeException(CycloneDxSerializationException):
+    """
+    Raised when attempting serializing/normalizing a :py:class:`cyclonedx.model.component.Component`
+    to a :py:class:`cyclonedx.schema.schema.BaseSchemaVersion`
+    which does not support that :py:class:`cyclonedx.model.component.ComponentType`
+    .
+    """
+
+
+class SerializationOfUnexpectedValueException(CycloneDxSerializationException, ValueError):
+    """
+    Raised when attempting serializing/normalizing a type that is not expected there.
+    """