0
# Document Operations
1
2
Core functionality for creating, reading, writing, and managing DXF documents. These operations form the foundation of all DXF file manipulation in ezdxf, supporting all DXF versions from R12 through R2018.
3
4
```python
5
from typing import Union, Sequence, TextIO, Optional, List
6
from pathlib import Path
7
```
8
9
## Capabilities
10
11
### Document Creation
12
13
Create new DXF documents with specified version and setup options.
14
15
```python { .api }
16
def new(
17
dxfversion: str = 'R2013',
18
setup: Union[str, bool, Sequence[str]] = False,
19
units: int = 6
20
) -> Drawing:
21
"""
22
Create a new DXF document.
23
24
Parameters:
25
- dxfversion: DXF version ('R12', 'R2000', 'R2004', 'R2007', 'R2010',
26
'R2013', 'R2018'), default is 'R2013'
27
- setup: setup default styles - False for no setup, True for all, or
28
list of topics ['linetypes', 'styles', 'dimstyles', 'visualstyles']
29
- units: document and modelspace units, default is 6 for meters
30
31
Returns:
32
Drawing: New DXF document instance
33
"""
34
```
35
36
Usage example:
37
```python
38
import ezdxf
39
40
# Create new R2018 document with standard setup
41
doc = ezdxf.new('R2018', setup=True, units=4) # millimeters
42
43
# Create minimal R12 document
44
doc_r12 = ezdxf.new('R12')
45
```
46
47
### Document Reading
48
49
Read existing DXF documents from various sources including files, streams, and compressed archives.
50
51
```python { .api }
52
def read(stream: TextIO, *, errors: str = 'surrogateescape') -> Drawing:
53
"""
54
Read DXF document from text stream.
55
56
Parameters:
57
- stream: text stream (file-like object)
58
- errors: error handling strategy for encoding issues
59
60
Returns:
61
Drawing: DXF document instance
62
"""
63
64
def readfile(
65
filename: str,
66
encoding: Optional[str] = None,
67
errors: str = 'surrogateescape'
68
) -> Drawing:
69
"""
70
Read DXF document from file system.
71
72
Parameters:
73
- filename: path to DXF file
74
- encoding: text encoding (auto-detected if None)
75
- errors: error handling strategy for encoding issues
76
77
Returns:
78
Drawing: DXF document instance
79
"""
80
81
def readzip(
82
zipfile: str,
83
filename: Optional[str] = None,
84
*,
85
errors: str = 'surrogateescape'
86
) -> Drawing:
87
"""
88
Read DXF document from ZIP archive.
89
90
Parameters:
91
- zipfile: path to ZIP file
92
- filename: DXF file name in ZIP (first .dxf file if None)
93
- errors: error handling strategy for encoding issues
94
95
Returns:
96
Drawing: DXF document instance
97
"""
98
99
def decode_base64(data: str, *, errors: str = 'surrogateescape'):
100
"""
101
Load DXF document from base64 encoded data.
102
103
Parameters:
104
- data: base64 encoded DXF data
105
- errors: error handling strategy for encoding issues
106
107
Returns:
108
Drawing: DXF document instance
109
"""
110
```
111
112
Usage examples:
113
```python
114
import ezdxf
115
116
# Read from file
117
doc = ezdxf.readfile('drawing.dxf')
118
119
# Read from ZIP archive
120
doc = ezdxf.readzip('archive.zip', 'drawing.dxf')
121
122
# Read from stream
123
with open('drawing.dxf', 'rt') as f:
124
doc = ezdxf.read(f)
125
126
# Read from base64 data
127
encoded_data = "..." # base64 encoded DXF content
128
doc = ezdxf.decode_base64(encoded_data)
129
```
130
131
### Document Validation
132
133
Validate DXF documents and detect structural issues, missing references, and format violations.
134
135
```python { .api }
136
def is_dxf_file(filename: str) -> bool:
137
"""
138
Check if file is valid DXF format.
139
140
Parameters:
141
- filename: path to file
142
143
Returns:
144
bool: True if valid DXF file
145
"""
146
147
def is_dxf_stream(stream) -> bool:
148
"""
149
Check if text stream contains valid DXF data.
150
151
Parameters:
152
- stream: text stream to check
153
154
Returns:
155
bool: True if valid DXF stream
156
"""
157
```
158
159
Usage examples:
160
```python
161
import ezdxf
162
163
# Validate file
164
if ezdxf.is_dxf_file('unknown.dxf'):
165
doc = ezdxf.readfile('unknown.dxf')
166
167
# Validate stream
168
with open('data.txt', 'rt') as f:
169
if ezdxf.is_dxf_stream(f):
170
f.seek(0) # Reset stream position
171
doc = ezdxf.read(f)
172
```
173
174
### Document Information and Configuration
175
176
Access document metadata, configuration options, and system information.
177
178
```python { .api }
179
def print_config(verbose: bool = False, stream = None):
180
"""
181
Print ezdxf configuration information.
182
183
Parameters:
184
- verbose: include detailed configuration and environment info
185
- stream: output stream (stdout if None)
186
"""
187
188
# Configuration objects
189
options: Options
190
"""Global configuration options"""
191
192
config_files: List[Path]
193
"""Loaded configuration files"""
194
```
195
196
Usage examples:
197
```python
198
import ezdxf
199
200
# Print basic configuration
201
ezdxf.print_config()
202
203
# Print detailed configuration
204
ezdxf.print_config(verbose=True)
205
206
# Access configuration options
207
print(f"Using C extensions: {ezdxf.options.use_c_ext}")
208
print(f"Test files path: {ezdxf.options.test_files}")
209
```
210
211
### Document Recovery
212
213
Recover corrupted or damaged DXF files with best-effort parsing and error correction.
214
215
```python { .api }
216
# From ezdxf.recover module
217
def read(stream, errors: str = 'ignore'):
218
"""
219
Read and recover corrupted DXF document from stream.
220
221
Parameters:
222
- stream: text stream
223
- errors: error handling ('ignore', 'strict')
224
225
Returns:
226
Drawing: Recovered document
227
"""
228
229
def readfile(filename: str, *, encoding: str = None, errors: str = 'ignore'):
230
"""
231
Read and recover corrupted DXF file.
232
233
Parameters:
234
- filename: path to DXF file
235
- encoding: text encoding
236
- errors: error handling ('ignore', 'strict')
237
238
Returns:
239
Drawing: Recovered document
240
"""
241
```
242
243
Usage examples:
244
```python
245
import ezdxf.recover
246
247
# Attempt to recover corrupted file
248
try:
249
doc = ezdxf.recover.readfile('corrupted.dxf')
250
print("Recovery successful")
251
except Exception as e:
252
print(f"Recovery failed: {e}")
253
```
254
255
### Document Saving and Export
256
257
Save DXF documents to files with various encoding and format options.
258
259
```python { .api }
260
class Drawing:
261
def save(self):
262
"""Save document to original filename"""
263
264
def saveas(self, filename: str, *, encoding: str = 'utf-8', fmt: str = 'asc'):
265
"""
266
Save document to specified file.
267
268
Parameters:
269
- filename: target file path
270
- encoding: text encoding ('utf-8', 'cp1252', etc.)
271
- fmt: file format ('asc' for ASCII, 'bin' for binary)
272
"""
273
274
def write(self, stream, *, fmt: str = 'asc'):
275
"""
276
Write document to stream.
277
278
Parameters:
279
- stream: output stream
280
- fmt: file format ('asc' for ASCII, 'bin' for binary)
281
"""
282
```
283
284
Usage examples:
285
```python
286
# Save to file
287
doc.saveas('output.dxf')
288
289
# Save with specific encoding
290
doc.saveas('output.dxf', encoding='cp1252')
291
292
# Save as binary DXF (smaller file size)
293
doc.saveas('output.dxf', fmt='bin')
294
295
# Write to stream
296
with open('output.dxf', 'wt', encoding='utf-8') as f:
297
doc.write(f)
298
```
299
300
## Types
301
302
```python { .api }
303
class Drawing:
304
"""
305
Main DXF document class containing all drawing data and metadata.
306
"""
307
filename: str
308
dxfversion: str
309
encoding: str
310
311
def modelspace(self) -> Modelspace: ...
312
def layout(self, name: str = None) -> Layout: ...
313
def new_layout(self, name: str, dxfattribs: dict = None) -> Layout: ...
314
315
class Options:
316
"""Global configuration options"""
317
use_c_ext: bool
318
test_files: str
319
loaded_config_files: List[Path]
320
321
def write(self, stream): ...
322
```