# cyclonedx.model.component

## Classes

`Commit` | Our internal representation of the commitType complex type.
`ComponentScope` | Enum object that defines the permissable 'scopes' for a Component according to the CycloneDX schema.
`ComponentType` | Enum object that defines the permissible 'types' for a Component according to the CycloneDX schema.
`Diff` | Our internal representation of the diffType complex type.
`PatchClassification` | Enum object that defines the permissible `patchClassification`s.
`Patch` | Our internal representation of the patchType complex type.
`Pedigree` | Our internal representation of the pedigreeType complex type.
`Swid` | Our internal representation of the swidType complex type.
`OmniborId` | Helper class that allows us to perform validation on data strings that must conform to
`Swhid` | Helper class that allows us to perform validation on data strings that must conform to
`Component` | This is our internal representation of a Component within a Bom.

## Module Contents

class cyclonedx.model.component.Commit(*, uid: str | None = None, url: cyclonedx.model.XsUri | None = None, author: cyclonedx.model.IdentifiableAction | None = None, committer: cyclonedx.model.IdentifiableAction | None = None, message: str | None = None)

  Our internal representation of the commitType complex type.

  Note

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

  property uid: str | None

    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

  property url: cyclonedx.model.XsUri | None

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

    Returns:

      XsUri if set else None

  property author: cyclonedx.model.IdentifiableAction | None

    The author who created the changes in the commit.

    Returns:

      IdentifiableAction if set else None

  property committer: cyclonedx.model.IdentifiableAction | None

    The person who committed or pushed the commit

    Returns:

      IdentifiableAction if set else None

  property message: str | None

    The text description of the contents of the commit.

    Returns:

      str if set else None

class cyclonedx.model.component.ComponentScope

  Bases: `str`, `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

  REQUIRED = 'required'
  OPTIONAL = 'optional'
  EXCLUDED = 'excluded'

class cyclonedx.model.component.ComponentType

  Bases: `str`, `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

  APPLICATION = 'application'
  CONTAINER = 'container'
  CRYPTOGRAPHIC_ASSET = 'cryptographic-asset'
  DATA = 'data'
  DEVICE = 'device'
  DEVICE_DRIVER = 'device-driver'
  FILE = 'file'
  FIRMWARE = 'firmware'
  FRAMEWORK = 'framework'
  LIBRARY = 'library'
  MACHINE_LEARNING_MODEL = 'machine-learning-model'
  OPERATING_SYSTEM = 'operating-system'
  PLATFORM = 'platform'

class cyclonedx.model.component.Diff(*, text: cyclonedx.model.AttachedText | None = None, url: cyclonedx.model.XsUri | None = None)

  Our internal representation of the diffType complex type.

  Note

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

  property text: cyclonedx.model.AttachedText | None

    Specifies the optional text of the diff.

    Returns:

      AttachedText if set else None

  property url: cyclonedx.model.XsUri | None

    Specifies the URL to the diff.

    Returns:

      XsUri if set else None

class cyclonedx.model.component.PatchClassification

  Bases: `str`, `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

  BACKPORT = 'backport'
  CHERRY_PICK = 'cherry-pick'
  MONKEY = 'monkey'
  UNOFFICIAL = 'unofficial'

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

  Our internal representation of the patchType complex type.

  Note

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

  property type: PatchClassification

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

    Returns:

      PatchClassification

  property diff: Diff | None

    The patch file (or diff) that show changes.

    Note

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

    Returns:

      Diff if set else None

  property resolves: SortedSet[IssueType]

    Optional list of issues resolved by this patch.

    Returns:

      Set of IssueType

class cyclonedx.model.component.Pedigree(*, ancestors: collections.abc.Iterable[Component] | None = None, descendants: collections.abc.Iterable[Component] | None = None, variants: collections.abc.Iterable[Component] | None = None, commits: collections.abc.Iterable[Commit] | None = None, patches: collections.abc.Iterable[Patch] | None = None, notes: str | None = 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

  property ancestors: 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

  property descendants: 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

  property variants: 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

  property commits: 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

  property patches: 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

  property notes: str | None

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

    Returns:

      str if set else None

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

  Our internal representation of the swidType complex type.

  Note

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

  property tag_id: str

    Maps to the tagId of a SoftwareIdentity.

    Returns:

      str

  property name: str

    Maps to the name of a SoftwareIdentity.

    Returns:

      str

  property version: str | None

    Maps to the version of a SoftwareIdentity.

    Returns:

      str if set else None.

  property tag_version: int | None

    Maps to the tagVersion of a SoftwareIdentity.

    Returns:

      int if set else None

  property patch: bool | None

    Maps to the patch of a SoftwareIdentity.

    Returns:

      bool if set else None

  property text: cyclonedx.model.AttachedText | None

    Specifies the full content of the SWID tag.

    Returns:

      AttachedText if set else None

  property url: cyclonedx.model.XsUri | None

    The URL to the SWID file.

    Returns:

      XsUri if set else None

class cyclonedx.model.component.OmniborId(id: str)

  Bases: `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.

  property id: str
  classmethod serialize(o: Any) → str

    general purpose serializer

  classmethod deserialize(o: Any) → OmniborId

    general purpose deserializer

  classmethod json_normalize(o: Any, *, view: Type[py_serializable.ViewType] | None, prop_info: py_serializable.ObjectMetadataLibrary.SerializableProperty, ctx: Type[Any], **kwargs: Any) → Any | None

    json specific normalizer

  classmethod json_serialize(o: Any) → str | Any

    json specific serializer

  classmethod json_denormalize(o: Any, *, prop_info: py_serializable.ObjectMetadataLibrary.SerializableProperty, ctx: Type[Any], **kwargs: Any) → Any

    json specific denormalizer

    Parameters:

      - tCls – the class that was desired to denormalize to

      - pCls – tha prent class - as context

  classmethod json_deserialize(o: Any) → Any

    json specific deserializer

  classmethod xml_normalize(o: Any, *, element_name: str, view: Type[py_serializable.ViewType] | None, xmlns: str | None, prop_info: py_serializable.ObjectMetadataLibrary.SerializableProperty, ctx: Type[Any], **kwargs: Any) → xml.etree.ElementTree.Element | Any | None

    xml specific normalizer

  classmethod xml_serialize(o: Any) → str | Any

    xml specific serializer

  classmethod xml_denormalize(o: xml.etree.ElementTree.Element, *, default_ns: str | None, prop_info: py_serializable.ObjectMetadataLibrary.SerializableProperty, ctx: Type[Any], **kwargs: Any) → Any

    xml specific denormalizer

  classmethod xml_deserialize(o: str | Any) → Any

    xml specific deserializer

class cyclonedx.model.component.Swhid(id: str)

  Bases: `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.

  property id: str
  classmethod serialize(o: Any) → str

    general purpose serializer

  classmethod deserialize(o: Any) → Swhid

    general purpose deserializer

  classmethod json_normalize(o: Any, *, view: Type[py_serializable.ViewType] | None, prop_info: py_serializable.ObjectMetadataLibrary.SerializableProperty, ctx: Type[Any], **kwargs: Any) → Any | None

    json specific normalizer

  classmethod json_serialize(o: Any) → str | Any

    json specific serializer

  classmethod json_denormalize(o: Any, *, prop_info: py_serializable.ObjectMetadataLibrary.SerializableProperty, ctx: Type[Any], **kwargs: Any) → Any

    json specific denormalizer

    Parameters:

      - tCls – the class that was desired to denormalize to

      - pCls – tha prent class - as context

  classmethod json_deserialize(o: Any) → Any

    json specific deserializer

  classmethod xml_normalize(o: Any, *, element_name: str, view: Type[py_serializable.ViewType] | None, xmlns: str | None, prop_info: py_serializable.ObjectMetadataLibrary.SerializableProperty, ctx: Type[Any], **kwargs: Any) → xml.etree.ElementTree.Element | Any | None

    xml specific normalizer

  classmethod xml_serialize(o: Any) → str | Any

    xml specific serializer

  classmethod xml_denormalize(o: xml.etree.ElementTree.Element, *, default_ns: str | None, prop_info: py_serializable.ObjectMetadataLibrary.SerializableProperty, ctx: Type[Any], **kwargs: Any) → Any

    xml specific denormalizer

  classmethod xml_deserialize(o: str | Any) → Any

    xml specific deserializer

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

  Bases: `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

  static for_file(absolute_file_path: str, path_for_bom: str | None) → Component

    Deprecated — Wrapper of `cyclonedx.contrib.component.builders.ComponentBuilder.make_for_file()`.

    Helper method to create a Component that represents the provided local file as a Component.

    Deprecated since version next: Use `cyclonedx.contrib.component.builders.ComponentBuilder().make_for_file()` instead.

  property type: ComponentType

    Get the type of this Component.

    Returns:

      Declared type of this Component as ComponentType.

  property mime_type: str | None

    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

  property supplier: cyclonedx.model.contact.OrganizationalEntity | None

    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

  property manufacturer: cyclonedx.model.contact.OrganizationalEntity | None

    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

  property authors: 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

  property publisher: str | None

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

    Returns:

      str if set else None

  property group: str | None

    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

  property name: str

    The name of the component.

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

    Examples: commons-lang3 and jquery.

    Returns:

      str

  property description: str | None

    Get the description of this Component.

    Returns:

      str if set, else None.

  property scope: ComponentScope | None

    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

  property hashes: SortedSet[HashType]

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

    Returns:

      Set of HashType

  property licenses: cyclonedx.model.license.LicenseRepository

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

    Returns:

      Set of LicenseChoice

  property copyright: str | None

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

    Returns:

      str or None

  property cpe: str | None

    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

  property purl: packageurl.PackageURL | None

    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

  property omnibor_ids: 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

  property swhids: 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

  property swid: Swid | None

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

    Returns:

      Swid if set else None

  property pedigree: Pedigree | None

    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

  property external_references: SortedSet[ExternalReference]

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

    Returns:

      Set of ExternalReference

  property properties: 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

  property components: 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

  property evidence: cyclonedx.model.component_evidence.ComponentEvidence | None

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

    Returns:

      ComponentEvidence if set else None

  property release_notes: cyclonedx.model.release_note.ReleaseNotes | None

    Specifies optional release notes.

    Returns:

      ReleaseNotes or None

  property crypto_properties: cyclonedx.model.crypto.CryptoProperties | None

    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

  property tags: 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]

  property author: str | None

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

    Returns:

      str if set else None

  property modified: bool
  property version: str | None

    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

  property bom_ref: 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

  get_all_nested_components(include_self: bool = False) → set[Component]
  get_pypi_url() → str