cyclonedx.model.component
=========================

.. py:module:: cyclonedx.model.component


Classes
-------

.. autoapisummary::

   cyclonedx.model.component.Commit
   cyclonedx.model.component.ComponentScope
   cyclonedx.model.component.ComponentType
   cyclonedx.model.component.Diff
   cyclonedx.model.component.PatchClassification
   cyclonedx.model.component.Patch
   cyclonedx.model.component.Pedigree
   cyclonedx.model.component.Swid
   cyclonedx.model.component.OmniborId
   cyclonedx.model.component.Swhid
   cyclonedx.model.component.Component


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

.. py:class:: Commit(*, uid: Optional[str] = None, url: Optional[cyclonedx.model.XsUri] = None, author: Optional[cyclonedx.model.IdentifiableAction] = None, committer: Optional[cyclonedx.model.IdentifiableAction] = None, message: Optional[str] = None)

   Our internal representation of the `commitType` complex type.

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


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


      A unique identifier of the commit. This may be version control specific. For example, Subversion uses revision
      numbers whereas git uses commit hashes.

      Returns:
          `str` if set else `None`



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


      The URL to the commit. This URL will typically point to a commit in a version control system.

      Returns:
           `XsUri` if set else `None`



   .. py:property:: author
      :type: Optional[cyclonedx.model.IdentifiableAction]


      The author who created the changes in the commit.

      Returns:
          `IdentifiableAction` if set else `None`



   .. py:property:: committer
      :type: Optional[cyclonedx.model.IdentifiableAction]


      The person who committed or pushed the commit

      Returns:
          `IdentifiableAction` if set else `None`



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


      The text description of the contents of the commit.

      Returns:
          `str` if set else `None`



.. py:class:: ComponentScope

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


   Enum object that defines the permissable 'scopes' for a Component according to the CycloneDX schema.

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


   .. py:attribute:: REQUIRED
      :value: 'required'



   .. py:attribute:: OPTIONAL
      :value: 'optional'



   .. py:attribute:: EXCLUDED
      :value: 'excluded'



.. py:class:: ComponentType

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


   Enum object that defines the permissible 'types' for a Component according to the CycloneDX schema.

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


   .. py:attribute:: APPLICATION
      :value: 'application'



   .. py:attribute:: CONTAINER
      :value: 'container'



   .. py:attribute:: CRYPTOGRAPHIC_ASSET
      :value: 'cryptographic-asset'



   .. py:attribute:: DATA
      :value: 'data'



   .. py:attribute:: DEVICE
      :value: 'device'



   .. py:attribute:: DEVICE_DRIVER
      :value: 'device-driver'



   .. py:attribute:: FILE
      :value: 'file'



   .. py:attribute:: FIRMWARE
      :value: 'firmware'



   .. py:attribute:: FRAMEWORK
      :value: 'framework'



   .. py:attribute:: LIBRARY
      :value: 'library'



   .. py:attribute:: MACHINE_LEARNING_MODEL
      :value: 'machine-learning-model'



   .. py:attribute:: OPERATING_SYSTEM
      :value: 'operating-system'



   .. py:attribute:: PLATFORM
      :value: 'platform'



.. py:class:: Diff(*, text: Optional[cyclonedx.model.AttachedText] = None, url: Optional[cyclonedx.model.XsUri] = None)

   Our internal representation of the `diffType` complex type.

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


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


      Specifies the optional text of the diff.

      Returns:
          `AttachedText` if set else `None`



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


      Specifies the URL to the diff.

      Returns:
          `XsUri` if set else `None`



.. py:class:: PatchClassification

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


   Enum object that defines the permissible `patchClassification`s.

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


   .. py:attribute:: BACKPORT
      :value: 'backport'



   .. py:attribute:: CHERRY_PICK
      :value: 'cherry-pick'



   .. py:attribute:: MONKEY
      :value: 'monkey'



   .. py:attribute:: UNOFFICIAL
      :value: 'unofficial'



.. py:class:: Patch(*, type: PatchClassification, diff: Optional[Diff] = None, resolves: Optional[collections.abc.Iterable[cyclonedx.model.issue.IssueType]] = None)

   Our internal representation of the `patchType` complex type.

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


   .. py:property:: type
      :type: PatchClassification


      Specifies the purpose for the patch including the resolution of defects, security issues, or new behavior or
      functionality.

      Returns:
          `PatchClassification`



   .. py:property:: diff
      :type: Optional[Diff]


      The patch file (or diff) that show changes.

      .. note::
          Refer to https://en.wikipedia.org/wiki/Diff.

      Returns:
          `Diff` if set else `None`



   .. py:property:: resolves
      :type: SortedSet[IssueType]


      Optional list of issues resolved by this patch.

      Returns:
          Set of `IssueType`



.. py:class:: Pedigree(*, ancestors: Optional[collections.abc.Iterable[Component]] = None, descendants: Optional[collections.abc.Iterable[Component]] = None, variants: Optional[collections.abc.Iterable[Component]] = None, commits: Optional[collections.abc.Iterable[Commit]] = None, patches: Optional[collections.abc.Iterable[Patch]] = None, notes: Optional[str] = None)

   Our internal representation of the `pedigreeType` complex type.

   Component pedigree is a way to document complex supply chain scenarios where components are created, distributed,
   modified, redistributed, combined with other components, etc. Pedigree supports viewing this complex chain from the
   beginning, the end, or anywhere in the middle. It also provides a way to document variants where the exact relation
   may not be known.

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


   .. py:property:: ancestors
      :type: SortedSet['Component']


      Describes zero or more components in which a component is derived from. This is commonly used to describe forks
      from existing projects where the forked version contains a ancestor node containing the original component it
      was forked from.

      For example, Component A is the original component. Component B is the component being used and documented in
      the BOM. However, Component B contains a pedigree node with a single ancestor documenting Component A - the
      original component from which Component B is derived from.

      Returns:
          Set of `Component`



   .. py:property:: descendants
      :type: SortedSet['Component']


      Descendants are the exact opposite of ancestors. This provides a way to document all forks (and their forks) of
      an original or root component.

      Returns:
          Set of `Component`



   .. py:property:: variants
      :type: SortedSet['Component']


      Variants describe relations where the relationship between the components are not known. For example, if
      Component A contains nearly identical code to Component B. They are both related, but it is unclear if one is
      derived from the other, or if they share a common ancestor.

      Returns:
          Set of `Component`



   .. py:property:: commits
      :type: SortedSet[Commit]


      A list of zero or more commits which provide a trail describing how the component deviates from an ancestor,
      descendant, or variant.

      Returns:
          Set of `Commit`



   .. py:property:: patches
      :type: SortedSet[Patch]


      A list of zero or more patches describing how the component deviates from an ancestor, descendant, or variant.
      Patches may be complimentary to commits or may be used in place of commits.

      Returns:
          Set of `Patch`



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


      Notes, observations, and other non-structured commentary describing the components pedigree.

      Returns:
          `str` if set else `None`



.. py:class:: Swid(*, tag_id: str, name: str, version: Optional[str] = None, tag_version: Optional[int] = None, patch: Optional[bool] = None, text: Optional[cyclonedx.model.AttachedText] = None, url: Optional[cyclonedx.model.XsUri] = None)

   Our internal representation of the `swidType` complex type.

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


   .. py:property:: tag_id
      :type: str


      Maps to the tagId of a SoftwareIdentity.

      Returns:
          `str`



   .. py:property:: name
      :type: str


      Maps to the name of a SoftwareIdentity.

      Returns:
           `str`



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


      Maps to the version of a SoftwareIdentity.

      Returns:
           `str` if set else `None`.



   .. py:property:: tag_version
      :type: Optional[int]


      Maps to the tagVersion of a SoftwareIdentity.

      Returns:
          `int` if set else `None`



   .. py:property:: patch
      :type: Optional[bool]


      Maps to the patch of a SoftwareIdentity.

      Returns:
           `bool` if set else `None`



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


      Specifies the full content of the SWID tag.

      Returns:
          `AttachedText` if set else `None`



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


      The URL to the SWID file.

      Returns:
          `XsUri` if set else `None`



.. py:class:: OmniborId(id: str)

   Bases: :py:obj:`py_serializable.helpers.BaseHelper`


   Helper class that allows us to perform validation on data strings that must conform to
   https://www.iana.org/assignments/uri-schemes/prov/gitoid.



   .. py:property:: id
      :type: str



   .. py:method:: serialize(o: Any) -> str
      :classmethod:


      general purpose serializer



   .. py:method:: deserialize(o: Any) -> OmniborId
      :classmethod:


      general purpose deserializer



   .. py:method:: json_normalize(o: Any, *, view: Optional[Type[py_serializable.ViewType]], prop_info: py_serializable.ObjectMetadataLibrary.SerializableProperty, ctx: Type[Any], **kwargs: Any) -> Optional[Any]
      :classmethod:


      json specific normalizer



   .. py:method:: json_serialize(o: Any) -> Union[str, Any]
      :classmethod:


      json specific serializer



   .. py:method:: json_denormalize(o: Any, *, prop_info: py_serializable.ObjectMetadataLibrary.SerializableProperty, ctx: Type[Any], **kwargs: Any) -> Any
      :classmethod:


      json specific denormalizer

      :param tCls: the class that was desired to denormalize to
      :param pCls: tha prent class - as context



   .. py:method:: json_deserialize(o: Any) -> Any
      :classmethod:


      json specific deserializer



   .. py:method:: xml_normalize(o: Any, *, element_name: str, view: Optional[Type[py_serializable.ViewType]], xmlns: Optional[str], prop_info: py_serializable.ObjectMetadataLibrary.SerializableProperty, ctx: Type[Any], **kwargs: Any) -> Optional[Union[xml.etree.ElementTree.Element, Any]]
      :classmethod:


      xml specific normalizer



   .. py:method:: xml_serialize(o: Any) -> Union[str, Any]
      :classmethod:


      xml specific serializer



   .. py:method:: xml_denormalize(o: xml.etree.ElementTree.Element, *, default_ns: Optional[str], prop_info: py_serializable.ObjectMetadataLibrary.SerializableProperty, ctx: Type[Any], **kwargs: Any) -> Any
      :classmethod:


      xml specific denormalizer



   .. py:method:: xml_deserialize(o: Union[str, Any]) -> Any
      :classmethod:


      xml specific deserializer



.. py:class:: Swhid(id: str)

   Bases: :py:obj:`py_serializable.helpers.BaseHelper`


   Helper class that allows us to perform validation on data strings that must conform to
   https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html.



   .. py:property:: id
      :type: str



   .. py:method:: serialize(o: Any) -> str
      :classmethod:


      general purpose serializer



   .. py:method:: deserialize(o: Any) -> Swhid
      :classmethod:


      general purpose deserializer



   .. py:method:: json_normalize(o: Any, *, view: Optional[Type[py_serializable.ViewType]], prop_info: py_serializable.ObjectMetadataLibrary.SerializableProperty, ctx: Type[Any], **kwargs: Any) -> Optional[Any]
      :classmethod:


      json specific normalizer



   .. py:method:: json_serialize(o: Any) -> Union[str, Any]
      :classmethod:


      json specific serializer



   .. py:method:: json_denormalize(o: Any, *, prop_info: py_serializable.ObjectMetadataLibrary.SerializableProperty, ctx: Type[Any], **kwargs: Any) -> Any
      :classmethod:


      json specific denormalizer

      :param tCls: the class that was desired to denormalize to
      :param pCls: tha prent class - as context



   .. py:method:: json_deserialize(o: Any) -> Any
      :classmethod:


      json specific deserializer



   .. py:method:: xml_normalize(o: Any, *, element_name: str, view: Optional[Type[py_serializable.ViewType]], xmlns: Optional[str], prop_info: py_serializable.ObjectMetadataLibrary.SerializableProperty, ctx: Type[Any], **kwargs: Any) -> Optional[Union[xml.etree.ElementTree.Element, Any]]
      :classmethod:


      xml specific normalizer



   .. py:method:: xml_serialize(o: Any) -> Union[str, Any]
      :classmethod:


      xml specific serializer



   .. py:method:: xml_denormalize(o: xml.etree.ElementTree.Element, *, default_ns: Optional[str], prop_info: py_serializable.ObjectMetadataLibrary.SerializableProperty, ctx: Type[Any], **kwargs: Any) -> Any
      :classmethod:


      xml specific denormalizer



   .. py:method:: xml_deserialize(o: Union[str, Any]) -> Any
      :classmethod:


      xml specific deserializer



.. py:class:: Component(*, name: str, type: ComponentType = ComponentType.LIBRARY, mime_type: Optional[str] = None, bom_ref: Optional[Union[str, cyclonedx.model.bom_ref.BomRef]] = None, supplier: Optional[cyclonedx.model.contact.OrganizationalEntity] = None, publisher: Optional[str] = None, group: Optional[str] = None, version: Optional[str] = None, description: Optional[str] = None, scope: Optional[ComponentScope] = None, hashes: Optional[collections.abc.Iterable[cyclonedx.model.HashType]] = None, licenses: Optional[collections.abc.Iterable[cyclonedx.model.license.License]] = None, copyright: Optional[str] = None, purl: Optional[packageurl.PackageURL] = None, external_references: Optional[collections.abc.Iterable[cyclonedx.model.ExternalReference]] = None, properties: Optional[collections.abc.Iterable[cyclonedx.model.Property]] = None, release_notes: Optional[cyclonedx.model.release_note.ReleaseNotes] = None, cpe: Optional[str] = None, swid: Optional[Swid] = None, pedigree: Optional[Pedigree] = None, components: Optional[collections.abc.Iterable[Component]] = None, evidence: Optional[cyclonedx.model.component_evidence.ComponentEvidence] = None, modified: bool = False, manufacturer: Optional[cyclonedx.model.contact.OrganizationalEntity] = None, authors: Optional[collections.abc.Iterable[cyclonedx.model.contact.OrganizationalContact]] = None, omnibor_ids: Optional[collections.abc.Iterable[OmniborId]] = None, swhids: Optional[collections.abc.Iterable[Swhid]] = None, crypto_properties: Optional[cyclonedx.model.crypto.CryptoProperties] = None, tags: Optional[collections.abc.Iterable[str]] = None, author: Optional[str] = None)

   Bases: :py:obj:`cyclonedx.model.dependency.Dependable`


   This is our internal representation of a Component within a Bom.

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


   .. py:method:: for_file(absolute_file_path: str, path_for_bom: Optional[str]) -> Component
      :staticmethod:


      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.

      .. deprecated:: next
          Use ``cyclonedx.contrib.component.builders.ComponentBuilder().make_for_file()`` instead.



   .. py:property:: type
      :type: ComponentType


      Get the type of this Component.

      Returns:
          Declared type of this Component as `ComponentType`.



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


      Get any declared mime-type for this Component.

      When used on file components, the mime-type can provide additional context about the kind of file being
      represented such as an image, font, or executable. Some library or framework components may also have an
      associated mime-type.

      Returns:
          `str` if set else `None`



   .. py:property:: supplier
      :type: Optional[cyclonedx.model.contact.OrganizationalEntity]


      The organization that supplied the component. The supplier may often be the manufacture, but may also be a
      distributor or repackager.

      Returns:
          `OrganizationalEntity` if set else `None`



   .. py:property:: manufacturer
      :type: Optional[cyclonedx.model.contact.OrganizationalEntity]


      The organization that created the component.
      Manufacturer is common in components created through automated processes.
      Components created through manual means may have `@.authors` instead.

      Returns:
          `OrganizationalEntity` if set else `None`



   .. py:property:: authors
      :type: SortedSet[OrganizationalContact]


      The person(s) who created the component.
      Authors are common in components created through manual processes.
      Components created through automated means may have `@.manufacturer` instead.

      Returns:
          `Iterable[OrganizationalContact]` if set else `None`



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


      The person(s) or organization(s) that published the component

      Returns:
          `str` if set else `None`



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


      The grouping name or identifier. This will often be a shortened, single name of the company or project that
      produced the component, or the source package or domain name. Whitespace and special characters should be
      avoided.

      Examples include: `apache`, `org.apache.commons`, and `apache.org`.

      Returns:
          `str` if set else `None`



   .. py:property:: name
      :type: str


      The name of the component.

      This will often be a shortened, single name of the component.

      Examples: `commons-lang3` and `jquery`.

      Returns:
          `str`



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


      Get the description of this Component.

      Returns:
          `str` if set, else `None`.



   .. py:property:: scope
      :type: Optional[ComponentScope]


      Specifies the scope of the component.

      If scope is not specified, 'required' scope should be assumed by the consumer of the BOM.

      Returns:
          `ComponentScope` or `None`



   .. py:property:: hashes
      :type: SortedSet[HashType]


      Optional list of hashes that help specify the integrity of this Component.

      Returns:
           Set of `HashType`



   .. py:property:: licenses
      :type: cyclonedx.model.license.LicenseRepository


      A optional list of statements about how this Component is licensed.

      Returns:
          Set of `LicenseChoice`



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


      An optional copyright notice informing users of the underlying claims to copyright ownership in a published
      work.

      Returns:
          `str` or `None`



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


      Specifies a well-formed CPE name that conforms to the CPE 2.2 or 2.3 specification.
      See https://nvd.nist.gov/products/cpe

      Returns:
          `str` if set else `None`



   .. py:property:: purl
      :type: Optional[packageurl.PackageURL]


      Specifies the package-url (PURL).

      The purl, if specified, must be valid and conform to the specification defined at:
      https://github.com/package-url/purl-spec

      Returns:
          `PackageURL` or `None`



   .. py:property:: omnibor_ids
      :type: SortedSet[OmniborId]


      Specifies the OmniBOR Artifact ID. The OmniBOR, if specified, MUST be valid and conform to the specification
      defined at: https://www.iana.org/assignments/uri-schemes/prov/gitoid

      Returns:
          `Iterable[str]` or `None`



   .. py:property:: swhids
      :type: SortedSet[Swhid]


      Specifies the Software Heritage persistent identifier (SWHID). The SWHID, if specified, MUST be valid and
      conform to the specification defined at:
      https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html

      Returns:
          `Iterable[Swhid]` if set else `None`



   .. py:property:: swid
      :type: Optional[Swid]


      Specifies metadata and content for ISO-IEC 19770-2 Software Identification (SWID) Tags.

      Returns:
          `Swid` if set else `None`



   .. py:property:: pedigree
      :type: Optional[Pedigree]


      Component pedigree is a way to document complex supply chain scenarios where components are created,
      distributed, modified, redistributed, combined with other components, etc.

      Returns:
          `Pedigree` if set else `None`



   .. py:property:: external_references
      :type: SortedSet[ExternalReference]


      Provides the ability to document external references related to the component or to the project the component
      describes.

      Returns:
          Set of `ExternalReference`



   .. 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:: components
      :type: SortedSet['Component']


      A list of software and hardware components included in the parent component. This is not a dependency tree. It
      provides a way to specify a hierarchical representation of component assemblies, similar to system -> subsystem
      -> parts assembly in physical supply chains.

      Returns:
          Set of `Component`



   .. py:property:: evidence
      :type: Optional[cyclonedx.model.component_evidence.ComponentEvidence]


      Provides the ability to document evidence collected through various forms of extraction or analysis.

      Returns:
          `ComponentEvidence` if set else `None`



   .. py:property:: release_notes
      :type: Optional[cyclonedx.model.release_note.ReleaseNotes]


      Specifies optional release notes.

      Returns:
          `ReleaseNotes` or `None`



   .. py:property:: crypto_properties
      :type: Optional[cyclonedx.model.crypto.CryptoProperties]


      Cryptographic assets have properties that uniquely define them and that make them actionable for further
      reasoning. As an example, it makes a difference if one knows the algorithm family (e.g. AES) or the specific
      variant or instantiation (e.g. AES-128-GCM). This is because the security level and the algorithm primitive
      (authenticated encryption) is only defined by the definition of the algorithm variant. The presence of a weak
      cryptographic algorithm like SHA1 vs. HMAC-SHA1 also makes a difference.

      Returns:
          `CryptoProperties` or `None`



   .. py:property:: tags
      :type: SortedSet[str]


      Textual strings that aid in discovery, search, and retrieval of the associated object.
      Tags often serve as a way to group or categorize similar or related objects by various attributes.

      Returns:
          `Iterable[str]`



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


      The person(s) or organization(s) that authored the component.

      Returns:
          `str` if set else `None`



   .. py:property:: modified
      :type: bool



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


      The component version. The version should ideally comply with semantic versioning but is not enforced.

      This is NOT optional for CycloneDX Schema Version < 1.4 but was agreed to default to an empty string where a
      version was not supplied for schema versions < 1.4

      Returns:
          Declared version of this Component as `str` or `None`



   .. 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:method:: get_all_nested_components(include_self: bool = False) -> set[Component]


   .. py:method:: get_pypi_url() -> str


