feat: prepare "contrib" area

jkowalleck · jkowalleck · commit 28b94a72bead · 2025-11-28T17:43:48.000+01:00
Signed-off-by: Jan Kowalleck &lt;jan.kowalleck@gmail.com&gt;
diff --git a/cyclonedx/contrib/component/builders.py b/cyclonedx/contrib/component/builders.py
@@ -27,7 +27,8 @@
 
 class ComponentBuilder:
 
-    def make_for_file(self, absolute_file_path: str, name: Optional[str]) -> Component:
+    def make_for_file(self, absolute_file_path: str, *,
+                      name: Optional[str]) -> Component:
         """
         Helper method to create a :class:`cyclonedx.model.component.Component`
         that represents the provided local file as a Component.
diff --git a/cyclonedx/contrib/hash/__init__.py b/cyclonedx/contrib/hash/__init__.py
@@ -0,0 +1,18 @@
+# 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.
+
+"""Hash related functionality"""
diff --git a/cyclonedx/contrib/hash/factories.py b/cyclonedx/contrib/hash/factories.py
@@ -0,0 +1,131 @@
+# 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.
+
+"""Hash related factories"""
+
+__all__ = ['HashTypeFactory']
+
+from ...model import HashType, HashAlgorithm
+
+from ...exception.model import UnknownHashTypeException
+
+
+
+_MAP_HASHLIB: dict[str, HashAlgorithm] = {
+    # from hashlib.algorithms_guaranteed
+    'md5': HashAlgorithm.MD5,
+    'sha1': HashAlgorithm.SHA_1,
+    # sha224:
+    'sha256': HashAlgorithm.SHA_256,
+    'sha384': HashAlgorithm.SHA_384,
+    'sha512': HashAlgorithm.SHA_512,
+    # blake2b:
+    # blake2s:
+    # sha3_224:
+    'sha3_256': HashAlgorithm.SHA3_256,
+    'sha3_384': HashAlgorithm.SHA3_384,
+    'sha3_512': HashAlgorithm.SHA3_512,
+    # shake_128:
+    # shake_256:
+}
+
+class HashTypeFactory:
+
+    def from_hashlib_alg(self, hashlib_alg: str, content: str) -> HashType:
+        """
+        Attempts to convert a hashlib-algorithm to our internal model classes.
+
+        Args:
+             hashlib_alg:
+                Hash algorith - like it is used by `hashlib`.
+                Example: `sha256`.
+
+            content:
+                Hash value.
+
+        Raises:
+            `UnknownHashTypeException` if the algorithm of hash cannot be determined.
+
+        Returns:
+            An instance of `HashType`.
+        """
+        alg = _MAP_HASHLIB.get(hashlib_alg.lower())
+        if alg is None:
+            raise UnknownHashTypeException(f'Unable to determine hash alg for {hashlib_alg!r}')
+        return HashType(alg=alg, content=content)
+
+    def from_composite_str(self, composite_hash: str) -> HashType:
+        """
+        Attempts to convert a string which includes both the Hash Algorithm and Hash Value and represent using our
+        internal model classes.
+
+        Args:
+             composite_hash:
+                Composite Hash string of the format `HASH_ALGORITHM`:`HASH_VALUE`.
+                Example: `sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b`.
+
+                Valid case insensitive prefixes are:
+                `md5`, `sha1`, `sha256`, `sha384`, `sha512`, `blake2b256`, `blake2b384`, `blake2b512`,
+                `blake2256`, `blake2384`, `blake2512`, `sha3-256`, `sha3-384`, `sha3-512`,
+                `blake3`.
+
+        Raises:
+            `UnknownHashTypeException` if the type of hash cannot be determined.
+
+        Returns:
+            An instance of `HashType`.
+        """
+        parts = composite_hash.split(':')
+
+        algorithm_prefix = parts[0].lower()
+        if algorithm_prefix == 'md5':
+            return HashType(
+                alg=HashAlgorithm.MD5,
+                content=parts[1].lower()
+            )
+        elif algorithm_prefix[0:4] == 'sha3':
+            return HashType(
+                alg=getattr(HashAlgorithm, f'SHA3_{algorithm_prefix[5:]}'),
+                content=parts[1].lower()
+            )
+        elif algorithm_prefix == 'sha1':
+            return HashType(
+                alg=HashAlgorithm.SHA_1,
+                content=parts[1].lower()
+            )
+        elif algorithm_prefix[0:3] == 'sha':
+            # This is actually SHA2...
+            return HashType(
+                alg=getattr(HashAlgorithm, f'SHA_{algorithm_prefix[3:]}'),
+                content=parts[1].lower()
+            )
+        elif algorithm_prefix[0:7] == 'blake2b':
+            return HashType(
+                alg=getattr(HashAlgorithm, f'BLAKE2B_{algorithm_prefix[7:]}'),
+                content=parts[1].lower()
+            )
+        elif algorithm_prefix[0:6] == 'blake2':
+            return HashType(
+                alg=getattr(HashAlgorithm, f'BLAKE2B_{algorithm_prefix[6:]}'),
+                content=parts[1].lower()
+            )
+        elif algorithm_prefix[0:6] == 'blake3':
+            return HashType(
+                alg=HashAlgorithm.BLAKE3,
+                content=parts[1].lower()
+            )
+        raise UnknownHashTypeException(f'Unable to determine hash type from {composite_hash!r}')
diff --git a/cyclonedx/exception/model.py b/cyclonedx/exception/model.py
@@ -116,7 +116,7 @@ class UnknownHashTypeException(CycloneDxModelException):
     """
     Exception raised when we are unable to determine the type of hash from a composite hash string.
     """
-    pass
+    pass  # TODO research deprecation of this...
 
 
 class LicenseExpressionAlongWithOthersException(CycloneDxModelException):
diff --git a/cyclonedx/model/__init__.py b/cyclonedx/model/__init__.py
@@ -37,8 +37,9 @@
 import py_serializable as serializable
 from sortedcontainers import SortedSet
 
+from contrib.hash.factories import HashTypeFactory
 from .._internal.compare import ComparableTuple as _ComparableTuple
-from ..exception.model import InvalidLocaleTypeException, InvalidUriException, UnknownHashTypeException
+from ..exception.model import InvalidLocaleTypeException, InvalidUriException
 from ..exception.serialization import CycloneDxDeserializationException, SerializationOfUnexpectedValueException
 from ..schema.schema import (
     SchemaVersion1Dot0,
@@ -366,25 +367,6 @@ def xml_denormalize(cls, o: 'XmlElement', *,
         ]
 
 
-_MAP_HASHLIB: dict[str, HashAlgorithm] = {
-    # from hashlib.algorithms_guaranteed
-    'md5': HashAlgorithm.MD5,
-    'sha1': HashAlgorithm.SHA_1,
-    # sha224:
-    'sha256': HashAlgorithm.SHA_256,
-    'sha384': HashAlgorithm.SHA_384,
-    'sha512': HashAlgorithm.SHA_512,
-    # blake2b:
-    # blake2s:
-    # sha3_224:
-    'sha3_256': HashAlgorithm.SHA3_256,
-    'sha3_384': HashAlgorithm.SHA3_384,
-    'sha3_512': HashAlgorithm.SHA3_512,
-    # shake_128:
-    # shake_256:
-}
-
-
 @serializable.serializable_class
 class HashType:
     """
@@ -395,91 +377,27 @@ class HashType:
     """
 
     @staticmethod
-    def from_hashlib_alg(hashlib_alg: str, content: str) -> 'HashType':  # TODO: move to contrib
-        """
-        Attempts to convert a hashlib-algorithm to our internal model classes.
-
-        Args:
-             hashlib_alg:
-                Hash algorith - like it is used by `hashlib`.
-                Example: `sha256`.
+    def from_hashlib_alg(hashlib_alg: str, content: str) -> 'HashType':
+        """Deprecated — Alias of :func:`cyclonedx.contrib.hash.factories.HashTypeFactory.from_hashlib_alge`.
 
-            content:
-                Hash value.
-
-        Raises:
-            `UnknownHashTypeException` if the algorithm of hash cannot be determined.
+        Attempts to convert a hashlib-algorithm to our internal model classes.
 
-        Returns:
-            An instance of `HashType`.
+        .. deprecated:: next
+            Use ``cyclonedx.contrib.hash.factories.HashTypeFactory.from_hashlib_alg()`` instead.
         """
-        alg = _MAP_HASHLIB.get(hashlib_alg.lower())
-        if alg is None:
-            raise UnknownHashTypeException(f'Unable to determine hash alg for {hashlib_alg!r}')
-        return HashType(alg=alg, content=content)
+        return HashTypeFactory().from_hashlib_alg(hashlib_alg, content)
 
     @staticmethod
-    def from_composite_str(composite_hash: str) -> 'HashType':  # TODO: move to contrib
-        """
+    def from_composite_str(composite_hash: str) -> 'HashType':
+        """Deprecated — Alias of :func:`cyclonedx.contrib.hash.factories.HashTypeFactory.from_composite_str`.
+
         Attempts to convert a string which includes both the Hash Algorithm and Hash Value and represent using our
         internal model classes.
 
-        Args:
-             composite_hash:
-                Composite Hash string of the format `HASH_ALGORITHM`:`HASH_VALUE`.
-                Example: `sha256:806143ae5bfb6a3c6e736a764057db0e6a0e05e338b5630894a5f779cabb4f9b`.
-
-                Valid case insensitive prefixes are:
-                `md5`, `sha1`, `sha256`, `sha384`, `sha512`, `blake2b256`, `blake2b384`, `blake2b512`,
-                `blake2256`, `blake2384`, `blake2512`, `sha3-256`, `sha3-384`, `sha3-512`,
-                `blake3`.
-
-        Raises:
-            `UnknownHashTypeException` if the type of hash cannot be determined.
-
-        Returns:
-            An instance of `HashType`.
+        .. deprecated:: next
+            Use ``cyclonedx.contrib.hash.factories.HashTypeFactory.from_composite_str()`` instead.
         """
-        parts = composite_hash.split(':')
-
-        algorithm_prefix = parts[0].lower()
-        if algorithm_prefix == 'md5':
-            return HashType(
-                alg=HashAlgorithm.MD5,
-                content=parts[1].lower()
-            )
-        elif algorithm_prefix[0:4] == 'sha3':
-            return HashType(
-                alg=getattr(HashAlgorithm, f'SHA3_{algorithm_prefix[5:]}'),
-                content=parts[1].lower()
-            )
-        elif algorithm_prefix == 'sha1':
-            return HashType(
-                alg=HashAlgorithm.SHA_1,
-                content=parts[1].lower()
-            )
-        elif algorithm_prefix[0:3] == 'sha':
-            # This is actually SHA2...
-            return HashType(
-                alg=getattr(HashAlgorithm, f'SHA_{algorithm_prefix[3:]}'),
-                content=parts[1].lower()
-            )
-        elif algorithm_prefix[0:7] == 'blake2b':
-            return HashType(
-                alg=getattr(HashAlgorithm, f'BLAKE2B_{algorithm_prefix[7:]}'),
-                content=parts[1].lower()
-            )
-        elif algorithm_prefix[0:6] == 'blake2':
-            return HashType(
-                alg=getattr(HashAlgorithm, f'BLAKE2B_{algorithm_prefix[6:]}'),
-                content=parts[1].lower()
-            )
-        elif algorithm_prefix[0:6] == 'blake3':
-            return HashType(
-                alg=HashAlgorithm.BLAKE3,
-                content=parts[1].lower()
-            )
-        raise UnknownHashTypeException(f'Unable to determine hash type from {composite_hash!r}')
+        return HashTypeFactory().from_composite_str(composite_hash)
 
     def __init__(
         self, *,
diff --git a/cyclonedx/model/component.py b/cyclonedx/model/component.py
@@ -960,19 +960,10 @@ def for_file(absolute_file_path: str, path_for_bom: Optional[str]) -> 'Component
 
         Helper method to create a Component that represents the provided local file as a Component.
 
-        Args:
-            absolute_file_path:
-                Absolute path to the file you wish to represent
-            path_for_bom:
-                Optionally, if supplied this is the path that will be used to identify the file in the BOM
-
-        Returns:
-            `Component` representing the supplied file
-
         .. deprecated:: next
             Use ``cyclonedx.contrib.component.builders.ComponentBuilder.make_for_file()`` instead.
         """
-        component = ComponentBuilder().make_for_file(absolute_file_path, path_for_bom)
+        component = ComponentBuilder().make_for_file(absolute_file_path, name=path_for_bom)
         sha1_hash = next(h.content for h in component.hashes if h.alg is HashAlgorithm.SHA_1)
         component.version=f'0.0.0-{sha1_hash[0:12]}'
         component.purl=PackageURL(  # DEPRECATED: a file has no PURL!
