feat: prepare "contrib" area

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

Author: jkowalleck

cyclonedx/_internal/hash.py cyclonedx/contrib/component/__init__.pycyclonedx/_internal/hash.py renamed to cyclonedx/contrib/component/__init__.py

@@ -15,29 +15,4 @@
 # 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()
+"""Component related functionality"""

cyclonedx/contrib/component/builders.py

@@ -0,0 +1,72 @@
+# 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.
+
+"""Component related builders"""
+
+
+from hashlib import sha1
+from typing import Optional
+from os.path import exists
+
+from ...model import HashType, HashAlgorithm
+from ...model.component import Component, ComponentType
+
+class ComponentBuilder:
+
+    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.
+
+        Args:
+            absolute_file_path:
+                Absolute path to the file you wish to represent
+            name:
+                Optionally, if supplied this is the name that will be used for the component.
+                Defaults to arg ``absolute_file_path``.
+
+        Returns:
+            `Component` representing the supplied file
+        """
+        if not exists(absolute_file_path):
+            raise FileExistsError(f'Supplied file path {absolute_file_path!r} does not exist')
+
+        return Component(
+            type=ComponentType.FILE,
+            name=name or absolute_file_path,
+            hashes=[
+                HashType(alg=HashAlgorithm.SHA_1, content=self._file_sha1sum(absolute_file_path))
+            ]
+        )
+
+    @staticmethod
+    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/model/__init__.py

@@ -395,7 +395,7 @@ class HashType:
     """
 
     @staticmethod
-    def from_hashlib_alg(hashlib_alg: str, content: str) -> 'HashType':
+    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.
 
@@ -419,7 +419,7 @@ def from_hashlib_alg(hashlib_alg: str, content: str) -> 'HashType':
         return HashType(alg=alg, content=content)
 
     @staticmethod
-    def from_composite_str(composite_hash: str) -> 'HashType':
+    def from_composite_str(composite_hash: str) -> 'HashType':  # TODO: move to contrib
         """
         Attempts to convert a string which includes both the Hash Algorithm and Hash Value and represent using our
         internal model classes.

cyclonedx/model/component.py

@@ -18,18 +18,18 @@
 import re
 from collections.abc import Iterable
 from enum import Enum
-from os.path import exists
 from typing import Any, Optional, Union
 from warnings import warn
 
 # See https://github.com/package-url/packageurl-python/issues/65
 import py_serializable as serializable
 from packageurl import PackageURL
 from sortedcontainers import SortedSet
+from typing_extensions import deprecated
 
+from contrib.component.builders import ComponentBuilder
 from .._internal.bom_ref import bom_ref_from_str as _bom_ref_from_str
 from .._internal.compare import ComparablePackageURL as _ComparablePackageURL, ComparableTuple as _ComparableTuple
-from .._internal.hash import file_sha1sum as _file_sha1sum
 from ..exception.model import InvalidOmniBorIdException, InvalidSwhidException
 from ..exception.serialization import (
     CycloneDxDeserializationException,
@@ -50,12 +50,11 @@
 from . import (
     AttachedText,
     ExternalReference,
-    HashAlgorithm,
     HashType,
     IdentifiableAction,
     Property,
     XsUri,
-    _HashTypeRepositorySerializationHelper,
+    _HashTypeRepositorySerializationHelper, HashAlgorithm,
 )
 from .bom_ref import BomRef
 from .component_evidence import ComponentEvidence, _ComponentEvidenceSerializationHelper
@@ -955,8 +954,10 @@ class Component(Dependable):
     """
 
     @staticmethod
+    @deprecated('Deprecated - use cyclonedx.contrib.component.builders.ComponentBuilder.make_for_file instead')
     def for_file(absolute_file_path: str, path_for_bom: Optional[str]) -> 'Component':
-        """
+        """Deprecated — Wrapper of :func:`cyclonedx.contrib.component.builders.ComponentBuilder.make_for_file`.
+
         Helper method to create a Component that represents the provided local file as a Component.
 
         Args:
@@ -967,22 +968,18 @@ def for_file(absolute_file_path: str, path_for_bom: Optional[str]) -> 'Component
 
         Returns:
             `Component` representing the supplied file
+
+        .. deprecated:: next
+            Use ``cyclonedx.contrib.component.builders.ComponentBuilder.make_for_file()`` instead.
         """
-        if not exists(absolute_file_path):
-            raise FileExistsError(f'Supplied file path {absolute_file_path!r} does not exist')
-
-        sha1_hash: str = _file_sha1sum(absolute_file_path)
-        return Component(
-            name=path_for_bom if path_for_bom else absolute_file_path,
-            version=f'0.0.0-{sha1_hash[0:12]}',
-            hashes=[
-                HashType(alg=HashAlgorithm.SHA_1, content=sha1_hash)
-            ],
-            type=ComponentType.FILE, purl=PackageURL(
-                type='generic', name=path_for_bom if path_for_bom else absolute_file_path,
-                version=f'0.0.0-{sha1_hash[0:12]}'
-            )
+        component = ComponentBuilder().make_for_file(absolute_file_path, 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!
+            type='generic', name=path_for_bom if path_for_bom else absolute_file_path,
+            version=f'0.0.0-{sha1_hash[0:12]}'
         )
+        return component
 
     def __init__(
         self, *,