0
# Document Writing
1

2
Comprehensive writing functionality for SPDX documents supporting all major output formats with automatic format detection, optional validation, and flexible output options.
3

4
## Capabilities
5

6
### Universal File Writing
7

8
Write SPDX documents to files with automatic format detection based on file extension.
9

10
```python { .api }
11
def write_file(document: Document, file_name: str, validate: bool = True):
12
    """
13
    Write SPDX document to file in any supported format.
14
    
15
    Automatically detects format from file extension:
16
    - .spdx, .tag -> Tag/Value format
17
    - .json -> JSON format
18
    - .yaml, .yml -> YAML format
19
    - .xml -> XML format
20
    - .rdf, .rdf.xml -> RDF/XML format
21
    
22
    Args:
23
        document: SPDX document to write
24
        file_name: Output file path (format determined by extension)
25
        validate: Whether to validate document before writing (default: True)
26
        
27
    Raises:
28
        ValidationError: If validation fails and validate=True
29
        FileNotFoundError: If output directory doesn't exist
30
        PermissionError: If cannot write to file
31
    """
32
```
33

34
### JSON Writing
35

36
Write SPDX documents to JSON format files.
37

38
```python { .api }
39
def write_document_to_file(document: Document, file_name: str, validate: bool = True) -> None:
40
    """
41
    Write SPDX document to JSON file.
42
    
43
    Args:
44
        document: SPDX document to write
45
        file_name: Output JSON file path
46
        validate: Whether to validate before writing
47
        
48
    Raises:
49
        ValidationError: If validation fails and validate=True
50
    """
51
```
52

53
### XML Writing
54

55
Write SPDX documents to XML format files.
56

57
```python { .api }
58
def write_document_to_file(document: Document, file_name: str, validate: bool = True) -> None:
59
    """
60
    Write SPDX document to XML file.
61
    
62
    Args:
63
        document: SPDX document to write
64
        file_name: Output XML file path
65
        validate: Whether to validate before writing
66
        
67
    Raises:
68
        ValidationError: If validation fails and validate=True
69
    """
70
```
71

72
### YAML Writing
73

74
Write SPDX documents to YAML format files.
75

76
```python { .api }
77
def write_document_to_file(document: Document, file_name: str, validate: bool = True) -> None:
78
    """
79
    Write SPDX document to YAML file.
80
    
81
    Args:
82
        document: SPDX document to write
83
        file_name: Output YAML file path
84
        validate: Whether to validate before writing
85
        
86
    Raises:
87
        ValidationError: If validation fails and validate=True
88
    """
89
```
90

91
### Tag-Value Writing
92

93
Write SPDX documents to Tag-Value format files.
94

95
```python { .api }
96
def write_document_to_file(document: Document, file_name: str, validate: bool = True) -> None:
97
    """
98
    Write SPDX document to Tag-Value file.
99
    
100
    Args:
101
        document: SPDX document to write
102
        file_name: Output Tag-Value file path (.spdx extension)
103
        validate: Whether to validate before writing
104
        
105
    Raises:
106
        ValidationError: If validation fails and validate=True
107
    """
108

109
def write_document(document: Document, stream) -> None:
110
    """
111
    Write SPDX document to Tag-Value format stream.
112
    
113
    Args:
114
        document: SPDX document to write
115
        stream: Output stream (e.g., sys.stdout, file object)
116
    """
117
```
118

119
### RDF Writing
120

121
Write SPDX documents to RDF/XML format files.
122

123
```python { .api }
124
def write_document_to_file(document: Document, file_name: str, validate: bool = True) -> None:
125
    """
126
    Write SPDX document to RDF/XML file.
127
    
128
    Args:
129
        document: SPDX document to write
130
        file_name: Output RDF file path (.rdf or .rdf.xml extension)
131
        validate: Whether to validate before writing
132
        
133
    Raises:
134
        ValidationError: If validation fails and validate=True
135
    """
136
```
137

138
## Usage Examples
139

140
### Basic File Writing
141

142
```python
143
from spdx_tools.spdx.writer.write_anything import write_file
144
from spdx_tools.spdx.parser.parse_anything import parse_file
145

146
# Parse a document and convert to different formats
147
document = parse_file("input.spdx")
148

149
# Write to different formats (format auto-detected from extension)
150
write_file(document, "output.json")      # JSON format
151
write_file(document, "output.yaml")      # YAML format
152
write_file(document, "output.xml")       # XML format
153
write_file(document, "output.rdf")       # RDF/XML format
154
write_file(document, "output.spdx")      # Tag-Value format
155
```
156

157
### Writing Without Validation
158

159
```python
160
# Skip validation for faster writing (not recommended for production)
161
write_file(document, "output.json", validate=False)
162
```
163

164
### Format-Specific Writing
165

166
```python
167
from spdx_tools.spdx.writer.json import json_writer
168
from spdx_tools.spdx.writer.xml import xml_writer
169
from spdx_tools.spdx.writer.yaml import yaml_writer
170

171
# Use format-specific writers directly
172
json_writer.write_document_to_file(document, "output.json")
173
xml_writer.write_document_to_file(document, "output.xml")
174
yaml_writer.write_document_to_file(document, "output.yaml")
175
```
176

177
### Writing to Stream
178

179
```python
180
import sys
181
from spdx_tools.spdx.writer.tagvalue import tagvalue_writer
182

183
# Write Tag-Value format to stdout
184
tagvalue_writer.write_document(document, sys.stdout)
185

186
# Write to custom stream
187
with open("output.spdx", "w") as f:
188
    tagvalue_writer.write_document(document, f)
189
```
190

191
### Error Handling
192

193
```python
194
from spdx_tools.spdx.writer.write_anything import write_file
195

196
try:
197
    write_file(document, "output.json")
198
    print("Document written successfully")
199
except Exception as e:
200
    print(f"Writing failed: {e}")
201
```
202

203
### Batch Conversion
204

205
```python
206
import os
207
from spdx_tools.spdx.parser.parse_anything import parse_file
208
from spdx_tools.spdx.writer.write_anything import write_file
209

210
def convert_spdx_files(input_dir: str, output_dir: str, target_format: str):
211
    """Convert all SPDX files in directory to target format."""
212
    for filename in os.listdir(input_dir):
213
        if filename.endswith((".spdx", ".json", ".yaml", ".xml", ".rdf")):
214
            input_path = os.path.join(input_dir, filename)
215
            output_filename = os.path.splitext(filename)[0] + f".{target_format}"
216
            output_path = os.path.join(output_dir, output_filename)
217
            
218
            try:
219
                document = parse_file(input_path)
220
                write_file(document, output_path)
221
                print(f"Converted {filename} -> {output_filename}")
222
            except Exception as e:
223
                print(f"Failed to convert {filename}: {e}")
224

225
# Convert all files to JSON
226
convert_spdx_files("input_docs/", "output_docs/", "json")
227
```
228

229
## Types
230

231
```python { .api }
232
from typing import TextIO
233

234
# All writer functions accept Document objects and file paths
235
# Stream writers accept any text stream (TextIO)
236
```