Merge branch 'main' into issue941-test

Author: jkowalleck

.github/workflows/release.yml

@@ -140,7 +140,7 @@ jobs:
           architecture: 'x64'
       - name: Install and configure Poetry
         # Seehttps://github.com/snok/install-poetry
-        uses: snok/install-poetry@76e04a911780d5b312d89783f7b1cd627778900a  # v1.4.1
+        uses: snok/install-poetry@a783c322200f0519c7926aa6faa857c4e23e9263  # v1.4.2
         with:
           version: ${{ env.POETRY_VERSION }}
           virtualenvs-create: true

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 <!-- version list -->
 
+## v11.9.0 (2026-06-08)
+
+### Features
+
+- Add support for license expression details
+  ([#908](https://github.com/CycloneDX/cyclonedx-python-lib/pull/908),
+  [`b502381`](https://github.com/CycloneDX/cyclonedx-python-lib/commit/b50238102553dc215b08796ea914072294f69489))
+
+
 ## v11.8.0 (2026-06-04)
 
 ### Documentation

cyclonedx/__init__.py

@@ -22,4 +22,4 @@
 
 # !! version is managed by semantic_release
 # do not use typing here, or else `semantic_release` might have issues finding the variable
-__version__ = "11.8.0"  # noqa:Q000
+__version__ = "11.9.0"  # noqa:Q000

cyclonedx/model/license.py

@@ -34,6 +34,7 @@
 from .._internal.compare import ComparableTuple as _ComparableTuple
 from ..exception.model import MutuallyExclusivePropertiesException
 from ..exception.serialization import CycloneDxDeserializationException
+from ..schema import SchemaVersion
 from ..schema.schema import SchemaVersion1Dot5, SchemaVersion1Dot6, SchemaVersion1Dot7
 from . import AttachedText, Property, XsUri
 from .bom_ref import BomRef
@@ -278,6 +279,123 @@ def __repr__(self) -> str:
         return f'<License id={self._id!r}, name={self._name!r}>'
 
 
+@serializable.serializable_class(ignore_unknown_during_deserialization=True)
+class LicenseExpressionDetails:
+    """
+    This is our internal representation of the ``licenseExpressionDetailedType`` complex type that specifies the details
+    and attributes related to a software license identifier within a CycloneDX BOM document.
+
+    .. note::
+        Introduced in CycloneDX v1.7
+
+
+    .. note::
+        See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.7/xml/#type_licenseExpressionDetailedType
+    """
+
+    def __init__(
+        self, license_identifier: str, *,
+        bom_ref: Optional[Union[str, BomRef]] = None,
+        text: Optional[AttachedText] = None,
+        url: Optional[XsUri] = None,
+    ) -> None:
+        self._bom_ref = _bom_ref_from_str(bom_ref)
+        self.license_identifier = license_identifier
+        self.text = text
+        self.url = url
+
+    @property
+    @serializable.xml_name('license-identifier')
+    @serializable.xml_string(serializable.XmlStringSerializationType.NORMALIZED_STRING)
+    @serializable.xml_attribute()
+    def license_identifier(self) -> str:
+        """
+        A valid SPDX license identifier. Refer to https://spdx.org/specifications for syntax requirements.
+        This field serves as the primary key, which uniquely identifies each record.
+
+        Example values:
+         - "Apache-2.0",
+         - "GPL-3.0-only WITH Classpath-exception-2.0"
+         - "LicenseRef-my-custom-license"
+
+        Returns:
+            `str`
+        """
+        return self._license_identifier
+
+    @license_identifier.setter
+    def license_identifier(self, license_identifier: str) -> None:
+        self._license_identifier = license_identifier
+
+    @property
+    @serializable.json_name('bom-ref')
+    @serializable.type_mapping(BomRef)
+    @serializable.xml_attribute()
+    @serializable.xml_name('bom-ref')
+    def bom_ref(self) -> BomRef:
+        """
+        An identifier which can be used to reference the license elsewhere in the BOM. Every bom-ref MUST be
+        unique within the BOM.
+        Value SHOULD not start with the BOM-Link intro 'urn:cdx:' to avoid conflicts with BOM-Links.
+
+        Returns:
+            `BomRef`
+        """
+        return self._bom_ref
+
+    @property
+    @serializable.xml_sequence(1)
+    def text(self) -> Optional[AttachedText]:
+        """
+        A way to include the textual content of the license.
+
+        Returns:
+            `AttachedText` else `None`
+        """
+        return self._text
+
+    @text.setter
+    def text(self, text: Optional[AttachedText]) -> None:
+        self._text = text
+
+    @property
+    @serializable.xml_sequence(2)
+    def url(self) -> Optional[XsUri]:
+        """
+        The URL to the license file. If specified, a 'license' externalReference should also be specified for
+        completeness.
+
+        Returns:
+            `XsUri` or `None`
+        """
+        return self._url
+
+    @url.setter
+    def url(self, url: Optional[XsUri]) -> None:
+        self._url = url
+
+    def __comparable_tuple(self) -> _ComparableTuple:
+        return _ComparableTuple((
+            self.bom_ref.value, self.license_identifier, self.url, self.text,
+        ))
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, LicenseExpressionDetails):
+            return self.__comparable_tuple() == other.__comparable_tuple()
+        return False
+
+    def __lt__(self, other: object) -> bool:
+        if isinstance(other, LicenseExpressionDetails):
+            return self.__comparable_tuple() < other.__comparable_tuple()
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash(self.__comparable_tuple())
+
+    def __repr__(self) -> str:
+        return f'<LicenseExpressionDetails bom-ref={self.bom_ref!r}, license_identifier={self.license_identifier}>'
+
+
 @serializable.serializable_class(
     name='expression',
     ignore_unknown_during_deserialization=True
@@ -296,10 +414,12 @@ def __init__(
         self, value: str, *,
         bom_ref: Optional[Union[str, BomRef]] = None,
         acknowledgement: Optional[LicenseAcknowledgement] = None,
+        details: Optional[Iterable[LicenseExpressionDetails]] = None,
     ) -> None:
         self._bom_ref = _bom_ref_from_str(bom_ref)
         self._value = value
         self._acknowledgement = acknowledgement
+        self.details = details or []
 
     @property
     @serializable.view(SchemaVersion1Dot5)
@@ -362,11 +482,30 @@ def acknowledgement(self) -> Optional[LicenseAcknowledgement]:
     def acknowledgement(self, acknowledgement: Optional[LicenseAcknowledgement]) -> None:
         self._acknowledgement = acknowledgement
 
+    @property
+    @serializable.json_name('expressionDetails')
+    @serializable.view(SchemaVersion1Dot7)
+    @serializable.xml_array(serializable.XmlArraySerializationType.FLAT, child_name='details')
+    @serializable.xml_sequence(1)
+    def details(self) -> 'SortedSet[LicenseExpressionDetails]':
+        """
+        Details for parts of the expression.
+
+        Returns:
+            Set of `LicenseExpressionDetails`
+        """
+        return self._details
+
+    @details.setter
+    def details(self, details: Iterable[LicenseExpressionDetails]) -> None:
+        self._details = SortedSet(details)
+
     def __comparable_tuple(self) -> _ComparableTuple:
         return _ComparableTuple((
             self._acknowledgement,
             self._value,
             self._bom_ref.value,
+            _ComparableTuple(self.details),
         ))
 
     def __hash__(self) -> int:
@@ -431,6 +570,38 @@ class LicenseRepository(SortedSet):
 class _LicenseRepositorySerializationHelper(serializable.helpers.BaseHelper):
     """  THIS CLASS IS NON-PUBLIC API  """
 
+    @staticmethod
+    def __supports_expression_details(view: Any) -> bool:
+        try:
+            return view is not None and view().schema_version_enum >= SchemaVersion.V1_7
+        except Exception:  # pragma: no cover
+            return False
+
+    @staticmethod
+    def __xml_normalize_license_expression_detailed(
+        license_expression: LicenseExpression,
+        view: Optional[type[serializable.ViewType]],
+        xmlns: Optional[str]
+    ) -> Element:
+        elem: Element = license_expression.as_xml(  # type:ignore[attr-defined]
+            view_=view, as_string=False, element_name='expression-detailed', xmlns=xmlns)
+        elem.set(f'{{{xmlns}}}expression' if xmlns else 'expression', license_expression.value)
+        elem.text = None
+        return elem
+
+    @staticmethod
+    def __xml_denormalize_license_expression_detailed(
+        li: Element,
+        default_ns: Optional[str]
+    ) -> LicenseExpression:
+        expression_value = li.get('expression')
+        if not expression_value:
+            raise CycloneDxDeserializationException(f'unexpected content: {li!r}')
+        license_expression: LicenseExpression = LicenseExpression.from_xml(  # type:ignore[attr-defined]
+            li, default_ns)
+        license_expression.value = expression_value
+        return license_expression
+
     @classmethod
     def json_normalize(cls, o: LicenseRepository, *,
                        view: Optional[type[serializable.ViewType]],
@@ -482,8 +653,13 @@ def xml_normalize(cls, o: LicenseRepository, *,
             # mixed license expression and license? this is an invalid constellation according to schema!
             # see https://github.com/CycloneDX/specification/pull/205
             # but models need to allow it for backwards compatibility with JSON CDX < 1.5
-            elem.append(expression.as_xml(  # type:ignore[attr-defined]
-                view_=view, as_string=False, element_name='expression', xmlns=xmlns))
+            if expression.details and cls.__supports_expression_details(view):
+                elem.append(cls.__xml_normalize_license_expression_detailed(expression, view, xmlns))
+            else:
+                if expression.details:
+                    warn('LicenseExpression details are not supported in schema versions < 1.7; skipping serialization')
+                elem.append(expression.as_xml(  # type:ignore[attr-defined]
+                    view_=view, as_string=False, element_name='expression', xmlns=xmlns))
         else:
             elem.extend(
                 li.as_xml(  # type:ignore[attr-defined]
@@ -506,6 +682,8 @@ def xml_denormalize(cls, o: Element,
             elif tag == 'expression':
                 repo.add(LicenseExpression.from_xml(  # type:ignore[attr-defined]
                     li, default_ns))
+            elif tag == 'expression-detailed':
+                repo.add(cls.__xml_denormalize_license_expression_detailed(li, default_ns))
             else:
                 raise CycloneDxDeserializationException(f'unexpected: {li!r}')
         return repo

docs/conf.py

@@ -23,7 +23,7 @@
 
 # The full version, including alpha/beta/rc tags
 # !! version is managed by semantic_release
-release = '11.8.0'
+release = '11.9.0'
 
 # -- General configuration ---------------------------------------------------
 

docs/requirements.txt

@@ -1,4 +1,4 @@
-m2r2>=0.3.2
+m2r2>=0.3.4
 sphinx>=8,<9
 sphinx-autoapi>=3,<4
 sphinx-rtd-theme>=3,<4

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "poetry.core.masonry.api"
 [tool.poetry]
 name = "cyclonedx-python-lib"
 # !! version is managed by semantic_release
-version = "11.8.0"
+version = "11.9.0"
 description = "Python library for CycloneDX"
 authors = [
   "Paul Horton <phorton@sonatype.com>",

tests/_data/models.py

@@ -97,7 +97,13 @@
     ImpactAnalysisState,
 )
 from cyclonedx.model.issue import IssueClassification, IssueType, IssueTypeSource
-from cyclonedx.model.license import DisjunctiveLicense, License, LicenseAcknowledgement, LicenseExpression
+from cyclonedx.model.license import (
+    DisjunctiveLicense,
+    License,
+    LicenseAcknowledgement,
+    LicenseExpression,
+    LicenseExpressionDetails,
+)
 from cyclonedx.model.lifecycle import LifecyclePhase, NamedLifecycle, PredefinedLifecycle
 from cyclonedx.model.release_note import ReleaseNotes
 from cyclonedx.model.service import Service
@@ -1061,6 +1067,15 @@ def get_vulnerability_source_owasp() -> VulnerabilitySource:
 
 
 def get_bom_with_licenses() -> Bom:
+    expression_details = [
+        LicenseExpressionDetails(license_identifier='GPL-3.0-or-later',
+                                 url=XsUri('https://www.apache.org/licenses/LICENSE-2.0.txt'),
+                                 text=AttachedText(content='specific GPL-3.0-or-later license text')),
+        LicenseExpressionDetails(license_identifier='GPL-2.0',
+                                 bom_ref='some-bomref-1234',
+                                 text=AttachedText(content='specific GPL-2.0 license text')),
+    ]
+
     return _make_bom(
         metadata=BomMetaData(
             licenses=[DisjunctiveLicense(id='CC-BY-1.0')],
@@ -1090,6 +1105,11 @@ def get_bom_with_licenses() -> Bom:
                           DisjunctiveLicense(name='some other license',
                                              properties=[Property(name='myname', value='proprietary')]),
                       ]),
+            Component(name='c-with-expression-details', type=ComponentType.LIBRARY, bom_ref='C5',
+                      licenses=[LicenseExpression(value='GPL-3.0-or-later OR GPL-2.0',
+                                                  details=expression_details,
+                                                  acknowledgement=LicenseAcknowledgement.DECLARED
+                                                  )]),
         ],
         services=[
             Service(name='s-with-expression', bom_ref='S1',

tests/_data/snapshots/get_bom_with_licenses-1.0.xml.bin

@@ -11,6 +11,11 @@
       <version/>
       <modified>false</modified>
     </component>
+    <component type="library">
+      <name>c-with-expression-details</name>
+      <version/>
+      <modified>false</modified>
+    </component>
     <component type="library">
       <name>c-with-license-properties</name>
       <version/>

tests/_data/snapshots/get_bom_with_licenses-1.1.xml.bin

@@ -18,6 +18,13 @@
         <expression>Apache-2.0 OR MIT</expression>
       </licenses>
     </component>
+    <component type="library" bom-ref="C5">
+      <name>c-with-expression-details</name>
+      <version/>
+      <licenses>
+        <expression>GPL-3.0-or-later OR GPL-2.0</expression>
+      </licenses>
+    </component>
     <component type="library" bom-ref="C4">
       <name>c-with-license-properties</name>
       <version/>