cyclonedx.model.license
=======================

.. py:module:: cyclonedx.model.license

.. autoapi-nested-parse::

   License related things



Attributes
----------

.. autoapisummary::

   cyclonedx.model.license.LicenseExpressionAcknowledgement
   cyclonedx.model.license.License


Classes
-------

.. autoapisummary::

   cyclonedx.model.license.LicenseAcknowledgement
   cyclonedx.model.license.DisjunctiveLicense
   cyclonedx.model.license.LicenseExpressionDetails
   cyclonedx.model.license.LicenseExpression
   cyclonedx.model.license.LicenseRepository


Module Contents
---------------

.. py:class:: LicenseAcknowledgement

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   This is our internal representation of the `type_licenseAcknowledgementEnumerationType` ENUM type
   within the CycloneDX standard.

   .. note::
       Introduced in CycloneDX v1.6

   .. note::
       See the CycloneDX Schema for hashType:
       https://cyclonedx.org/docs/1.7/xml/#type_licenseAcknowledgementEnumerationType


   .. py:attribute:: CONCLUDED
      :value: 'concluded'



   .. py:attribute:: DECLARED
      :value: 'declared'



.. py:data:: LicenseExpressionAcknowledgement

   Deprecated — Alias for :class:`LicenseAcknowledgement`

   .. deprecated:: next Import `LicenseAcknowledgement` instead.
       The exported original symbol itself is NOT deprecated - only this import path.


.. py:class:: DisjunctiveLicense(*, bom_ref: Optional[Union[str, cyclonedx.model.bom_ref.BomRef]] = None, id: Optional[str] = None, name: Optional[str] = None, text: Optional[cyclonedx.model.AttachedText] = None, url: Optional[cyclonedx.model.XsUri] = None, acknowledgement: Optional[LicenseAcknowledgement] = None, properties: Optional[collections.abc.Iterable[cyclonedx.model.Property]] = None)

   This is our internal representation of `licenseType` complex type that can be used in multiple places within
   a CycloneDX BOM document.

   .. note::
       See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.7/xml/#type_licenseType


   .. py:property:: bom_ref
      :type: cyclonedx.model.bom_ref.BomRef


      An optional identifier which can be used to reference the component elsewhere in the BOM. Every bom-ref MUST be
      unique within the BOM.

      Returns:
          `BomRef`



   .. py:property:: id
      :type: Optional[str]


      A SPDX license ID.

      .. note::
        See the list of expected values:
        https://cyclonedx.org/docs/1.7/json/#components_items_licenses_items_license_id

      Returns:
          `str` or `None`



   .. py:property:: name
      :type: Optional[str]


      If SPDX does not define the license used, this field may be used to provide the license name.

      Returns:
          `str` or `None`



   .. py:property:: text
      :type: Optional[cyclonedx.model.AttachedText]


      Specifies the optional full text of the attachment

      Returns:
          `AttachedText` else `None`



   .. py:property:: url
      :type: Optional[cyclonedx.model.XsUri]


      The URL to the attachment file. If the attachment is a license or BOM, an externalReference should also be
      specified for completeness.

      Returns:
          `XsUri` or `None`



   .. py:property:: properties
      :type: SortedSet[Property]


      Provides the ability to document properties in a key/value store. This provides flexibility to include data not
      officially supported in the standard without having to use additional namespaces or create extensions.

      Return:
          Set of `Property`



   .. py:property:: acknowledgement
      :type: Optional[LicenseAcknowledgement]


      Declared licenses and concluded licenses represent two different stages in the licensing process within
      software development.

      Declared licenses refer to the initial intention of the software authors regarding the
      licensing terms under which their code is released. On the other hand, concluded licenses are the result of a
      comprehensive analysis of the project's codebase to identify and confirm the actual licenses of the components
      used, which may differ from the initially declared licenses. While declared licenses provide an upfront
      indication of the licensing intentions, concluded licenses offer a more thorough understanding of the actual
      licensing within a project, facilitating proper compliance and risk management. Observed licenses are defined
      in evidence.licenses. Observed licenses form the evidence necessary to substantiate a concluded license.

      Returns:
          `LicenseAcknowledgement` or `None`



.. py:class:: LicenseExpressionDetails(license_identifier: str, *, bom_ref: Optional[Union[str, cyclonedx.model.bom_ref.BomRef]] = None, text: Optional[cyclonedx.model.AttachedText] = None, url: Optional[cyclonedx.model.XsUri] = None)

   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


   .. py:property:: license_identifier
      :type: 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`



   .. py:property:: text
      :type: Optional[cyclonedx.model.AttachedText]


      A way to include the textual content of the license.

      Returns:
          `AttachedText` else `None`



   .. py:property:: url
      :type: Optional[cyclonedx.model.XsUri]


      The URL to the license file. If specified, a 'license' externalReference should also be specified for
      completeness.

      Returns:
          `XsUri` or `None`



   .. py:property:: bom_ref
      :type: cyclonedx.model.bom_ref.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`



.. py:class:: LicenseExpression(value: str, *, bom_ref: Optional[Union[str, cyclonedx.model.bom_ref.BomRef]] = None, acknowledgement: Optional[LicenseAcknowledgement] = None, details: Optional[collections.abc.Iterable[LicenseExpressionDetails]] = None)

   This is our internal representation of `licenseType`'s  expression type that can be used in multiple places within
   a CycloneDX BOM document.

   .. note::
       See the CycloneDX Schema definition:
       https://cyclonedx.org/docs/1.7/json/#components_items_licenses_items_expression


   .. py:property:: details
      :type: SortedSet[LicenseExpressionDetails]


      Details for parts of the expression.

      Returns:
          Set of `LicenseExpressionDetails`



   .. py:property:: bom_ref
      :type: cyclonedx.model.bom_ref.BomRef


      An optional identifier which can be used to reference the component elsewhere in the BOM. Every bom-ref MUST be
      unique within the BOM.

      Returns:
          `BomRef`



   .. py:property:: value
      :type: str


      Value of this LicenseExpression.

      Returns:
           `str`



   .. py:property:: acknowledgement
      :type: Optional[LicenseAcknowledgement]


      Declared licenses and concluded licenses represent two different stages in the licensing process within
      software development.

      Declared licenses refer to the initial intention of the software authors regarding the
      licensing terms under which their code is released. On the other hand, concluded licenses are the result of a
      comprehensive analysis of the project's codebase to identify and confirm the actual licenses of the components
      used, which may differ from the initially declared licenses. While declared licenses provide an upfront
      indication of the licensing intentions, concluded licenses offer a more thorough understanding of the actual
      licensing within a project, facilitating proper compliance and risk management. Observed licenses are defined
      in evidence.licenses. Observed licenses form the evidence necessary to substantiate a concluded license.

      Returns:
          `LicenseAcknowledgement` or `None`



.. py:data:: License

   TypeAlias for a union of supported license models.

   - :class:`LicenseExpression`
   - :class:`DisjunctiveLicense`


.. py:class:: LicenseRepository(iterable=None, key=None)

   Bases: :py:obj:`sortedcontainers.SortedSet`\ [\ :py:obj:`License`\ ]


   Collection of :class:`License`.

   This is a `set`, not a `list`.  Order MUST NOT matter here.
   If you wanted a certain order, then you should also express whether the items are concat by `AND` or `OR`.
   If you wanted to do so, you should use :class:`LicenseExpression`.

   As a model, this MUST accept multiple :class:`LicenseExpression` along with
   multiple :class:`DisjunctiveLicense`, as this was an accepted in CycloneDX JSON before v1.5.
   So for modeling purposes, this is supported.
   Denormalizers/deserializers will be thankful.
   The normalization/serialization process SHOULD take care of these facts and do what is needed.


   .. py:attribute:: isdisjoint

      Return True if two sets have a null intersection.



   .. py:attribute:: issubset


   .. py:attribute:: issuperset


   .. py:attribute:: bisect_left


   .. py:attribute:: bisect


   .. py:attribute:: bisect_right


   .. py:attribute:: index

      S.index(value, [start, [stop]]) -> integer -- return first index of
      value.  Raises ValueError if the value is not present.

      Supporting start and stop arguments is optional, but
      recommended.



   .. py:attribute:: irange


   .. py:attribute:: islice


   .. py:property:: key

      Function used to extract comparison key from values.

      Sorted set compares values directly when the key function is none.




   .. py:method:: add(value)

      Add `value` to sorted set.

      Runtime complexity: `O(log(n))` -- approximate.

      >>> ss = SortedSet()
      >>> ss.add(3)
      >>> ss.add(1)
      >>> ss.add(2)
      >>> ss
      SortedSet([1, 2, 3])

      :param value: value to add to sorted set




   .. py:method:: clear()

      Remove all values from sorted set.

      Runtime complexity: `O(n)`




   .. py:method:: copy()

      Return a shallow copy of the sorted set.

      Runtime complexity: `O(n)`

      :return: new sorted set




   .. py:method:: count(value)

      Return number of occurrences of `value` in the sorted set.

      Runtime complexity: `O(1)`

      >>> ss = SortedSet([1, 2, 3, 4, 5])
      >>> ss.count(3)
      1

      :param value: value to count in sorted set
      :return: count




   .. py:method:: discard(value)

      Remove `value` from sorted set if it is a member.

      If `value` is not a member, do nothing.

      Runtime complexity: `O(log(n))` -- approximate.

      >>> ss = SortedSet([1, 2, 3, 4, 5])
      >>> ss.discard(5)
      >>> ss.discard(0)
      >>> ss == set([1, 2, 3, 4])
      True

      :param value: `value` to discard from sorted set




   .. py:method:: pop(index=-1)

      Remove and return value at `index` in sorted set.

      Raise :exc:`IndexError` if the sorted set is empty or index is out of
      range.

      Negative indices are supported.

      Runtime complexity: `O(log(n))` -- approximate.

      >>> ss = SortedSet('abcde')
      >>> ss.pop()
      'e'
      >>> ss.pop(2)
      'c'
      >>> ss
      SortedSet(['a', 'b', 'd'])

      :param int index: index of value (default -1)
      :return: value
      :raises IndexError: if index is out of range




   .. py:method:: remove(value)

      Remove `value` from sorted set; `value` must be a member.

      If `value` is not a member, raise :exc:`KeyError`.

      Runtime complexity: `O(log(n))` -- approximate.

      >>> ss = SortedSet([1, 2, 3, 4, 5])
      >>> ss.remove(5)
      >>> ss == set([1, 2, 3, 4])
      True
      >>> ss.remove(0)
      Traceback (most recent call last):
        ...
      KeyError: 0

      :param value: `value` to remove from sorted set
      :raises KeyError: if `value` is not in sorted set




   .. py:method:: difference(*iterables)

      Return the difference of two or more sets as a new sorted set.

      The `difference` method also corresponds to operator ``-``.

      ``ss.__sub__(iterable)`` <==> ``ss - iterable``

      The difference is all values that are in this sorted set but not the
      other `iterables`.

      >>> ss = SortedSet([1, 2, 3, 4, 5])
      >>> ss.difference([4, 5, 6, 7])
      SortedSet([1, 2, 3])

      :param iterables: iterable arguments
      :return: new sorted set




   .. py:method:: difference_update(*iterables)

      Remove all values of `iterables` from this sorted set.

      The `difference_update` method also corresponds to operator ``-=``.

      ``ss.__isub__(iterable)`` <==> ``ss -= iterable``

      >>> ss = SortedSet([1, 2, 3, 4, 5])
      >>> _ = ss.difference_update([4, 5, 6, 7])
      >>> ss
      SortedSet([1, 2, 3])

      :param iterables: iterable arguments
      :return: itself




   .. py:method:: intersection(*iterables)

      Return the intersection of two or more sets as a new sorted set.

      The `intersection` method also corresponds to operator ``&``.

      ``ss.__and__(iterable)`` <==> ``ss & iterable``

      The intersection is all values that are in this sorted set and each of
      the other `iterables`.

      >>> ss = SortedSet([1, 2, 3, 4, 5])
      >>> ss.intersection([4, 5, 6, 7])
      SortedSet([4, 5])

      :param iterables: iterable arguments
      :return: new sorted set




   .. py:method:: intersection_update(*iterables)

      Update the sorted set with the intersection of `iterables`.

      The `intersection_update` method also corresponds to operator ``&=``.

      ``ss.__iand__(iterable)`` <==> ``ss &= iterable``

      Keep only values found in itself and all `iterables`.

      >>> ss = SortedSet([1, 2, 3, 4, 5])
      >>> _ = ss.intersection_update([4, 5, 6, 7])
      >>> ss
      SortedSet([4, 5])

      :param iterables: iterable arguments
      :return: itself




   .. py:method:: symmetric_difference(other)

      Return the symmetric difference with `other` as a new sorted set.

      The `symmetric_difference` method also corresponds to operator ``^``.

      ``ss.__xor__(other)`` <==> ``ss ^ other``

      The symmetric difference is all values tha are in exactly one of the
      sets.

      >>> ss = SortedSet([1, 2, 3, 4, 5])
      >>> ss.symmetric_difference([4, 5, 6, 7])
      SortedSet([1, 2, 3, 6, 7])

      :param other: `other` iterable
      :return: new sorted set




   .. py:method:: symmetric_difference_update(other)

      Update the sorted set with the symmetric difference with `other`.

      The `symmetric_difference_update` method also corresponds to operator
      ``^=``.

      ``ss.__ixor__(other)`` <==> ``ss ^= other``

      Keep only values found in exactly one of itself and `other`.

      >>> ss = SortedSet([1, 2, 3, 4, 5])
      >>> _ = ss.symmetric_difference_update([4, 5, 6, 7])
      >>> ss
      SortedSet([1, 2, 3, 6, 7])

      :param other: `other` iterable
      :return: itself




   .. py:method:: union(*iterables)

      Return new sorted set with values from itself and all `iterables`.

      The `union` method also corresponds to operator ``|``.

      ``ss.__or__(iterable)`` <==> ``ss | iterable``

      >>> ss = SortedSet([1, 2, 3, 4, 5])
      >>> ss.union([4, 5, 6, 7])
      SortedSet([1, 2, 3, 4, 5, 6, 7])

      :param iterables: iterable arguments
      :return: new sorted set




   .. py:method:: update(*iterables)

      Update the sorted set adding values from all `iterables`.

      The `update` method also corresponds to operator ``|=``.

      ``ss.__ior__(iterable)`` <==> ``ss |= iterable``

      >>> ss = SortedSet([1, 2, 3, 4, 5])
      >>> _ = ss.update([4, 5, 6, 7])
      >>> ss
      SortedSet([1, 2, 3, 4, 5, 6, 7])

      :param iterables: iterable arguments
      :return: itself




