0
# SPDX Tools
1
2
A comprehensive Python library for working with SPDX (Software Package Data Exchange) documents. Enables parsing, validation, creation, and conversion of SPDX files across multiple formats including Tag/Value, RDF, JSON, YAML, and XML. Provides full validation capabilities for SPDX document versions 2.2 and 2.3 against the official specification, includes command-line tools for file processing, and offers experimental support for the upcoming SPDX v3.0 specification.
3
4
## Package Information
5
6
- **Package Name**: spdx-tools
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install spdx-tools`
10
11
## Core Imports
12
13
```python
14
import spdx_tools
15
```
16
17
For parsing and writing documents:
18
19
```python
20
from spdx_tools.spdx.parser.parse_anything import parse_file
21
from spdx_tools.spdx.writer.write_anything import write_file
22
```
23
24
For working with data models:
25
26
```python
27
from spdx_tools.spdx.model import Document, Package, File, Relationship
28
```
29
30
For validation:
31
32
```python
33
from spdx_tools.spdx.validation.document_validator import validate_full_spdx_document
34
```
35
36
## Basic Usage
37
38
```python
39
from spdx_tools.spdx.parser.parse_anything import parse_file
40
from spdx_tools.spdx.writer.write_anything import write_file
41
from spdx_tools.spdx.validation.document_validator import validate_full_spdx_document
42
43
# Parse an SPDX document from any supported format
44
document = parse_file("input.spdx")
45
46
# Validate the document
47
validation_messages = validate_full_spdx_document(document)
48
if validation_messages:
49
for message in validation_messages:
50
print(f"Validation error: {message.validation_message}")
51
else:
52
print("Document is valid")
53
54
# Convert to different format
55
write_file(document, "output.json") # Converts to JSON
56
57
# Access document components
58
print(f"Document name: {document.creation_info.name}")
59
print(f"Number of packages: {len(document.packages)}")
60
print(f"Number of files: {len(document.files)}")
61
```
62
63
## Architecture
64
65
SPDX Tools is organized around core concepts:
66
67
- **Document Model**: Comprehensive data structures reflecting the SPDX specification
68
- **Parser Framework**: Format-agnostic parsing with format-specific implementations
69
- **Writer Framework**: Format-agnostic writing with format-specific implementations
70
- **Validation Engine**: Comprehensive validation against SPDX specification rules
71
- **CLI Tools**: Command-line interfaces for common operations
72
73
The library supports SPDX specification versions 2.2 and 2.3, with experimental support for the upcoming SPDX 3.0 specification. All major SPDX serialization formats are supported: Tag/Value, RDF/XML, JSON, YAML, and XML.
74
75
## Capabilities
76
77
### Document Parsing
78
79
Parse SPDX documents from files in any supported format with automatic format detection based on file extension.
80
81
```python { .api }
82
def parse_file(file_name: str, encoding: str = "utf-8") -> Document:
83
"""
84
Parse SPDX file in any supported format.
85
86
Args:
87
file_name: Path to SPDX file (.spdx, .json, .yaml, .xml, .rdf)
88
encoding: File encoding (default: utf-8)
89
90
Returns:
91
Document: Parsed SPDX document object
92
93
Raises:
94
SPDXParsingError: If parsing fails
95
"""
96
```
97
98
[Document Parsing](./parsing.md)
99
100
### Document Writing
101
102
Write SPDX documents to files in any supported format with automatic format detection and optional validation.
103
104
```python { .api }
105
def write_file(document: Document, file_name: str, validate: bool = True) -> None:
106
"""
107
Write SPDX document to file in any supported format.
108
109
Args:
110
document: SPDX document to write
111
file_name: Output file path (format determined by extension)
112
validate: Whether to validate document before writing
113
"""
114
```
115
116
[Document Writing](./writing.md)
117
118
### Document Validation
119
120
Comprehensive validation of SPDX documents against the official specification with detailed error reporting.
121
122
```python { .api }
123
def validate_full_spdx_document(document: Document, spdx_version: str = None) -> List[ValidationMessage]:
124
"""
125
Validate complete SPDX document against specification.
126
127
Args:
128
document: SPDX document to validate
129
spdx_version: SPDX version to validate against ("SPDX-2.2" or "SPDX-2.3")
130
131
Returns:
132
List of validation messages (empty if valid)
133
"""
134
```
135
136
[Document Validation](./validation.md)
137
138
### Data Models
139
140
Complete object model representing all SPDX specification elements including documents, packages, files, relationships, and metadata.
141
142
```python { .api }
143
class Document:
144
"""Main SPDX document containing all elements."""
145
creation_info: CreationInfo
146
packages: List[Package]
147
files: List[File]
148
snippets: List[Snippet]
149
extracted_licensing_infos: List[ExtractedLicensingInfo]
150
relationships: List[Relationship]
151
annotations: List[Annotation]
152
153
class CreationInfo:
154
"""Document creation metadata."""
155
spdx_version: str
156
spdx_id: str
157
name: str
158
document_namespace: str
159
creators: List[Actor]
160
created: datetime
161
```
162
163
[Data Models](./models.md)
164
165
### Command Line Tools
166
167
CLI tools for parsing, validating, converting, and analyzing SPDX documents with support for all major formats and comprehensive error reporting.
168
169
```python { .api }
170
def main(infile: str, outfile: str, version: str, novalidation: bool, graph: bool) -> None:
171
"""
172
CLI entry point for pyspdxtools command.
173
174
Args:
175
infile: Input SPDX file path
176
outfile: Output file path (or "-" for stdout)
177
version: SPDX version to validate against
178
novalidation: Skip validation if True
179
graph: Generate relationship graph if True
180
"""
181
```
182
183
[Command Line Tools](./cli.md)
184
185
### SPDX 3.0 Support
186
187
Experimental support for the upcoming SPDX 3.0 specification including new data models, profile support, and enhanced capabilities.
188
189
```python { .api }
190
class SpdxDocument:
191
"""SPDX 3.0 document root."""
192
creation_info: CreationInfo
193
elements: List[Element]
194
195
class Element:
196
"""Base class for all SPDX 3.0 elements."""
197
spdx_id: str
198
name: Optional[str]
199
summary: Optional[str]
200
```
201
202
[SPDX 3.0 Support](./spdx3.md)
203
204
## Types
205
206
```python { .api }
207
from enum import Enum
208
from datetime import datetime
209
from typing import List, Optional, Union
210
211
class FileFormat(Enum):
212
"""Supported SPDX file formats."""
213
JSON = "json"
214
YAML = "yaml"
215
XML = "xml"
216
TAG_VALUE = "tag_value"
217
RDF_XML = "rdf_xml"
218
219
class ActorType(Enum):
220
"""Types of actors/creators."""
221
PERSON = "Person"
222
ORGANIZATION = "Organization"
223
TOOL = "Tool"
224
225
class RelationshipType(Enum):
226
"""Types of relationships between SPDX elements."""
227
DESCRIBES = "DESCRIBES"
228
DESCRIBED_BY = "DESCRIBED_BY"
229
CONTAINS = "CONTAINS"
230
CONTAINED_BY = "CONTAINED_BY"
231
DEPENDS_ON = "DEPENDS_ON"
232
DEPENDENCY_OF = "DEPENDENCY_OF"
233
# ... many more relationship types
234
235
class ChecksumAlgorithm(Enum):
236
"""Supported checksum algorithms."""
237
SHA1 = "SHA1"
238
SHA224 = "SHA224"
239
SHA256 = "SHA256"
240
SHA384 = "SHA384"
241
SHA512 = "SHA512"
242
MD5 = "MD5"
243
BLAKE2B_256 = "BLAKE2b-256"
244
# ... more algorithms
245
246
class ValidationMessage:
247
"""Validation error or warning message."""
248
validation_message: str
249
context: ValidationContext
250
251
class SPDXParsingError(Exception):
252
"""Exception raised during SPDX parsing."""
253
def get_messages(self) -> List[str]:
254
"""Get list of parsing error messages."""
255
```