tessl/pypi-spdx-tools

Python library to parse, validate and create SPDX documents

—

Pending

Overview

Eval results

Files

SPDX 3.0 Support

Name: tessl/pypi-spdx-tools
Author: tessl

Experimental support for the upcoming SPDX 3.0 specification including new data models, profile support, and enhanced capabilities. This functionality is under active development and subject to change.

Capabilities

SPDX 3.0 Document Structure

New document model for SPDX 3.0 with enhanced element-based architecture.

class SpdxDocument:
    """
    SPDX 3.0 document root.
    
    Represents the main container for SPDX 3.0 elements with
    creation information and element collections.
    """
    creation_info: CreationInfo
    elements: List[Element]

class CreationInfo:
    """
    SPDX 3.0 document creation information.
    
    Enhanced creation info with additional metadata support
    and profile identification.
    """
    spec_version: str                           # SPDX 3.0 specification version
    spdx_id: str                               # Document SPDX identifier  
    name: str                                  # Document name
    document_namespace: str                    # Unique document namespace
    creators: List[Agent]                      # Document creators (enhanced)
    created: datetime                          # Creation timestamp
    profile: List[ProfileIdentifierType]      # Supported profiles
    data_license: str                          # Data license
    imports: List[str] = []                    # Imported namespace URIs
    extension_map: List[NamespaceMap] = []     # Extension mappings
    external_map: List[ExternalMap] = []       # External references
    verify_using: List[IntegrityMethod] = []   # Verification methods

Base Element Model

Foundation classes for all SPDX 3.0 elements.

class Element:
    """
    Base class for all SPDX 3.0 elements.
    
    Provides common properties for packages, files, and other
    SPDX elements in the 3.0 specification.
    """
    spdx_id: str                               # Element SPDX identifier
    name: Optional[str] = None                 # Element name
    summary: Optional[str] = None              # Element summary
    description: Optional[str] = None          # Element description
    comment: Optional[str] = None              # Element comment
    verification_info: List[IntegrityMethod] = []  # Verification methods
    external_references: List[ExternalReference] = []  # External references
    external_identifiers: List[ExternalIdentifier] = []  # External identifiers
    extension_map: List[NamespaceMap] = []     # Extension mappings

class Artifact(Element):
    """
    Base class for artifacts (files, packages, etc.).
    
    Represents downloadable or distributable software artifacts
    with integrity and origin information.
    """
    originated_by: List[Agent] = []            # Artifact originators
    supplied_by: List[Agent] = []              # Artifact suppliers
    built_time: Optional[datetime] = None      # Build timestamp
    release_time: Optional[datetime] = None    # Release timestamp  
    valid_until_time: Optional[datetime] = None  # Validity period

Agent System

Enhanced agent/actor model for SPDX 3.0.

class Agent(Element):
    """Base agent/actor class for SPDX 3.0."""
    pass

class Person(Agent):
    """
    Person agent representing an individual.
    
    Represents a human individual involved in software
    development or distribution.
    """
    pass

class Organization(Agent):
    """
    Organization agent representing a company or group.
    
    Represents an organizational entity involved in software
    development or distribution.
    """
    pass

class SoftwareAgent(Agent):
    """
    Software agent representing automated systems.
    
    Represents software systems, scripts, or automated
    processes involved in software creation.
    """
    pass

class Tool(SoftwareAgent):
    """
    Tool agent representing development/build tools.
    
    Represents specific tools used in software development,
    building, or analysis processes.
    """
    pass

Collections and Bundles

Organizational structures for grouping SPDX 3.0 elements.

class ElementCollection(Element):
    """
    Collection of SPDX elements.
    
    Provides grouping mechanism for organizing related
    SPDX elements together.
    """
    elements: List[str] = []                   # Element SPDX IDs in collection
    root_elements: List[str] = []              # Root element SPDX IDs

class Bundle(ElementCollection):
    """
    Bundle of related SPDX elements.
    
    Represents a logical grouping of elements that
    are distributed or processed together.
    """
    pass

class Bom(ElementCollection):
    """
    Bill of Materials (BOM).
    
    Represents a structured inventory of software
    components and their relationships.
    """
    pass

Relationships and Annotations

Enhanced relationship and annotation system for SPDX 3.0.

class Relationship(Element):
    """
    Relationship between SPDX 3.0 elements.
    
    Enhanced relationship model with lifecycle scoping
    and improved semantics.
    """
    from_element: str                          # Source element SPDX ID
    relationship_type: RelationshipType        # Type of relationship
    to_elements: List[str] = []                # Target element SPDX IDs
    completeness: Optional[RelationshipCompleteness] = None  # Completeness indicator

class LifecycleScopedRelationship(Relationship):
    """
    Lifecycle-scoped relationship.
    
    Represents relationships that are valid only during
    specific lifecycle phases.
    """
    scope: Optional[LifecycleScopeType] = None  # Lifecycle scope

class Annotation(Element):
    """
    Annotation on SPDX 3.0 elements.
    
    Enhanced annotation system with improved
    metadata and categorization.
    """
    subject: str                               # Annotated element SPDX ID
    annotation_type: AnnotationType            # Annotation type
    annotator: Agent                           # Annotation creator
    annotation_date: datetime                  # Annotation timestamp
    statement: str                             # Annotation content

Profile-Specific Models

Specialized models for different SPDX 3.0 profiles.

# Software Profile
class SoftwareArtifact(Artifact):
    """Software artifact in software profile."""
    pass

class Package(SoftwareArtifact):
    """Software package with enhanced metadata."""
    package_url: Optional[str] = None          # Package URL (purl)
    download_location: Optional[str] = None    # Download location
    files_analyzed: Optional[bool] = None      # Whether files were analyzed
    package_verification_code: Optional[str] = None  # Verification code

class File(SoftwareArtifact):
    """Software file with enhanced metadata."""
    content_type: Optional[str] = None         # MIME content type

class Directory(SoftwareArtifact):
    """Directory containing software files."""
    pass

class Snippet(SoftwareArtifact):
    """Code snippet within a file."""
    byte_range: Optional[Range] = None         # Byte range in file
    line_range: Optional[Range] = None         # Line range in file

# AI Profile  
class AIPackage(Package):
    """AI/ML package with specialized metadata."""
    pass

# Build Profile
class Build(Element):
    """Build process information."""
    pass

# Dataset Profile
class Dataset(Element):
    """Dataset information for data packages."""
    pass

# Licensing Profile
class LicenseExpression(Element):
    """License expression evaluation."""
    pass

class License(Element):
    """License information."""
    pass

class LicenseAddition(Element):
    """License exception or addition."""
    pass

class CustomLicense(License):
    """Custom license not in SPDX list."""
    pass

class CustomLicenseAddition(LicenseAddition):
    """Custom license addition."""
    pass

Security Profile

Security-related models for vulnerability assessment.

class VulnAssessmentRelationship(Relationship):
    """Base vulnerability assessment relationship."""
    assessed_element: str                      # Element being assessed
    supplier: Optional[Agent] = None           # Assessment supplier
    published_time: Optional[datetime] = None  # Publication timestamp

class VexAffectedVulnAssessmentRelationship(VulnAssessmentRelationship):
    """VEX affected vulnerability assessment."""
    action_statement: Optional[str] = None     # Recommended action
    action_statement_time: Optional[datetime] = None  # Action timestamp
    justification_type: Optional[str] = None   # Justification type
    impact_statement: Optional[str] = None     # Impact description
    impact_statement_time: Optional[datetime] = None  # Impact timestamp

class VexFixedVulnAssessmentRelationship(VulnAssessmentRelationship):  
    """VEX fixed vulnerability assessment."""
    pass

class VexNotAffectedVulnAssessmentRelationship(VulnAssessmentRelationship):
    """VEX not affected vulnerability assessment."""
    impact_statement: Optional[str] = None     # Impact description
    impact_statement_time: Optional[datetime] = None  # Impact timestamp
    justification_type: Optional[str] = None   # Justification type

class VexUnderInvestigationVulnAssessmentRelationship(VulnAssessmentRelationship):
    """VEX under investigation vulnerability assessment."""
    pass

Supporting Types

Enhanced supporting types for SPDX 3.0.

class Hash(IntegrityMethod):
    """
    Cryptographic hash for integrity verification.
    
    Enhanced hash support with additional algorithms
    and metadata.
    """
    algorithm: HashAlgorithm                   # Hash algorithm
    hash_value: str                           # Hash value

class ExternalReference:
    """
    Reference to external resource.
    
    Enhanced external reference system with
    categorization and verification.
    """
    external_reference_type: ExternalReferenceType  # Reference type
    locator: str                              # Resource locator
    content_type: Optional[str] = None        # MIME content type
    comment: Optional[str] = None             # Reference comment

class ExternalIdentifier:
    """
    External identifier for elements.
    
    Links SPDX elements to external identification
    systems and registries.
    """
    external_identifier_type: ExternalIdentifierType  # Identifier type
    identifier: str                           # Identifier value
    issuing_authority: Optional[str] = None   # Authority that issued ID
    comment: Optional[str] = None             # Identifier comment

class ExternalMap:
    """External namespace mapping."""
    external_spdx_id: str                     # External SPDX ID
    verification_info: IntegrityMethod        # Verification method

class NamespaceMap:
    """Namespace mapping for extensions."""
    prefix: str                               # Namespace prefix
    namespace: str                            # Namespace URI

CLI Tools

Command-line interface for SPDX 3.0 operations.

def main() -> None:
    """
    CLI entry point for pyspdxtools3 command.
    
    Experimental CLI for SPDX 3.0 document processing.
    Provides parsing, validation, and conversion capabilities
    for SPDX 3.0 documents.
    
    Note: API and functionality subject to change as
    SPDX 3.0 specification evolves.
    """

Enumerations

SPDX 3.0 Specific Enums

class ProfileIdentifierType(Enum):
    """SPDX 3.0 profile identifiers."""
    CORE = "core"
    SOFTWARE = "software"
    AI = "ai"
    BUILD = "build"
    DATASET = "dataset"
    LICENSING = "licensing"
    SECURITY = "security"

class HashAlgorithm(Enum):
    """Hash algorithms for SPDX 3.0."""
    SHA1 = "sha1"
    SHA224 = "sha224"
    SHA256 = "sha256"
    SHA384 = "sha384"
    SHA512 = "sha512"
    SHA3_256 = "sha3-256"
    SHA3_384 = "sha3-384"
    SHA3_512 = "sha3-512"
    BLAKE2B_256 = "blake2b-256"
    BLAKE2B_384 = "blake2b-384"
    BLAKE2B_512 = "blake2b-512"
    BLAKE3 = "blake3"
    MD5 = "md5"

class ExternalReferenceType(Enum):
    """Types of external references."""
    WEBSITE = "website"
    VCS = "vcs"
    DOWNLOAD = "download"
    ISSUE_TRACKER = "issueTracker"
    MAILING_LIST = "mailingList"
    SOCIAL = "social"
    CHAT = "chat"
    DOCUMENTATION = "documentation"
    SUPPORT = "support"
    DISTRIBUTION = "distribution"
    SECURITY = "security"
    OTHER = "other"

class ExternalIdentifierType(Enum):
    """Types of external identifiers."""
    CPE22 = "cpe22"
    CPE23 = "cpe23"
    CVE = "cve"
    SWID = "swid"
    PURL = "purl"
    GITOID = "gitoid"
    OTHER = "other"

class RelationshipCompleteness(Enum):
    """Completeness of relationships."""
    COMPLETE = "complete"
    INCOMPLETE = "incomplete"
    NO_ASSERTION = "noAssertion"

class LifecycleScopeType(Enum):
    """Lifecycle scope types."""
    DESIGN = "design"
    BUILD = "build"
    TEST = "test"
    RUNTIME = "runtime"
    OTHER = "other"

Usage Examples

Creating SPDX 3.0 Documents

from datetime import datetime
from spdx_tools.spdx3.model import (
    SpdxDocument, CreationInfo, Package, Person, Hash, HashAlgorithm,
    ProfileIdentifierType
)

# Create SPDX 3.0 document
creation_info = CreationInfo(
    spec_version="3.0",
    spdx_id="https://example.com/doc#",
    name="Example SPDX 3.0 Document",
    document_namespace="https://example.com/doc",
    creators=[Person(spdx_id="https://example.com/person#alice", name="Alice")],
    created=datetime.now(),
    profile=[ProfileIdentifierType.CORE, ProfileIdentifierType.SOFTWARE]
)

# Create software package
package = Package(
    spdx_id="https://example.com/package#main",
    name="example-package",
    download_location="https://github.com/example/package"
)

# Create document
document = SpdxDocument(
    creation_info=creation_info,
    elements=[package]
)

Working with Profiles

# Check document profiles
if ProfileIdentifierType.SOFTWARE in document.creation_info.profile:
    print("Document supports software profile")

if ProfileIdentifierType.SECURITY in document.creation_info.profile:
    print("Document supports security profile")

Enhanced Relationships

from spdx_tools.spdx3.model import LifecycleScopedRelationship, LifecycleScopeType

# Create lifecycle-scoped relationship
relationship = LifecycleScopedRelationship(
    spdx_id="https://example.com/rel#1",
    from_element="https://example.com/package#main",
    relationship_type=RelationshipType.DEPENDS_ON,
    to_elements=["https://example.com/package#dep"],
    scope=LifecycleScopeType.BUILD
)

Migration Notes

Key differences when migrating from SPDX 2.x to 3.0:

Element-based architecture: All components are now Elements with SPDX IDs
Profile system: Documents can support multiple profiles (software, AI, security, etc.)
Enhanced agents: More sophisticated agent/actor model
Improved relationships: Lifecycle scoping and completeness indicators
Namespace changes: URIs instead of simple SPDX IDs
Extended metadata: More comprehensive metadata support

Note: SPDX 3.0 support is experimental and subject to change as the specification evolves.

Install with Tessl CLI