feat: make schema deprecation warnings handle-able

Signed-off-by: Jan Kowalleck <jan.kowalleck@gmail.com>

Author: jkowalleck

cyclonedx/model/bom.py

@@ -30,6 +30,7 @@
 from .._internal.compare import ComparableTuple as _ComparableTuple
 from .._internal.time import get_now_utc as _get_now_utc
 from ..exception.model import LicenseExpressionAlongWithOthersException, UnknownComponentDependencyException
+from ..schema.deprecation import DeprecationWarning1Dot6
 from ..schema.schema import (
     SchemaVersion1Dot0,
     SchemaVersion1Dot1,
@@ -294,7 +295,7 @@ def manufacture(self, manufacture: Optional[OrganizationalEntity]) -> None:
             warn(
                 '`bom.metadata.manufacture` is deprecated from CycloneDX v1.6 onwards. '
                 'Please use `bom.metadata.component.manufacturer` instead.',
-                DeprecationWarning)
+                DeprecationWarning1Dot6)
         self._manufacture = manufacture
 
     @property

cyclonedx/model/component.py

@@ -40,6 +40,7 @@
     SerializationOfUnexpectedValueException,
     SerializationOfUnsupportedComponentTypeException,
 )
+from ..schema.deprecation import DeprecationWarning1Dot3, DeprecationWarning1Dot6
 from ..schema.schema import (
     SchemaVersion1Dot0,
     SchemaVersion1Dot1,
@@ -1186,7 +1187,7 @@ def author(self) -> Optional[str]:
     def author(self, author: Optional[str]) -> None:
         if author is not None:
             warn('`@.author` is deprecated from CycloneDX v1.6 onwards. '
-                 'Please use `@.authors` or `@.manufacturer` instead.', DeprecationWarning)
+                 'Please use `@.authors` or `@.manufacturer` instead.', DeprecationWarning1Dot6)
         self._author = author
 
     @property
@@ -1468,7 +1469,7 @@ def modified(self) -> bool:
     def modified(self, modified: bool) -> None:
         if modified:
             warn('`@.modified` is deprecated from CycloneDX v1.3 onwards. '
-                 'Please use `@.pedigree` instead.', DeprecationWarning)
+                 'Please use `@.pedigree` instead.', DeprecationWarning1Dot3)
         self._modified = modified
 
     @property

cyclonedx/model/tool.py

@@ -28,6 +28,7 @@
 
 from .._internal.compare import ComparableTuple as _ComparableTuple
 from ..schema import SchemaVersion
+from ..schema.deprecation import DeprecationWarning1Dot5
 from ..schema.schema import SchemaVersion1Dot4, SchemaVersion1Dot5, SchemaVersion1Dot6, SchemaVersion1Dot7
 from . import ExternalReference, HashType, _HashTypeRepositorySerializationHelper
 from .component import Component
@@ -242,7 +243,7 @@ def tools(self, tools: Iterable[Tool]) -> None:
         if tools:
             warn('`@.tools` is deprecated from CycloneDX v1.5 onwards. '
                  'Please use `@.components` and `@.services` instead.',
-                 DeprecationWarning)
+                 DeprecationWarning1Dot5)
         self._tools = SortedSet(tools)
 
     def __len__(self) -> int:

cyclonedx/schema/deprecation.py

@@ -0,0 +1,73 @@
+# 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.
+
+from abc import ABC, abstractmethod
+from typing import Literal
+
+from . import SchemaVersion
+
+
+class SchemaDeprecationWarning(DeprecationWarning, ABC):
+    @property
+    @abstractmethod
+    def schema_version_enum(self) -> SchemaVersion:
+        ...  # pragma: no cover
+
+    def get_schema_version(self) -> str:
+        return self.schema_version_enum.to_version()
+
+
+class DeprecationWarning1Dot7(SchemaDeprecationWarning):
+    @property
+    def schema_version_enum(self) -> Literal[SchemaVersion.V1_7]:
+        return SchemaVersion.V1_7
+
+
+class DeprecationWarning1Dot6(SchemaDeprecationWarning):
+    @property
+    def schema_version_enum(self) -> Literal[SchemaVersion.V1_6]:
+        return SchemaVersion.V1_6
+
+
+class DeprecationWarning1Dot5(SchemaDeprecationWarning):
+    @property
+    def schema_version_enum(self) -> Literal[SchemaVersion.V1_5]:
+        return SchemaVersion.V1_5
+
+
+class DeprecationWarning1Dot4(SchemaDeprecationWarning):
+    @property
+    def schema_version_enum(self) -> Literal[SchemaVersion.V1_4]:
+        return SchemaVersion.V1_4
+
+
+class DeprecationWarning1Dot3(SchemaDeprecationWarning):
+    @property
+    def schema_version_enum(self) -> Literal[SchemaVersion.V1_3]:
+        return SchemaVersion.V1_3
+
+
+class DeprecationWarning1Dot2(SchemaDeprecationWarning):
+    @property
+    def schema_version_enum(self) -> Literal[SchemaVersion.V1_2]:
+        return SchemaVersion.V1_2
+
+
+class DeprecationWarning1Dot1(SchemaDeprecationWarning):
+    @property
+    def schema_version_enum(self) -> Literal[SchemaVersion.V1_1]:
+        return SchemaVersion.V1_1

examples/complex_deserialize.py

@@ -16,6 +16,7 @@
 # Copyright (c) OWASP Foundation. All Rights Reserved.
 
 import sys
+import warnings
 from json import loads as json_loads
 from typing import TYPE_CHECKING
 
@@ -24,6 +25,7 @@
 from cyclonedx.exception import MissingOptionalDependencyException
 from cyclonedx.model.bom import Bom
 from cyclonedx.schema import OutputFormat, SchemaVersion
+from cyclonedx.schema.deprecation import SchemaDeprecationWarning
 from cyclonedx.validation import make_schemabased_validator
 from cyclonedx.validation.json import JsonStrictValidator
 
@@ -100,6 +102,7 @@
       "type": "library",
       "group": "acme",
       "name": "some-component",
+      "author": "John 'the mighty' Doe",
       "version": "1.33.7-beta.1",
       "purl": "pkg:generic/acme/some-component@1.33.7-beta.1",
       "licenses": [
@@ -154,8 +157,10 @@
     print('JSON valid')
 except MissingOptionalDependencyException as error:
     print('JSON-validation was skipped due to', error)
-bom_from_json = Bom.from_json(  # type: ignore[attr-defined]
-    json_loads(json_data))
+with warnings.catch_warnings():
+    warnings.filterwarnings("ignore", category=SchemaDeprecationWarning)
+    bom_from_json = Bom.from_json(  # type: ignore[attr-defined]
+        json_loads(json_data))
 print('bom_from_json', repr(bom_from_json))
 
 # endregion JSON
@@ -255,8 +260,10 @@
     print('XML valid')
 except MissingOptionalDependencyException as error:
     print('XML-validation was skipped due to', error)
-bom_from_xml = Bom.from_xml(  # type: ignore[attr-defined]
-    SafeElementTree.fromstring(xml_data))
+with warnings.catch_warnings():
+    warnings.filterwarnings("ignore", category=SchemaDeprecationWarning)
+    bom_from_xml = Bom.from_xml(  # type: ignore[attr-defined]
+        SafeElementTree.fromstring(xml_data))
 print('bom_from_xml', repr(bom_from_xml))
 
 # endregion XML