|
| 1 | +# This file is part of CycloneDX Python Library |
| 2 | +# |
| 3 | +# Licensed under the Apache License, Version 2.0 (the "License"); |
| 4 | +# you may not use this file except in compliance with the License. |
| 5 | +# You may obtain a copy of the License at |
| 6 | +# |
| 7 | +# http://www.apache.org/licenses/LICENSE-2.0 |
| 8 | +# |
| 9 | +# Unless required by applicable law or agreed to in writing, software |
| 10 | +# distributed under the License is distributed on an "AS IS" BASIS, |
| 11 | +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 12 | +# See the License for the specific language governing permissions and |
| 13 | +# limitations under the License. |
| 14 | +# |
| 15 | +# SPDX-License-Identifier: Apache-2.0 |
| 16 | +# Copyright (c) OWASP Foundation. All Rights Reserved. |
| 17 | + |
| 18 | + |
| 19 | +""" |
| 20 | +CycloneDX Schema Deprecation Warnings |
| 21 | +===================================== |
| 22 | +
|
| 23 | +This module provides warning classes for deprecated features in CycloneDX schemas. |
| 24 | +Each warning class corresponds to a specific schema version, enabling downstream |
| 25 | +code to catch, filter, or otherwise handle schema-specific deprecation warnings. |
| 26 | +
|
| 27 | +Intended Usage |
| 28 | +-------------- |
| 29 | +
|
| 30 | +Downstream consumers can manage warnings using Python's ``warnings`` module. |
| 31 | +Common scenarios include: |
| 32 | +
|
| 33 | +- Filtering by schema version |
| 34 | +- Suppressing warnings in tests or batch processing |
| 35 | +- Logging or reporting deprecation warnings without raising exceptions |
| 36 | +
|
| 37 | +Example |
| 38 | +------- |
| 39 | +
|
| 40 | +.. code-block:: python |
| 41 | +
|
| 42 | + import warnings |
| 43 | + from cyclonedx.schema.deprecation import ( |
| 44 | + BaseSchemaDeprecationWarning, |
| 45 | + SchemaDeprecationWarning1Dot7, |
| 46 | + ) |
| 47 | +
|
| 48 | + # Suppress all CycloneDX schema deprecation warnings |
| 49 | + warnings.filterwarnings("ignore", category=BaseSchemaDeprecationWarning) |
| 50 | +
|
| 51 | + # Suppress only warnings specific to schema version 1.7 |
| 52 | + warnings.filterwarnings("ignore", category=SchemaDeprecationWarning1Dot7) |
| 53 | +
|
| 54 | +Notes |
| 55 | +----- |
| 56 | +
|
| 57 | +- All deprecation warnings inherit from :class:`BaseSchemaDeprecationWarning`. |
| 58 | +- The ``SCHEMA_VERSION`` class variable indicates the CycloneDX schema version |
| 59 | + where the feature became deprecated. |
| 60 | +- These warning classes are designed for downstream **filtering and logging**, |
| 61 | + not for raising exceptions. |
| 62 | +""" |
| 63 | + |
| 64 | + |
| 65 | +from abc import ABC |
| 66 | +from typing import ClassVar, Literal, Optional |
| 67 | +from warnings import warn |
| 68 | + |
| 69 | +from . import SchemaVersion |
| 70 | + |
| 71 | +__all__ = [ |
| 72 | + 'BaseSchemaDeprecationWarning', |
| 73 | + 'SchemaDeprecationWarning1Dot1', |
| 74 | + 'SchemaDeprecationWarning1Dot2', |
| 75 | + 'SchemaDeprecationWarning1Dot3', |
| 76 | + 'SchemaDeprecationWarning1Dot4', |
| 77 | + 'SchemaDeprecationWarning1Dot5', |
| 78 | + 'SchemaDeprecationWarning1Dot6', |
| 79 | + 'SchemaDeprecationWarning1Dot7', |
| 80 | +] |
| 81 | + |
| 82 | + |
| 83 | +class BaseSchemaDeprecationWarning(DeprecationWarning, ABC): |
| 84 | + """Base class for warnings about deprecated schema features.""" |
| 85 | + |
| 86 | + SCHEMA_VERSION: ClassVar[SchemaVersion] |
| 87 | + |
| 88 | + @classmethod |
| 89 | + def _warn(cls, deprecated: str, instead: Optional[str] = None, *, stacklevel: int = 1) -> None: |
| 90 | + """Internal API. Not part of the public interface.""" |
| 91 | + msg = f'`{deprecated}` is deprecated from CycloneDX v{cls.SCHEMA_VERSION.to_version()} onwards.' |
| 92 | + if instead: |
| 93 | + msg += f' Please use `{instead}` instead.' |
| 94 | + warn(msg, category=cls, stacklevel=stacklevel + 1) |
| 95 | + |
| 96 | + |
| 97 | +class SchemaDeprecationWarning1Dot7(BaseSchemaDeprecationWarning): |
| 98 | + """Class for warnings about deprecated schema features in CycloneDX 1.7""" |
| 99 | + SCHEMA_VERSION: ClassVar[Literal[SchemaVersion.V1_7]] = SchemaVersion.V1_7 |
| 100 | + |
| 101 | + |
| 102 | +class SchemaDeprecationWarning1Dot6(BaseSchemaDeprecationWarning): |
| 103 | + """Class for warnings about deprecated schema features in CycloneDX 1.6""" |
| 104 | + SCHEMA_VERSION: ClassVar[Literal[SchemaVersion.V1_6]] = SchemaVersion.V1_6 |
| 105 | + |
| 106 | + |
| 107 | +class SchemaDeprecationWarning1Dot5(BaseSchemaDeprecationWarning): |
| 108 | + """Class for warnings about deprecated schema features in CycloneDX 1.5""" |
| 109 | + SCHEMA_VERSION: ClassVar[Literal[SchemaVersion.V1_5]] = SchemaVersion.V1_5 |
| 110 | + |
| 111 | + |
| 112 | +class SchemaDeprecationWarning1Dot4(BaseSchemaDeprecationWarning): |
| 113 | + """Class for warnings about deprecated schema features in CycloneDX 1.4""" |
| 114 | + SCHEMA_VERSION: ClassVar[Literal[SchemaVersion.V1_4]] = SchemaVersion.V1_4 |
| 115 | + |
| 116 | + |
| 117 | +class SchemaDeprecationWarning1Dot3(BaseSchemaDeprecationWarning): |
| 118 | + """Class for warnings about deprecated schema features in CycloneDX 1.3""" |
| 119 | + SCHEMA_VERSION: ClassVar[Literal[SchemaVersion.V1_3]] = SchemaVersion.V1_3 |
| 120 | + |
| 121 | + |
| 122 | +class SchemaDeprecationWarning1Dot2(BaseSchemaDeprecationWarning): |
| 123 | + """Class for warnings about deprecated schema features in CycloneDX 1.2""" |
| 124 | + SCHEMA_VERSION: ClassVar[Literal[SchemaVersion.V1_2]] = SchemaVersion.V1_2 |
| 125 | + |
| 126 | + |
| 127 | +class SchemaDeprecationWarning1Dot1(BaseSchemaDeprecationWarning): |
| 128 | + """Class for warnings about deprecated schema features in CycloneDX 1.1""" |
| 129 | + SCHEMA_VERSION: ClassVar[Literal[SchemaVersion.V1_1]] = SchemaVersion.V1_1 |
0 commit comments