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



Attributes
----------

.. autoapisummary::

   spdx.NOASSERTION
   spdx.NONE_VALUE
   spdx.MAYBE_STR
   spdx.SPDXID_R
   spdx.SECURITY
   spdx.PACKAGE_MANAGER
   spdx.PERSISTENT_ID
   spdx.OTHER
   spdx.SPDX_EXTERNAL_REF_TYPES


Exceptions
----------

.. autoapisummary::

   spdx.InvalidSPDX


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.PackageLicenseConcluded
   spdx.PackageLicenseDeclared
   spdx.PackageLicenseComments
   spdx.PackageCopyrightText
   spdx.PackageComment
   spdx.ExternalRefCategory
   spdx.ExternalRef
   spdx.RelationshipType
   spdx.Relationship
   spdx.Package
   spdx.DocumentInformation
   spdx.CreationInformation
   spdx.Document


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

.. 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:exception:: InvalidSPDX

   Bases: :py:obj:`Exception`


   Raise an exception when the SPDX document cannot be generated.


.. 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:: __str__() -> str
      :abstractmethod:



   .. py:method:: __format__(format_spec: str) -> str


   .. 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:attribute:: value


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


   .. py:method:: __gt__(other: object) -> bool


   .. py:method:: to_json_dict() -> dict[str, Any]

      Return a chunk of the SPDX JSON document.



.. py:class:: SPDXEntryMaybeStr(value: MAYBE_STR)

   Bases: :py:obj:`SPDXEntry`


   Describe an SPDX Entry accepting a string, NOASSERTION, or NONE.


   .. py:attribute:: value


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


   .. py:method:: to_json_dict() -> dict[str, Any]

      Return a chunk of the SPDX JSON document.



.. py:class:: SPDXEntryMaybeStrMultilines(value: MAYBE_STR)

   Bases: :py:obj:`SPDXEntryMaybeStr`


   Describe an SPDX Entry accepting a string, NOASSERTION, or NONE.


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

      Return the content that can span to multiple lines.

      In tag:value format multiple lines are delimited by <text>...</text>.



.. py:class:: SPDXEntryBool(value: bool)

   Bases: :py:obj:`SPDXEntry`


   Describe an SPDX Entry accepting a boolean.


   .. py:attribute:: value
      :type:  bool


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


   .. py:method:: to_json_dict() -> dict[str, Any]

      Return a chunk of the SPDX JSON document.



.. 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]


.. py:class:: SPDXVersion(value: str)

   Bases: :py:obj:`SPDXEntryStr`


   Provide the SPDX version used to generate the document.

   See 6.1 `SPDX version field
   <https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#61-spdx-version-field>`_.


   .. py:attribute:: json_entry_key
      :value: 'spdxVersion'


      Name of the SPDXEntry as visible in the SPDX JSON report.



.. py:class:: DataLicense(value: str)

   Bases: :py:obj:`SPDXEntryStr`


   License of the SPDX Metadata.

   See 6.2 `Data license field
   <https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#62-data-license-field>`_.


.. py:class:: SPDXID(value: str)

   Bases: :py:obj:`SPDXEntryStr`


   Identify an SPDX Document, or Package.

   See 6.3 `SPDX identifier field
   <https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#63-spdx-identifier-field>`_
   and 7.2 `Package SPDX identifier field
   <https://spdx.github.io/spdx-spec/v2.3/package-information/#72-package-spdx-identifier-field>`_.

   The value is a unique string containing letters, numbers, ., and/or -.


   .. py:attribute:: json_entry_key
      :value: 'SPDXID'


      Name of the SPDXEntry as visible in the SPDX JSON report.



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


   .. py:method:: __eq__(o: object) -> bool


   .. py:method:: __hash__() -> int


.. py:class:: DocumentName(value: str)

   Bases: :py:obj:`SPDXEntryStr`


   Identify name of this document.

   See 6.4 `Document name field
   <https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#64-document-name-field>`_.


   .. py:attribute:: json_entry_key
      :value: 'name'


      Name of the SPDXEntry as visible in the SPDX JSON report.



.. py:class:: DocumentNamespace(value: str)

   Bases: :py:obj:`SPDXEntryStr`


   Provide a unique URI for this document.

   See 6.5 `SPDX document namespace field
   <https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#65-spdx-document-namespace-field>`_.


.. 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
   <https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#67-license-list-version-field>`_.


.. py:class:: Entity(value: str)

   Bases: :py:obj:`SPDXEntryStr`


   Represent an Entity (Organization, Person, Tool).


.. py:class:: EntityRef(value: Entity | Literal['NOASSERTION'])

   Bases: :py:obj:`SPDXEntry`


   Reference an Entity.

   Accept NOASSERTION as a valid value.


   .. py:attribute:: value


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


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

      Return a valid tag:value line.



   .. py:method:: to_json_dict() -> dict[str, Any]

      Return a chunk of the SPDX JSON document.



.. 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
   <https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#68-creator-field>`_.


   .. py:attribute:: json_entry_key
      :value: 'creators'


      Name of the SPDXEntry as visible in the SPDX JSON report.



.. py:class:: Created(value: str)

   Bases: :py:obj:`SPDXEntryStr`


   Identify when the SPDX document was originally created.

   See 6.9 `Created field
   <https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#69-created-field>`_.


.. 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
   <https://spdx.github.io/spdx-spec/v2.3/package-information/#71-package-name-field>`_


   .. py:attribute:: json_entry_key
      :value: 'name'


      Name of the SPDXEntry as visible in the SPDX JSON report.



.. py:class:: PackageVersion(value: str)

   Bases: :py:obj:`SPDXEntryStr`


   Identify the version of the package.

   See 7.3 `Package version field
   <https://spdx.github.io/spdx-spec/v2.3/package-information/#73-package-version-field>`_


   .. py:attribute:: json_entry_key
      :value: 'versionInfo'


      Name of the SPDXEntry as visible in the SPDX JSON report.



.. py:class:: PackageFileName(value: str)

   Bases: :py:obj:`SPDXEntryStr`


   Provide the actual file name of the package.

   See 7.4 `Package file name field
   <https://spdx.github.io/spdx-spec/v2.3/package-information/#74-package-file-name-field>`_


.. 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
   <https://spdx.github.io/spdx-spec/v2.3/package-information/#75-package-supplier-field>`_


   .. py:attribute:: json_entry_key
      :value: 'supplier'


      Name of the SPDXEntry as visible in the SPDX JSON report.



.. py:class:: PackageOriginator(value: Entity | Literal['NOASSERTION'])

   Bases: :py:obj:`EntityRef`


   Identify from where the package originally came.

   See 7.6 `Package originator field
   <https://spdx.github.io/spdx-spec/v2.3/package-information/#76-package-originator-field>`_


   .. py:attribute:: json_entry_key
      :value: 'originator'


      Name of the SPDXEntry as visible in the SPDX JSON report.



.. py:class:: PackageDownloadLocation(value: MAYBE_STR)

   Bases: :py:obj:`SPDXEntryMaybeStr`


   Identifies the download location of the package.

   See 7.7 `Package download location field
   <https://spdx.github.io/spdx-spec/v2.3/package-information/#77-package-download-location-field>`_


   .. py:attribute:: json_entry_key
      :value: 'downloadLocation'


      Name of the SPDXEntry as visible in the SPDX JSON report.



.. 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
   <https://spdx.github.io/spdx-spec/v2.3/package-information/#78-files-analyzed-field>`_


.. 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
   <https://spdx.github.io/spdx-spec/v2.3/package-information/#710-package-checksum-field>`_


   .. py:attribute:: entry_key
      :value: 'PackageChecksum'


      Name of the SPDXEntry as visible in the SPDX tag:value report.



   .. py:attribute:: json_entry_key
      :value: 'checksums'


      Name of the SPDXEntry as visible in the SPDX JSON report.



   .. py:property:: algorithm
      :type: str

      :abstractmethod:



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


   .. py:method:: to_json_dict() -> dict[str, dict[str, str]]

      Return a chunk of the SPDX JSON document.



.. py:class:: PackageHomePage(value: MAYBE_STR)

   Bases: :py:obj:`SPDXEntryMaybeStr`


   Identifies the homepage location of the package.

   See 7.11 `Package home page field
   <https://spdx.github.io/spdx-spec/v2.3/package-information/#711-package-home-page-field>`_


   .. py:attribute:: json_entry_key
      :value: 'homepage'


      Name of the SPDXEntry as visible in the SPDX JSON report.



.. py:class:: SHA1(value: str)

   Bases: :py:obj:`PackageChecksum`


   Provide a mechanism that permits unique identification of the package.

   See 7.10 `Package checksum field
   <https://spdx.github.io/spdx-spec/v2.3/package-information/#710-package-checksum-field>`_


   .. py:attribute:: algorithm
      :value: 'SHA1'



.. py:class:: SHA256(value: str)

   Bases: :py:obj:`PackageChecksum`


   Provide a mechanism that permits unique identification of the package.

   See 7.10 `Package checksum field
   <https://spdx.github.io/spdx-spec/v2.3/package-information/#710-package-checksum-field>`_


   .. py:attribute:: algorithm
      :value: 'SHA256'



.. py:class:: PackageLicenseConcluded(value: MAYBE_STR)

   Bases: :py:obj:`SPDXEntryMaybeStr`


   Contain the license concluded as governing the package.

   See 7.13 `Concluded license field
   <https://spdx.github.io/spdx-spec/v2.3/package-information/#713-concluded-license-field>`_


   .. py:attribute:: json_entry_key
      :value: 'licenseConcluded'


      Name of the SPDXEntry as visible in the SPDX JSON report.



.. 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
   <https://spdx.github.io/spdx-spec/v2.3/package-information/#715-declared-license-field>`_


   .. py:attribute:: json_entry_key
      :value: 'licenseDeclared'


      Name of the SPDXEntry as visible in the SPDX JSON report.



.. 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
   <https://spdx.github.io/spdx-spec/v2.3/package-information/#716-comments-on-license-field>`_


   .. py:attribute:: json_entry_key
      :value: 'licenseComments'


      Name of the SPDXEntry as visible in the SPDX JSON report.



.. py:class:: PackageCopyrightText(value: MAYBE_STR)

   Bases: :py:obj:`SPDXEntryMaybeStrMultilines`


   Identify the copyright holders of the package.

   See 7.17 `Copyright text field
   <https://spdx.github.io/spdx-spec/v2.3/package-information/#717-copyright-text-field>`_


   .. py:attribute:: json_entry_key
      :value: 'copyrightText'


      Name of the SPDXEntry as visible in the SPDX JSON report.



.. 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
   <https://spdx.github.io/spdx-spec/v2.3/package-information/#720-package-comment-field>`_


   .. py:attribute:: json_entry_key
      :value: 'comment'


      Name of the SPDXEntry as visible in the SPDX JSON report.



.. 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

.. 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
   <https://spdx.github.io/spdx-spec/v2.3/package-information/#721-external-reference-field>`_


   .. py:attribute:: json_entry_key
      :value: 'externalRefs'


      Name of the SPDXEntry as visible in the SPDX JSON report.



   .. py:attribute:: reference_category


   .. py:attribute:: reference_type


   .. py:attribute:: reference_locator


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


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


      Generate an External Ref from a dict compatible with the JSON format.

      :param external_ref_dict: a dict with the referenceCategory, referenceType,
          and referenceLocator keys
      :return: a new ExternalRef instance



.. 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: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
   <https://spdx.github.io/spdx-spec/v2.3/relationships-between-SPDX-elements/#111-relationship-field>`_.


   .. py:attribute:: spdx_element_id


   .. py:attribute:: relationship_type


   .. py:attribute:: related_spdx_element


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


   .. py:method:: to_json_dict() -> dict[str, str]

      Return a chunk of the SPDX JSON document.



.. 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
   <https://spdx.github.io/spdx-spec/v2.3/package-information/>`_

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


   .. 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
      :value: None



.. 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


.. 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


.. py:class:: Document(document_name: str, creators: list[Entity])

   Describe the SPDX Document.


   .. py:attribute:: doc_info


   .. py:attribute:: creation_info


   .. py:attribute:: packages
      :type:  dict[SPDXID, Package]


   .. py:attribute:: relationships
      :type:  list[Relationship]
      :value: []



   .. py:attribute:: main_package_spdx_id
      :type:  SPDXID | None
      :value: None



   .. 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 <main package>) if is_main_package
          is True or (<main package> CONTAINS <package>)

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



