0
# Configuration Management
1
2
Global and context-specific configuration for controlling ASDF behavior including validation settings, version defaults, array handling preferences, and I/O performance tuning.
3
4
## Capabilities
5
6
### Configuration Access
7
8
Access and manage the global ASDF configuration that affects all operations.
9
10
```python { .api }
11
def get_config():
12
"""
13
Get the current global ASDF configuration.
14
15
Returns:
16
AsdfConfig: Current configuration object
17
"""
18
```
19
20
### Configuration Context Manager
21
22
Temporarily modify configuration settings within a specific scope without affecting global settings.
23
24
```python { .api }
25
def config_context():
26
"""
27
Context manager for temporary configuration changes.
28
29
Returns:
30
AsdfConfig: Configuration object that can be modified within context
31
32
Example:
33
with asdf.config_context() as config:
34
config.validate_on_read = False
35
# Operations here use modified config
36
# Global config restored after context
37
"""
38
```
39
40
### AsdfConfig Class
41
42
Configuration object containing all ASDF behavioral settings with properties for validation, performance, and compatibility control.
43
44
```python { .api }
45
class AsdfConfig:
46
@property
47
def validate_on_read(self) -> bool:
48
"""
49
Whether to validate ASDF files when reading.
50
Default: True
51
"""
52
53
@validate_on_read.setter
54
def validate_on_read(self, value: bool):
55
"""Set validation on read behavior."""
56
57
@property
58
def default_version(self) -> str:
59
"""
60
Default ASDF version for new files.
61
Default: Latest supported version
62
"""
63
64
@default_version.setter
65
def default_version(self, value: str):
66
"""Set default ASDF version."""
67
68
@property
69
def io_block_size(self) -> int:
70
"""
71
Block size for file I/O operations in bytes.
72
Default: 65536 (64KB)
73
"""
74
75
@io_block_size.setter
76
def io_block_size(self, value: int):
77
"""Set I/O block size."""
78
79
@property
80
def array_inline_threshold(self) -> int:
81
"""
82
Size threshold in bytes for inlining arrays in YAML.
83
Arrays smaller than this are stored inline, larger ones in binary blocks.
84
Default: 100
85
"""
86
87
@array_inline_threshold.setter
88
def array_inline_threshold(self, value: int):
89
"""Set array inline threshold."""
90
91
@property
92
def all_array_storage(self) -> str:
93
"""
94
Global override for array storage mode.
95
Options: None, 'internal', 'external'
96
Default: None (use per-array settings)
97
"""
98
99
@all_array_storage.setter
100
def all_array_storage(self, value: str):
101
"""Set global array storage mode."""
102
103
@property
104
def all_array_compression(self) -> str:
105
"""
106
Global override for array compression.
107
Options: None, 'none', 'zlib', 'bzp2', 'lz4'
108
Default: None (use per-array settings)
109
"""
110
111
@all_array_compression.setter
112
def all_array_compression(self, value: str):
113
"""Set global array compression."""
114
115
@property
116
def legacy_fill_schema_defaults(self) -> bool:
117
"""
118
Whether to fill in schema defaults for legacy files.
119
Default: True
120
"""
121
122
@legacy_fill_schema_defaults.setter
123
def legacy_fill_schema_defaults(self, value: bool):
124
"""Set legacy schema defaults behavior."""
125
126
@property
127
def all_array_compression_kwargs(self) -> dict:
128
"""
129
Global compression keyword arguments for all arrays.
130
Dictionary of kwargs passed to compressor during block compression.
131
Default: None (no keyword arguments)
132
"""
133
134
@all_array_compression_kwargs.setter
135
def all_array_compression_kwargs(self, value: dict):
136
"""Set global array compression keyword arguments."""
137
138
@property
139
def default_array_save_base(self) -> bool:
140
"""
141
Whether to save base arrays for views by default.
142
When True, views of the same array refer to offsets/strides of same block.
143
Default: True
144
"""
145
146
@default_array_save_base.setter
147
def default_array_save_base(self, value: bool):
148
"""Set default array save base behavior."""
149
150
@property
151
def convert_unknown_ndarray_subclasses(self) -> bool:
152
"""
153
Whether to convert unknown ndarray subclasses to ndarray.
154
When True, unhandled ndarray subclasses appear as regular ndarrays.
155
Default: False (deprecated feature, issues AsdfConversionWarning)
156
"""
157
158
@convert_unknown_ndarray_subclasses.setter
159
def convert_unknown_ndarray_subclasses(self, value: bool):
160
"""Set ndarray subclass conversion behavior."""
161
162
@property
163
def lazy_tree(self) -> bool:
164
"""
165
Whether ASDF tree contents are lazily converted to custom objects.
166
When True, custom objects created only when accessed.
167
Default: False
168
"""
169
170
@lazy_tree.setter
171
def lazy_tree(self, value: bool):
172
"""Set lazy tree conversion behavior."""
173
174
# Read-only properties
175
@property
176
def resource_mappings(self) -> list:
177
"""
178
List of registered resource mapping instances.
179
Loaded from entry points unless overridden by user configuration.
180
"""
181
182
@property
183
def resource_manager(self):
184
"""
185
ResourceManager instance including resources from registered mappings.
186
"""
187
188
@property
189
def extensions(self) -> list:
190
"""
191
List of registered extensions loaded from entry points.
192
"""
193
```
194
195
## Usage Examples
196
197
### Reading Current Configuration
198
199
```python
200
import asdf
201
202
# Get current configuration
203
config = asdf.get_config()
204
205
print(f"Validation on read: {config.validate_on_read}")
206
print(f"Default version: {config.default_version}")
207
print(f"Array inline threshold: {config.array_inline_threshold} bytes")
208
print(f"I/O block size: {config.io_block_size} bytes")
209
```
210
211
### Temporary Configuration Changes
212
213
```python
214
# Use context manager for temporary changes
215
with asdf.config_context() as config:
216
# Disable validation for performance
217
config.validate_on_read = False
218
219
# Use older version for compatibility
220
config.default_version = "1.4.0"
221
222
# Operations within this block use modified settings
223
af = asdf.AsdfFile({"data": [1, 2, 3]})
224
af.write_to("output.asdf") # Uses version 1.4.0, no validation
225
226
# Outside context, original settings restored
227
print(asdf.get_config().default_version) # Back to original
228
```
229
230
### Performance Tuning
231
232
```python
233
# Configure for large file operations
234
with asdf.config_context() as config:
235
# Increase I/O block size for better throughput
236
config.io_block_size = 1024 * 1024 # 1MB blocks
237
238
# Increase inline threshold to reduce small array overhead
239
config.array_inline_threshold = 1000
240
241
# Disable validation for faster writes
242
config.validate_on_read = False
243
244
# Process large dataset
245
process_large_dataset()
246
```
247
248
### Global Array Settings
249
250
```python
251
# Set global compression for all arrays
252
with asdf.config_context() as config:
253
config.all_array_compression = 'lz4'
254
255
# All arrays will use LZ4 compression
256
data = {
257
"array1": np.random.random(10000),
258
"array2": np.arange(50000),
259
"array3": np.zeros((100, 100))
260
}
261
262
af = asdf.AsdfFile(data)
263
af.write_to("compressed.asdf")
264
```
265
266
### Legacy File Handling
267
268
```python
269
# Configure for legacy file compatibility
270
with asdf.config_context() as config:
271
# Enable legacy schema defaults
272
config.legacy_fill_schema_defaults = True
273
274
# Use older version for maximum compatibility
275
config.default_version = "1.3.0"
276
277
# Read old ASDF files with better compatibility
278
af = asdf.open("legacy_file.asdf")
279
```
280
281
### Development and Testing
282
283
```python
284
# Configuration for development/testing
285
def test_mode_config():
286
with asdf.config_context() as config:
287
# Strict validation for testing
288
config.validate_on_read = True
289
290
# Use latest version for testing new features
291
config.default_version = "1.5.0"
292
293
# Small inline threshold to test binary block handling
294
config.array_inline_threshold = 10
295
296
yield config
297
298
# Use in tests
299
with test_mode_config():
300
# Run tests with strict settings
301
run_validation_tests()
302
```
303
304
### Memory Optimization
305
306
```python
307
# Configure for memory-constrained environments
308
with asdf.config_context() as config:
309
# Smaller I/O blocks to reduce memory usage
310
config.io_block_size = 8192 # 8KB
311
312
# Lower inline threshold to move more data to disk
313
config.array_inline_threshold = 50
314
315
# Enable compression to reduce memory footprint
316
config.all_array_compression = 'zlib'
317
318
# Process data with reduced memory usage
319
process_memory_efficiently()
320
```
321
322
### Configuration for Different Environments
323
324
```python
325
def configure_for_environment(env_type):
326
"""Configure ASDF for different deployment environments."""
327
config = asdf.get_config()
328
329
if env_type == "production":
330
config.validate_on_read = True # Safety first
331
config.all_array_compression = 'lz4' # Good compression/speed balance
332
config.io_block_size = 262144 # 256KB for network efficiency
333
334
elif env_type == "development":
335
config.validate_on_read = True # Catch errors early
336
config.array_inline_threshold = 10 # Test binary handling
337
338
elif env_type == "performance":
339
config.validate_on_read = False # Maximum speed
340
config.io_block_size = 1048576 # 1MB blocks
341
config.all_array_compression = 'none' # No compression overhead
342
343
# Apply environment-specific configuration
344
configure_for_environment("production")
345
```