feat!: v6.0.0 (#492)

### Breaking Changes

* Removed symbols that were already marked as deprecated (via [#493])
* Removed symbols in `parser.*` ([#489] via [#495])
* Removed `output.LATEST_SUPPORTED_SCHEMA_VERSION` ([#491] via [#494])
* Serialization of unsupported enum values might downgrade/migrate/omit them  ([#490] via [#496])  
  Handling might raise warnings if a data loss occurred due to omitting.  
  The result is a guaranteed valid XML/JSON, since no (enum-)invalid values are rendered.
* Serialization of any `model.component.Component` with unsupported `type` raises `exception.serialization.SerializationOfUnsupportedComponentTypeException` ([#490] via [#496])
* Object `model.bom_ref.BomRef`'s property `value` defaults to `Null`, was arbitrary `UUID` ([#504] via [#505])  
  This change does not affect serialization. All `bom-ref`s are guaranteed to have unique values on rendering.
* Removed helpers from public API ([#503] via [#506])

### Added

* Basic support for CycloneDX 1.5 ([#404] via [#488])
  * No data models were enhanced nor added, yet.  
    Pull requests to add functionality are welcome.
  * Existing enumerable got new cases, to reflect features of CycloneDX 1.5 ([#404] via [#488])
  * Outputters were enabled to render CycloneDX 1.5 ([#404] via [#488])

### Tests

* Created (regression/unit/integration/functional) tests for CycloneDX 1.5 ([#404] via [#488])
* Created (regression/functional) tests for Enums' handling and completeness ([#490] via [#496])

### Misc

* Bumped dependency `py-serializable@^0.16`, was `@^0.15` (via [#496])


----

### API Changes — the details for migration

* Added new sub-package `exception.serialization` (via [#496])
* Removed class `models.ComparableTuple` ([#503] via [#506])
* Enum `model.ExternalReferenceType` got new cases, to reflect features for CycloneDX 1.5 ([#404] via [#488])
* Removed function `models.get_now_utc` ([#503] via [#506])
* Removed function `models.sha1sum` ([#503] via [#506])
* Enum `model.component.ComponentType` got new cases, to reflect features for CycloneDX 1.5 ([#404] via [#488])
* Removed `model.component.Component.__init__()`'s deprecated optional kwarg `namespace` (via [#493])  
  Use kwarg `group` instead.
* Removed `model.component.Component.__init__()`'s deprecated optional kwarg `license_str` (via [#493])  
  Use kwarg `licenses` instead.
* Removed deprecated method `model.component.Component.get_namespace()` (via [#493])
* Removed class `models.dependency.DependencyDependencies` ([#503] via [#506])
* Removed `model.vulnerability.Vulnerability.__init__()`'s deprecated optional kwarg `source_name` (via [#493])  
  Use kwarg `source` instead.
* Removed `model.vulnerability.Vulnerability.__init__()`'s deprecated optional kwarg `source_url` (via [#493])  
  Use kwarg `source` instead.
* Removed `model.vulnerability.Vulnerability.__init__()`'s deprecated optional kwarg `recommendations` (via [#493])  
  Use kwarg `recommendation` instead.
* Removed `model.vulnerability.VulnerabilityRating.__init__()`'s deprecated optional kwarg `score_base` (via [#493])  
  Use kwarg `score` instead.
* Enum `model.vulnerability.VulnerabilityScoreSource` got new cases, to reflect features for CycloneDX 1.5 ([#404] via [#488])
* Removed `output.LATEST_SUPPORTED_SCHEMA_VERSION` ([#491] via [#494])
* Removed deprecated function `output.get_instance()` (via [#493])  
  Use function `output.make_outputter()` instead.
* Added new class `output.json.JsonV1Dot5`, to reflect CycloneDX 1.5 ([#404] via [#488])
* Added new item to dict `output.json.BY_SCHEMA_VERSION`, to reflect CycloneDX 1.5 ([#404] via [#488])
* Added new class `output.xml.XmlV1Dot5`, to reflect CycloneDX 1.5 ([#404] via [#488])
* Added new item to dict `output.xml.BY_SCHEMA_VERSION`, to reflect CycloneDX 1.5 ([#404] via [#488])
* Removed class `parser.ParserWarning` ([#489] via [#495])
* Removed class `parser.BaseParser` ([#489] via [#495])
* Enum `schema.SchemaVersion` got new case `V1_5`, to reflect CycloneDX 1.5 ([#404] via [#488])


[#404]: #404
[#488]: #488
[#489]: #489
[#490]: #490
[#491]: #491
[#493]: #493
[#494]: #494
[#495]: #495
[#496]: #496
[#503]: #503
[#504]: #504
[#505]: #505
[#506]: #506

---------

Signed-off-by: Johannes Feichtner <[email protected]>
Signed-off-by: Jan Kowalleck <[email protected]>
Signed-off-by: semantic-release <semantic-release>
Co-authored-by: Johannes Feichtner <[email protected]>
Co-authored-by: semantic-release <semantic-release>

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