:py:mod:`spdx` ============== .. py:module:: spdx .. autoapi-nested-parse:: Generate an SPDX file. This is following the specification from https://spdx.github.io/spdx-spec/v2.3/ a simple example can be found at ./tests/tests_e3/spdx_test.py Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: spdx.SPDXPackageSupplier spdx.SPDXEntry spdx.SPDXEntryStr spdx.SPDXEntryMaybeStr spdx.SPDXEntryMaybeStrMultilines spdx.SPDXEntryBool spdx.SPDXSection spdx.SPDXVersion spdx.DataLicense spdx.SPDXID spdx.DocumentName spdx.DocumentNamespace spdx.LicenseListVersion spdx.Entity spdx.EntityRef spdx.Creator spdx.Created spdx.Organization spdx.Person spdx.Tool spdx.PackageName spdx.PackageVersion spdx.PackageFileName spdx.PackageSupplier spdx.PackageOriginator spdx.PackageDownloadLocation spdx.FilesAnalyzed spdx.PackageChecksum spdx.PackageHomePage spdx.SHA1 spdx.SHA256 spdx.SHA512 spdx.PackageLicenseConcluded spdx.PackageLicenseDeclared spdx.PackageLicenseComments spdx.PackageCopyrightText spdx.PackageDescription spdx.PackageComment spdx.ExternalRefCategory spdx.ExternalRef spdx.PrimaryPackagePurpose spdx.RelationshipType spdx.Relationship spdx.Package spdx.DocumentInformation spdx.CreationInformation spdx.Document Functions ~~~~~~~~~ .. autoapisummary:: spdx.get_entity Attributes ~~~~~~~~~~ .. autoapisummary:: spdx.NOASSERTION spdx.NONE_VALUE spdx.MAYBE_STR spdx.SPDXID_R spdx.InvalidSPDX spdx.SECURITY spdx.PACKAGE_MANAGER spdx.PERSISTENT_ID spdx.OTHER spdx.SPDX_EXTERNAL_REF_TYPES .. py:data:: NOASSERTION :type: Literal[NOASSERTION] :value: 'NOASSERTION' Indicates that the preparer of the SPDX document is not making any assertion regarding the value of this field. .. py:data:: NONE_VALUE :type: Literal[NONE] :value: 'NONE' When this value is used as the object of a property it indicates that the preparer of the SpdxDocument believes that there is no value for the property. This value should only be used if there is sufficient evidence to support this assertion. .. py:data:: MAYBE_STR .. py:data:: SPDXID_R .. py:function:: get_entity(value: str | None) -> Organization | Person | Tool | None Get an entity according to an entity string. The entity string looks like ``: ``. If the entity type is ``Organization``, ``Person`` or ``Tool``, the appropriate :class:`Organization`, :class:`Person` or :class:`Tool` initialised with *entity_name* is returned. If not possible match if found, :const:`None` is returned. :param value: A string to extract entity definition from. :return: The entity initialised by *value*, or :const:`None` on error. .. py:exception:: InvalidSPDXError Bases: :py:obj:`Exception` Raise an exception when the SPDX document cannot be generated. .. py:data:: InvalidSPDX .. py:class:: SPDXPackageSupplier(*args, **kwds) Bases: :py:obj:`enum.Enum` Used by the SPDX originator field. This field is composed of a package supplier type (organization, person, tool) and a name. This enum represents the package supplier type. .. py:attribute:: ORGANIZATION :value: 'Organization' .. py:attribute:: PERSON :value: 'Person' .. py:attribute:: TOOL :value: 'Tool' .. py:class:: SPDXEntry Describe an SPDX Entry. .. py:property:: entry_key :type: str Name of the SPDXEntry as visible in the SPDX tag:value report. .. py:property:: json_entry_key :type: str Name of the SPDXEntry as visible in the SPDX JSON report. .. py:method:: get_entry_key() -> str :classmethod: Name of the SPDXEntry as visible in the SPDX tag:value report. .. py:method:: get_json_entry_key() -> str :classmethod: Name of the SPDXEntry as visible in the SPDX JSON report. .. py:method:: __str__() -> str :abstractmethod: Return string representation of SPDX entry. .. py:method:: __format__(format_spec: str) -> str Format the entry. :param format_spec: format specification .. py:method:: to_tagvalue() -> str Return a valid tag:value line. .. py:method:: to_json_dict() -> dict[str, Any] :abstractmethod: Return a chunk of the SPDX JSON document. .. py:class:: SPDXEntryStr(value: str) Bases: :py:obj:`SPDXEntry` Describe an SPDX Entry accepting a string. .. py:method:: __str__() -> str Return string representation of SPDX entry. .. py:method:: __gt__(other: object) -> bool Compare entries. :param other: other entry to compare with .. py:method:: to_json_dict() -> dict[str, Any] Convert to JSON-serializable dictionary format. .. py:class:: SPDXEntryMaybeStr(value: MAYBE_STR) Bases: :py:obj:`SPDXEntry` Describe an SPDX Entry accepting a string, NOASSERTION, or NONE. .. py:method:: __str__() -> str Return string representation of SPDX entry. .. py:method:: to_json_dict() -> dict[str, Any] Convert to JSON-serializable dictionary format. .. py:class:: SPDXEntryMaybeStrMultilines(value: MAYBE_STR) Bases: :py:obj:`SPDXEntryMaybeStr` SPDX entry that can contain multiline string values. .. py:method:: to_tagvalue() -> str Return the content that can span to multiple lines. In tag:value format multiple lines are delimited by .... .. py:class:: SPDXEntryBool(value: bool) Bases: :py:obj:`SPDXEntry` Describe an SPDX Entry accepting a boolean. .. py:method:: __str__() -> str Return string representation of boolean value. .. py:method:: to_json_dict() -> dict[str, Any] Convert to JSON-serializable dictionary format. .. py:class:: SPDXSection Describe an SPDX section. .. py:method:: to_tagvalue() -> list[str] Generate a chunk of an SPDX tag:value document. Return a list of SPDX lines .. py:method:: to_json_dict() -> dict[str, Any] Convert to JSON-serializable dictionary format. .. py:class:: SPDXVersion(value: str) Bases: :py:obj:`SPDXEntryStr` Provide the SPDX version used to generate the document. See 6.1 `SPDX version field `_. .. py:attribute:: VERSION :type: str :value: 'SPDX-2.3' .. py:attribute:: json_entry_key :value: 'spdxVersion' .. py:method:: from_json_dict(obj: dict[str, Any]) -> SPDXVersion :classmethod: Initialize an :class:`SPDXVersion` from a :class:`dict`. If an SPDX version value could not be extracted from *obj*, the default value :attr:`SPDXVersion.VERSION` is used. :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize an :class:`SPDXVersion` with. For instance: >>> from e3.spdx import SPDXVersion >>> SPDXVersion.from_json_dict({"spdxVersion": "1.2.3"}).value '1.2.3' >>> SPDXVersion.from_json_dict({"xxx": "1.2.3"}).value 'SPDX-2.3' :return: The :class:`SPDXVersion` initialized with the value of *obj*. .. py:class:: DataLicense(value: str) Bases: :py:obj:`SPDXEntryStr` License of the SPDX Metadata. See 6.2 `Data license field `_. .. py:attribute:: LICENSE :type: str :value: 'CC0-1.0' .. py:method:: from_json_dict(obj: dict[str, Any]) -> DataLicense :classmethod: Initialize a :class:`DataLicense` from a :class:`dict`. If a data license value could not be extracted from *obj*, the default value :attr:`DataLicense.LICENSE` is used. :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize a :class:`DataLicense` with. For instance: >>> from e3.spdx import DataLicense >>> DataLicense.from_json_dict({"dataLicense": "1.2.3"}).value '1.2.3' >>> DataLicense.from_json_dict({"xxx": "1.2.3"}).value 'CC0-1.0' :return: The :class:`DataLicense` initialized with the value of *obj*. .. py:class:: SPDXID(value: str) Bases: :py:obj:`SPDXEntryStr` Identify an SPDX Document, or Package. See 6.3 `SPDX identifier field `_ and 7.2 `Package SPDX identifier field `_. The value is a unique string containing letters, numbers, ., and/or -. .. py:attribute:: PREFIX :type: str :value: 'SPDXRef-' .. py:attribute:: DEFAULT_ID :type: str :value: 'DOCUMENT' .. py:attribute:: json_entry_key :value: 'SPDXID' .. py:method:: __str__() -> str Return string representation of SPDX ID. .. py:method:: __eq__(o: object) -> bool Check equality. :param o: object to compare with .. py:method:: __hash__() -> int Return hash value of SPDX ID. .. py:method:: from_json_dict(obj: dict[str, Any]) -> SPDXID :classmethod: Initialize an :class:`SPDXID` from a :class:`dict`. If an SPDX ID value could not be extracted from *obj*, the default value :attr:`SPDXID.DEFAULT_ID` is used. :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize an :class:`SPDXID` with. For instance: >>> from e3.spdx import SPDXID >>> SPDXID.from_json_dict({"SPDXID": "1.2.3"}).value '1.2.3' >>> SPDXID.from_json_dict({"xxx": "1.2.3"}).value 'DOCUMENT' :return: The :class:`SPDXID` initialized with the value of *obj*. .. py:class:: DocumentName(value: str) Bases: :py:obj:`SPDXEntryStr` Identify name of this document. See 6.4 `Document name field `_. .. py:attribute:: json_entry_key :value: 'name' .. py:class:: DocumentNamespace(value: str) Bases: :py:obj:`SPDXEntryStr` Provide a unique URI for this document. See 6.5 `SPDX document namespace field `_. .. py:method:: from_json_dict(obj: dict[str, Any]) -> DocumentNamespace :classmethod: Initialize a :class:`DocumentNamespace` from a :class:`dict`. If a document namespace value could not be extracted from *obj*, an empty string is used. :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize a :class:`DocumentNamespace` with. For instance: >>> from e3.spdx import DocumentNamespace >>> DocumentNamespace.from_json_dict({"documentNamespace": "namespace"}).value 'namespace' >>> DocumentNamespace.from_json_dict({"xxx": "namespace"}).value '' :return: The :class:`DocumentNamespace` initialized with the value of *obj*. .. py:class:: LicenseListVersion(value: str) Bases: :py:obj:`SPDXEntryStr` Provide the version of the SPDX License List used. See 6.7 `License list version field `_. .. py:attribute:: VERSION :type: str :value: '3.19' Default license list version value. .. py:method:: from_json_dict(obj: dict[str, str]) -> LicenseListVersion :classmethod: Initialize a :class:`LicenseListVersion` from a :class:`dict`. If a license list version value could not be extracted from *obj*, the default :attr:`LicenseListVersion.VERSION` value is used. :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize a :class:`LicenseListVersion` with. For instance: >>> from e3.spdx import LicenseListVersion >>> LicenseListVersion.from_json_dict({"licenseListVersion": "3.2.1"}).value '3.2.1' >>> LicenseListVersion.from_json_dict({"xxx": "3.2.1"}).value '3.19' :return: The :class:`LicenseListVersion` initialized with the value of *obj*. .. py:class:: Entity(value: str) Bases: :py:obj:`SPDXEntryStr` Represent an Entity (Organization, Person, Tool). .. py:method:: from_json_dict(obj: dict[str, str]) -> Tool | Person | Organization | None :classmethod: Initialize an :class:`Entity` from a :class:`dict`. :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize an :class:`Entity` with. :return: The :class:`Entity` initialized with the value of *obj*, or :const:`None` if the JSON key does not match. .. py:class:: EntityRef(value: Entity | Literal[NOASSERTION]) Bases: :py:obj:`SPDXEntry` Reference an Entity. Accept NOASSERTION as a valid value. .. py:method:: __str__() -> str Return string representation of entity reference. .. py:method:: to_tagvalue() -> str Convert to SPDX tag-value format string. .. py:method:: to_json_dict() -> dict[str, Any] Convert to JSON-serializable dictionary format. .. py:class:: Creator(value: Entity | Literal[NOASSERTION]) Bases: :py:obj:`EntityRef` Identify who (or what, in the case of a tool) created the SPDX document. See 6.8 `Creator field `_. .. py:attribute:: json_entry_key :value: 'creators' .. py:method:: from_json_dict(obj: dict[str, Any]) -> Creator | None :classmethod: Initialize a :class:`Creator` from a :class:`dict`. :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize a :class:`Creator` with. :return: The :class:`Creator` initialized with the value of *obj*, or :const:`None` if the JSON key does not match. .. py:class:: Created(value: str) Bases: :py:obj:`SPDXEntryStr` Identify when the SPDX document was originally created. See 6.9 `Created field `_. .. py:method:: from_json_dict(obj: dict[str, Any]) -> Created :classmethod: Initialize a :class:`Created` from a :class:`dict`. :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize an :class:`Created` with. :return: The :class:`Created` initialized with the value of *obj*. .. py:class:: Organization(value: str) Bases: :py:obj:`Entity` Identify an organization by its name. .. py:class:: Person(value: str) Bases: :py:obj:`Entity` Identify a person by its name. .. py:class:: Tool(value: str) Bases: :py:obj:`Entity` Identify a tool. .. py:class:: PackageName(value: str) Bases: :py:obj:`SPDXEntryStr` Identify the full name of the package. See 7.1 `Package name field `_ .. py:attribute:: json_entry_key :value: 'name' .. py:method:: from_json_dict(obj: dict[str, Any]) -> PackageName :classmethod: Initialize a :class:`PackageName` from a :class:`dict`. :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize an :class:`PackageName` with. :return: The :class:`PackageName` initialized with the value of *obj*. .. py:class:: PackageVersion(value: str) Bases: :py:obj:`SPDXEntryStr` Identify the version of the package. See 7.3 `Package version field `_ .. py:attribute:: json_entry_key :value: 'versionInfo' .. py:method:: from_json_dict(obj: dict[str, Any]) -> PackageVersion :classmethod: Initialize a :class:`PackageVersion` from a :class:`dict`. :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize an :class:`PackageVersion` with. :return: The :class:`PackageVersion` initialized with the value of *obj*. .. py:class:: PackageFileName(value: str) Bases: :py:obj:`SPDXEntryStr` Provide the actual file name of the package. See 7.4 `Package file name field `_ .. py:method:: from_json_dict(obj: dict[str, Any]) -> PackageFileName :classmethod: Initialize a :class:`PackageFileName` from a :class:`dict`. :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize an :class:`PackageFileName` with. :return: The :class:`PackageFileName` initialized with the value of *obj*. .. py:class:: PackageSupplier(value: Entity | Literal[NOASSERTION]) Bases: :py:obj:`EntityRef` Identify the actual distribution source for the package. See 7.5 `Package supplier field `_ .. py:attribute:: json_entry_key :value: 'supplier' .. py:method:: from_json_dict(obj: dict[str, Any]) -> PackageSupplier | None :classmethod: Initialize a :class:`PackageSupplier` from a :class:`dict`. :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize a :class:`PackageSupplier` with. :return: The :class:`PackageSupplier` initialized with the value of *obj*, or :const:`None` if the JSON key does not match. .. py:class:: PackageOriginator(value: Entity | Literal[NOASSERTION]) Bases: :py:obj:`EntityRef` Identify from where the package originally came. See 7.6 `Package originator field `_ .. py:attribute:: json_entry_key :value: 'originator' .. py:method:: from_json_dict(obj: dict[str, Any]) -> PackageOriginator | None :classmethod: Initialize a :class:`PackageOriginator` from a :class:`dict`. :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize a :class:`PackageOriginator` with. :return: The :class:`PackageOriginator` initialized with the value of *obj*, or :const:`None` if the JSON key does not match. .. py:class:: PackageDownloadLocation(value: MAYBE_STR) Bases: :py:obj:`SPDXEntryMaybeStr` Identifies the download location of the package. See 7.7 `Package download location field `_ .. py:attribute:: json_entry_key :value: 'downloadLocation' .. py:method:: from_json_dict(obj: dict[str, Any]) -> PackageDownloadLocation :classmethod: Initialize a :class:`PackageDownloadLocation` from a :class:`dict`. :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize an :class:`PackageDownloadLocation` with. :return: The :class:`PackageDownloadLocation` initialized with the value of *obj*. .. py:class:: FilesAnalyzed(value: bool) Bases: :py:obj:`SPDXEntryBool` Indicates whether the file content of this package have been analyzed. See 7.8 `Files analyzed field `_ .. py:method:: from_json_dict(obj: dict[str, Any]) -> FilesAnalyzed :classmethod: Initialize a :class:`FilesAnalyzed` from a :class:`dict`. By default, if *obj* does not contain this class' JSON entry key, ``FilesAnalyzed(False)`` is returned. :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize an :class:`FilesAnalyzed` with. :return: The :class:`FilesAnalyzed` initialized with the value of *obj*. .. py:class:: PackageChecksum(value: str) Bases: :py:obj:`SPDXEntryStr` Provide a mechanism that permits unique identification of the package. See 7.10 `Package checksum field `_ .. py:property:: algorithm :type: str :abstractmethod: Algorithm. .. py:attribute:: entry_key :value: 'PackageChecksum' .. py:attribute:: json_entry_key :value: 'checksums' .. py:method:: __str__() -> str Return string representation of package checksum. .. py:method:: to_json_dict() -> dict[str, dict[str, str]] Convert to JSON-serializable dictionary format. .. py:method:: from_json_dict(obj: dict[str, Any]) -> PackageChecksum :classmethod: Initialize a :class:`PackageChecksum` from a :class:`dict`. Supported algorithms so far: - `sha1` - `sha256` - `sha512` :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize an :class:`PackageChecksum` with. :return: The :class:`PackageChecksum` initialized with the value of *obj*. :raise: :exc:`ValueError` if the algorithm defined by *obj* is not supported. .. py:class:: PackageHomePage(value: MAYBE_STR) Bases: :py:obj:`SPDXEntryMaybeStr` Identifies the homepage location of the package. See 7.11 `Package home page field `_ .. py:attribute:: json_entry_key :value: 'homepage' .. py:method:: from_json_dict(obj: dict[str, Any]) -> PackageHomePage | None :classmethod: Initialize a :class:`PackageHomePage` from a :class:`dict`. :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize an :class:`PackageHomePage` with. :return: The :class:`PackageHomePage` initialized with the value of *obj*. .. py:class:: SHA1(value: str) Bases: :py:obj:`PackageChecksum` SHA1 checksum for SPDX package verification. .. py:attribute:: algorithm :value: 'SHA1' .. py:class:: SHA256(value: str) Bases: :py:obj:`PackageChecksum` SHA256 checksum for SPDX package verification. .. py:attribute:: algorithm :value: 'SHA256' .. py:class:: SHA512(value: str) Bases: :py:obj:`PackageChecksum` SHA512 checksum for SPDX package verification. .. py:attribute:: algorithm :value: 'SHA512' .. py:class:: PackageLicenseConcluded(value: MAYBE_STR) Bases: :py:obj:`SPDXEntryMaybeStr` Contain the license concluded as governing the package. See 7.13 `Concluded license field `_ .. py:attribute:: json_entry_key :value: 'licenseConcluded' .. py:method:: from_json_dict(obj: dict[str, Any]) -> PackageLicenseConcluded :classmethod: Initialize a :class:`PackageLicenseConcluded` from a :class:`dict`. By default a :class:`PackageLicenseConcluded(NONE_VALUE)` is returned. :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize an :class:`PackageLicenseConcluded` with. :return: The :class:`PackageLicenseConcluded` initialized with the value of *obj*. .. py:class:: PackageLicenseDeclared(value: MAYBE_STR) Bases: :py:obj:`SPDXEntryMaybeStr` Contain the license having been declared by the authors of the package. See 7.15 `Declared license field `_ .. py:attribute:: json_entry_key :value: 'licenseDeclared' .. py:method:: from_json_dict(obj: dict[str, Any]) -> PackageLicenseDeclared | None :classmethod: Initialize a :class:`PackageLicenseDeclared` from a :class:`dict`. By default :const:`None` is returned. :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize an :class:`PackageLicenseDeclared` with. :return: The :class:`PackageLicenseDeclared` initialized with the value of *obj*. .. py:class:: PackageLicenseComments(value: MAYBE_STR) Bases: :py:obj:`SPDXEntryMaybeStrMultilines` Record background information or analysis for the Concluded License. See 7.16 `Comments on license field `_ .. py:attribute:: json_entry_key :value: 'licenseComments' .. py:method:: from_json_dict(obj: dict[str, Any]) -> PackageLicenseComments | None :classmethod: Initialize a :class:`PackageLicenseComments` from a :class:`dict`. By default :const:`None` is returned. :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize an :class:`PackageLicenseComments` with. :return: The :class:`PackageLicenseComments` initialized with the value of *obj*. .. py:class:: PackageCopyrightText(value: MAYBE_STR) Bases: :py:obj:`SPDXEntryMaybeStrMultilines` Identify the copyright holders of the package. See 7.17 `Copyright text field `_ .. py:attribute:: json_entry_key :value: 'copyrightText' .. py:method:: from_json_dict(obj: dict[str, Any]) -> PackageCopyrightText | None :classmethod: Initialize a :class:`PackageCopyrightText` from a :class:`dict`. By default :const:`None` is returned. :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize an :class:`PackageCopyrightText` with. :return: The :class:`PackageCopyrightText` initialized with the value of *obj*. .. py:class:: PackageDescription(value: MAYBE_STR) Bases: :py:obj:`SPDXEntryMaybeStrMultilines` A more detailed description of the package. It may also be extracted from the packages itself. Provides recipients of the SPDX document with a detailed technical explanation of the functionality, anticipated use, and anticipated implementation of the package. This field may also include a description of improvements over prior versions of the package. See 7.19 `Package detailed description field `_ .. py:attribute:: json_entry_key :value: 'description' .. py:method:: from_json_dict(obj: dict[str, Any]) -> PackageDescription | None :classmethod: Initialize a :class:`PackageDescription` from a :class:`dict`. By default :const:`None` is returned. :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize an :class:`PackageDescription` with. :return: The :class:`PackageDescription` initialized with the value of *obj*. .. py:class:: PackageComment(value: MAYBE_STR) Bases: :py:obj:`SPDXEntryMaybeStrMultilines` Record background information or analysis for the Concluded License. See 7.20 `Package comment field `_ .. py:attribute:: json_entry_key :value: 'comment' .. py:method:: from_json_dict(obj: dict[str, Any]) -> PackageComment | None :classmethod: Initialize a :class:`PackageComment` from a :class:`dict`. By default :const:`None` is returned. :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize an :class:`PackageComment` with. :return: The :class:`PackageComment` initialized with the value of *obj*. .. py:class:: ExternalRefCategory(*args, **kwds) Bases: :py:obj:`enum.Enum` Identify the category of an ExternalRef. .. py:attribute:: security :value: 'SECURITY' .. py:attribute:: package_manager :value: 'PACKAGE-MANAGER' .. py:attribute:: persistent_id :value: 'PERSISTENT-ID' .. py:attribute:: other :value: 'OTHER' .. py:data:: SECURITY .. py:data:: PACKAGE_MANAGER .. py:data:: PERSISTENT_ID .. py:data:: OTHER .. py:data:: SPDX_EXTERNAL_REF_TYPES :value: ((), (), (), (), (), (), (), (), (), (), (), (), ()) .. py:class:: ExternalRef(reference_category: ExternalRefCategory, reference_type: str, reference_locator: str) Bases: :py:obj:`SPDXEntry` Reference an external source of information relevant to the package. See 7.21 `External reference field `_ .. py:attribute:: json_entry_key :value: 'externalRefs' .. py:method:: __str__() -> str Return string representation of external reference. .. py:method:: to_json_dict() -> dict[str, dict[str, str]] Return a chunk of the SPDX JSON document. .. py:method:: from_dict(external_ref_dict: dict[str, str]) -> ExternalRef :classmethod: Initialize an :class:`ExternalRef` from a :class:`dict`. :param external_ref_dict: A :class:`dict` containing the ``"referenceCategory"``, ``"referenceType"`` and ``"referenceLocator"`` keys. The values of those keys are used to initialize a new :class:`ExternalRef`. :return: The :class:`ExternalRef` initialized with the value of *external_ref_dict*. .. py:class:: PrimaryPackagePurpose(*args, **kwds) Bases: :py:obj:`enum.Enum` Provides information about the primary purpose of the identified package. Package Purpose is intrinsic to how the package is being used rather than the content of the package. The options to populate this field are limited to the values below. See 7.24 `Primary Package Purpose field `_ .. py:attribute:: APPLICATION .. py:attribute:: FRAMEWORK .. py:attribute:: LIBRARY .. py:attribute:: CONTAINER .. py:attribute:: OPERATING_SYSTEM .. py:attribute:: DEVICE .. py:attribute:: FIRMWARE .. py:attribute:: SOURCE .. py:attribute:: ARCHIVE .. py:attribute:: FILE .. py:attribute:: INSTALL .. py:attribute:: OTHER .. py:method:: get_json_entry_key() -> str :classmethod: Return JSON entry key for this object. .. py:method:: to_tagvalue() -> str Convert to SPDX tag-value format string. .. py:method:: to_json_dict() -> dict[str, str] Convert to JSON-serializable dictionary format. .. py:method:: from_json_dict(obj: dict[str, Any]) -> PrimaryPackagePurpose | None :classmethod: Initialize a :class:`PrimaryPackagePurpose` from a :class:`dict`. By default :const:`None` is returned. :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize an :class:`PrimaryPackagePurpose` with. :return: The :class:`PrimaryPackagePurpose` initialized with the value of *obj*. .. py:class:: RelationshipType(*args, **kwds) Bases: :py:obj:`enum.Enum` Describes the type of relationship between two SPDX elements. .. py:attribute:: DESCRIBES .. py:attribute:: DESCRIBED_BY .. py:attribute:: CONTAINS .. py:attribute:: CONTAINED_BY .. py:attribute:: DEPENDS_ON .. py:attribute:: DEPENDENCY_OF .. py:attribute:: DEPENDENCY_MANIFEST_OF .. py:attribute:: BUILD_DEPENDENCY_OF .. py:attribute:: DEV_DEPENDENCY_OF .. py:attribute:: OPTIONAL_DEPENDENCY_OF .. py:attribute:: PROVIDED_DEPENDENCY_OF .. py:attribute:: TEST_DEPENDENCY_OF .. py:attribute:: RUNTIME_DEPENDENCY_OF .. py:attribute:: EXAMPLE_OF .. py:attribute:: GENERATES .. py:attribute:: GENERATED_FROM .. py:attribute:: ANCESTOR_OF .. py:attribute:: DESCENDANT_OF .. py:attribute:: VARIANT_OF .. py:attribute:: DISTRIBUTION_ARTIFACT .. py:attribute:: PATCH_FOR .. py:attribute:: PATCH_APPLIED .. py:attribute:: COPY_OF .. py:attribute:: FILE_ADDED .. py:attribute:: FILE_DELETED .. py:attribute:: FILE_MODIFIED .. py:attribute:: EXPANDED_FROM_ARCHIVE .. py:attribute:: DYNAMIC_LINK .. py:attribute:: STATIC_LINK .. py:attribute:: DATA_FILE_OF .. py:attribute:: TEST_CASE_OF .. py:attribute:: BUILD_TOOL_OF .. py:attribute:: DEV_TOOL_OF .. py:attribute:: TEST_OF .. py:attribute:: TEST_TOOL_OF .. py:attribute:: DOCUMENTATION_OF .. py:attribute:: OPTIONAL_COMPONENT_OF .. py:attribute:: METAFILE_OF .. py:attribute:: PACKAGE_OF .. py:attribute:: AMENDS .. py:attribute:: PREREQUISITE_FOR .. py:attribute:: HAS_PREREQUISITE .. py:attribute:: REQUIREMENT_DESCRIPTION_FOR .. py:attribute:: SPECIFICATION_FOR .. py:attribute:: OTHER .. py:method:: get_json_entry_key() -> str :classmethod: Return JSON entry key for this object. .. py:method:: to_tagvalue() -> str Convert to SPDX tag-value format string. .. py:method:: to_json_dict() -> dict[str, str] Convert to JSON-serializable dictionary format. .. py:method:: from_json_dict(obj: dict[str, Any]) -> RelationshipType :classmethod: Initialize a :class:`RelationshipType` from a :class:`dict`. By default ``RelationshipType.OTHER`` is returned. :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize an :class:`RelationshipType` with. :return: The :class:`RelationshipType` initialized with the value of *obj*. .. py:class:: Relationship(spdx_element_id: SPDXID, relationship_type: RelationshipType, related_spdx_element: SPDXID) Bases: :py:obj:`SPDXEntry` Provides information about the relationship between two SPDX elements. See 11.1 `Relationship field `_. .. py:method:: __str__() -> str Return string representation of relationship. .. py:method:: to_json_dict() -> dict[str, str] Convert to JSON-serializable dictionary format. .. py:method:: from_json_dict(obj: dict[str, Any]) -> Relationship :classmethod: Initialize a :class:`Relationship` from a :class:`dict`. :param obj: A :class:`dict` which key is this class' JSON entry key, and the value, an object to initialize an :class:`Relationship` with. :return: The :class:`Relationship` initialized with the value of *obj*. .. py:class:: Package Bases: :py:obj:`SPDXSection` Describe a package. If the SPDX information describes a package, the following fields shall be included per package. See `7 Package information section `_ :ivar PackageName name: A mandatory single line of text identifying the full name of the package as given by the Package Originator (:class:`PackageOriginator`). :ivar SPDXID spdx_id: Uniquely identify any element in an SPDX document which may be referenced by other elements. These may be referenced internally and externally with the addition of the SPDX document identifier. Generally made of ``f"{name}-{version}"``. :ivar PackageVersion version: Identify the version of the package. :ivar PackageFileName file_name: Provide the actual file name of the package, or path of the directory being treated as a package. This may include the packaging and compression methods used as part of the file name, if appropriate. :ivar list[PackageChecksum] checksum: Provide an independently reproducible mechanism that permits unique identification of a specific package that correlates to the data in this SPDX document. This identifier enables a recipient to determine if any file in the original package has been changed. If the SPDX document is to be included in a package, this value should not be calculated. The SHA1 algorithm shall be used to provide the checksum by default. The only supported checksum algorithms (for now) are :class:`SHA1` and :class:`SHA256`. :ivar PackageSupplier supplier: Identify the actual distribution source for the package/directory identified in the SPDX document. This might or might not be different from the originating distribution source for the package. The name of the Package Supplier shall be an organization or recognized author and not a website. For example, SourceForge is a host website, not a supplier, the supplier for https://sourceforge.net/projects/bridge/ is *The Linux Foundation*. :ivar PackageOriginator originator: If the package identified in the SPDX document originated from a different person or organization than identified as Package Supplier (see *supplier* above), this field identifies from where or whom the package originally came. In some cases, a package may be created and originally distributed by a different third party than the Package Supplier of the package. For example, the SPDX document identifies the package as ``glibc`` and the Package Supplier as *Red Hat*, but the *Free Software Foundation* is the Package Originator. :ivar PackageCopyrightText copyright_text: Identify the copyright holders of the package, as well as any dates present. This will be a free form text field extracted from package information files. :ivar FilesAnalyzed files_analyzed: Indicates whether the file content of this package has been available for or subjected to analysis when creating the SPDX document. If false, indicates packages that represent metadata or URI references to a project, product, artifact, distribution or a component. If ``False``, the package shall not contain any files. :ivar PackageLicenseConcluded license_concluded: Contain the license the SPDX document creator has concluded as governing the package or alternative values, if the governing license cannot be determined. :ivar PackageLicenseComments | None license_comments: This field provides a place for the SPDX document creator to record any relevant background information or analysis that went in to arriving at the Concluded License for a package. If the Concluded License does not match the Declared License or License Information from Files, this should be explained by the SPDX document creator. It is also preferable to include an explanation here when the Concluded License is :attr:`NOASSERTION`. :ivar PackageLicenseDeclared license_declared: List the licenses that have been declared by the authors of the package. Any license information that does not originate from the package authors, e.g. license information from a third-party repository, should not be included in this field. :ivar PrimaryPackagePurposeType | None primary_purpose: Provides information about the primary purpose of the identified package. Package Purpose is intrinsic to how the package is being used rather than the content of the package. :ivar PackageHomePage | None homepage: Provide a place for the SPDX document creator to record a website that serves as the package's home page. This link can also be used to reference further information about the package referenced by the SPDX document creator. :ivar PackageDownloadLocation download_location: This section identifies the download Uniform Resource Locator (URL), or a specific location within a version control system (VCS) for the package at the time that the SPDX document was created. :ivar list[ExternalRef] | None external_refs: An External Reference allows a Package to reference an external source of additional information, metadata, enumerations, asset identifiers, or downloadable content believed to be relevant to the Package. For instance: .. code-block:: python ExternalRef( reference_category=ExternalRefCategory.package_manager, reference_type="purl", reference_locator="pkg:generic/my-dep@1b2" ) :ivar PackageDescription | None description: This field is a more detailed description of the package. It may also be extracted from the packages itself. :ivar PackageComment | None comment: This field provides a place for the SPDX document creator to record any general comments about the package being described. .. py:attribute:: name :type: PackageName .. py:attribute:: spdx_id :type: SPDXID .. py:attribute:: version :type: PackageVersion .. py:attribute:: file_name :type: PackageFileName .. py:attribute:: checksum :type: list[PackageChecksum] .. py:attribute:: supplier :type: PackageSupplier .. py:attribute:: originator :type: PackageOriginator .. py:attribute:: copyright_text :type: PackageCopyrightText | None .. py:attribute:: files_analyzed :type: FilesAnalyzed .. py:attribute:: license_concluded :type: PackageLicenseConcluded .. py:attribute:: license_comments :type: PackageLicenseComments | None .. py:attribute:: license_declared :type: PackageLicenseDeclared | None .. py:attribute:: homepage :type: PackageHomePage | None .. py:attribute:: download_location :type: PackageDownloadLocation .. py:attribute:: external_refs :type: list[ExternalRef] | None .. py:attribute:: comment :type: PackageComment | None .. py:attribute:: primary_purpose :type: PrimaryPackagePurpose | None .. py:attribute:: description :type: PackageDescription | None .. py:method:: from_json_dict(package_dict: dict[str, Any]) -> Package :classmethod: Initialize a :class:`Package` from a :class:`dict`. :param package_dict: A :class:`dict` containing JSON elements to initialize this :class:`Package` with. :return: The :class:`Package` initialized with the values of *obj*. .. py:class:: DocumentInformation Bases: :py:obj:`SPDXSection` Describe the SPDX Document. .. py:attribute:: document_name :type: DocumentName .. py:attribute:: document_namespace :type: DocumentNamespace .. py:attribute:: version :type: SPDXVersion .. py:attribute:: data_license :type: DataLicense .. py:attribute:: spdx_id :type: SPDXID .. py:method:: __post_init__() -> None Initialize document namespace after dataclass initialization. .. py:method:: from_json_dict(obj: dict[str, Any]) -> DocumentInformation :classmethod: Initialize a :class:`DocumentInformation` from a :class:`dict`. :param obj: A :class:`dict` containing JSON elements to initialize this :class:`DocumentInformation` with. :return: The :class:`DocumentInformation` initialized with the values of *obj*. .. py:class:: CreationInformation Bases: :py:obj:`SPDXSection` Document where and by whom the SPDX document has been created. .. py:attribute:: creators :type: list[Creator] .. py:attribute:: created_now :type: Created .. py:attribute:: license_list_version :type: LicenseListVersion .. py:method:: __post_init__() -> None Initialize creation timestamp after dataclass initialization. .. py:method:: from_json_dict(obj: dict[str, Any]) -> CreationInformation :classmethod: Initialize a :class:`CreationInformation` from a :class:`dict`. :param obj: A :class:`dict` containing JSON elements to initialize this :class:`CreationInformation` with. :return: The :class:`CreationInformation` initialized with the values of *obj*. .. py:class:: Document(document_name: str, creators: list[Entity]) Describe the SPDX Document. .. py:property:: spdx_id :type: SPDXID Return the Document SPDXID. .. py:method:: add_package(package: Package, is_main_package: bool = False, add_relationship: bool = True) -> SPDXID Add a new Package and describe its relationship to other elements. :param package: An already created :class:`Package` to be added to this SPDX document :param is_main_package: whether the package is the main package, in which case a relationship will automatically be added to record that the document DESCRIBES this package. If false, it is assumed that the package is contained by the main package unless a relationship is explicitely passed :param add_relationship: whether to automatically add a relationship element - either (DOCUMENT DESCRIBES
) if is_main_package is True or (
CONTAINS ) :return: the package SPDX_ID .. py:method:: add_relationship(relationship: Relationship) -> None Add a new relationship to the document. :param relationship: the Relationship to add .. py:method:: to_tagvalue() -> list[str] Generate a list of tag:value lines describing the SPDX document. .. py:method:: to_json_dict() -> dict[str, Any] Generate a representation of an SPDX following the JSON schema. Generate a dictionary that can be dumped into a JSON. .. py:method:: from_json_dict(doc_dict: dict[str, Any]) -> Document :classmethod: Create a :class:`Document` out of a JSON :class:`dict`. This may be used when initializing a :class:`Document` from an SPDX JSON file, or to duplicate a :class:`Document`. For instance: >>> import json >>> from pathlib import Path >>> with Path("my.spdx.json").open( ... encoding="utf-8", errors="replace" ... ) as spdx_handle: >>> spdx_dict = json.load(spdx_handle) >>> spdx_doc: Document = Document.from_json_dict(spdx_dict) >>> spdx_doc2: Document = Document.from_json_dict(spdx_doc.to_json_dict()) :param doc_dict: The :class:`dict` containing JSON values to initialize this :class:`Document` with. :returns: A new :class:`Document` initialized with the JSON values of *doc_dict*.