spdx-tools Python Library

This example demonstrates how to load a document, modify its metadata, add a file and a relationship, validate the changes, and save the result.

import logging
from license_expression import get_spdx_licensing
from spdx_tools.spdx.model import (Checksum, ChecksumAlgorithm, File,
                                   FileType, Relationship, RelationshipType)
from spdx_tools.spdx.parser.parse_anything import parse_file
from spdx_tools.spdx.validation.document_validator import validate_full_spdx_document
from spdx_tools.spdx.writer.write_anything import write_file

# read in an SPDX document from a file
document = parse_file("spdx_document.json")

# change the document's name
document.creation_info.name = "new document name"

# define a file and a DESCRIBES relationship between the file and the document
checksum = Checksum(ChecksumAlgorithm.SHA1, "71c4025dd9897b364f3ebbb42c484ff43d00791c")

file = File(name="./fileName.py", spdx_id="SPDXRef-File", checksums=[checksum],
            file_types=[FileType.TEXT],
            license_concluded=get_spdx_licensing().parse("MIT and GPL-2.0"),
            license_comment="licenseComment", copyright_text="copyrightText")

relationship = Relationship("SPDXRef-DOCUMENT", RelationshipType.DESCRIBES, "SPDXRef-File")

# add the file and the relationship to the document
# (note that we do not use "document.files.append(file)" as that would circumvent the type checking)
document.files = document.files + [file]
document.relationships = document.relationships + [relationship]

# validate the edited document and log the validation messages
validation_messages = validate_full_spdx_document(document)
for validation_message in validation_messages:
    logging.warning(validation_message.validation_message)

# if there are no validation messages, the document is valid
if not validation_messages:
    write_file(document, "new_spdx_document.rdf", validate=False)

Use the following functions from the spdx_tools library to manipulate SPDX documents programmatically.

Parsing

Use parse_file(file_name) from spdx_tools.spdx.parser.parse_anything. It returns a Document instance or raises SPDXParsingError if the file is invalid.

Validating

Use validate_full_spdx_document(document) from spdx_tools.spdx.validation.document_validator. It returns a list of ValidationMessage objects containing error descriptions and ValidationContext.

Writing

Use write_file(document, file_name) from spdx_tools.spdx.writer.write_anything. The format is determined by the filename extension. Validation is performed by default before writing. To skip validation, use write_file(document, file_name, validate=False).

from spdx_tools.spdx.parser.parse_anything import parse_file
from spdx_tools.spdx.validation.document_validator import validate_full_spdx_document
from spdx_tools.spdx.writer.write_anything import write_file

document = parse_file("document.json")
errors = validate_full_spdx_document(document)
if not errors:
    write_file(document, "document.rdf")

The pyspdxtools command-line interface allows you to interact with SPDX files. The input and output formats are automatically inferred from the file extensions (e.g., .json, .tag, .rdf, .yaml, .xml).

Parsing and Validating

To parse and validate a file: pyspdxtools -i <filename>

Converting Formats

To convert a file from one format to another: pyspdxtools -i <input_file> -o <output_file>

To skip the validation process during conversion (use with caution): pyspdxtools -i <input_file> -o <output_file> --novalidation

Generating Graphs (Optional)

If networkx and pygraphviz are installed, you can generate a visual graph of the document structure: pyspdxtools -i <input_file> --graph -o <output_file> (The <output_file> should have a valid extension for pygraphviz, such as .png).

pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json -o output.tag
pyspdxtools -i tests/spdx/data/SPDXJSONExample-v2.3.spdx.json --graph -o SPDXJSONExample-v2.3.spdx.png

The Actor class is used to represent entities involved in an SPDX document, such as people, organizations, or tools. It includes the entity's type, name, and an optional email address.

ActorType

An actor must be assigned one of the following ActorType values:

• PERSON
• ORGANIZATION
• TOOL

Serialization

Calling to_serialized_string() or using str() on an Actor instance returns a formatted string representation used across all SPDX serialization formats. The format is: {ActorType.name.title()}: {name} ({email}) (where the email part is omitted if not provided).

from spdx_tools.spdx.model.actor import Actor, ActorType

# Create a Person actor
person = Actor(actor_type=ActorType.PERSON, name="Jane Doe", email="jane@example.com")
print(person.to_serialized_string())
# Output: Person: Jane Doe (jane@example.com)

# Create an Organization actor without an email
org = Actor(actor_type=ActorType.ORGANIZATION, name="Acme Corp")
print(org)
# Output: Organization: Acme Corp

Use validate_spdx_id() to verify that an SPDX ID is syntactically correct and, optionally, exists within a specific Document.

An SPDX ID can be a simple internal ID (e.g., SPDXRef-example) or a reference to an external document using a colon separator (e.g., DocumentRef-external:SPDXRef-internal).

Parameters:

• spdx_id (str): The ID to validate.
• document (Document): The SPDX document to check against.
• check_document (bool): If True, verifies if the ID exists anywhere in the document. Defaults to False.
• check_files (bool): If True, verifies if the ID exists specifically within the document's files. Defaults to False.

Returns: A List[str] containing validation error messages. An empty list indicates the ID is valid.

from spdx_tools.spdx.validation.spdx_id_validators import validate_spdx_id

# Example: Validating an internal ID exists in the document
errors = validate_spdx_id("SPDXRef-File-1", document, check_document=True)
if not errors:
    print("ID is valid and present")
else:
    print(f"Validation errors: {errors}")