Configuration

Version 2.8 of this library introduced a new mechanism, AsdfConfig, for setting global configuration options. Currently available options are limited, but we expect to eventually move many of the AsdfFile.__init__ and AsdfFile.write_to keyword arguments to AsdfConfig.

AsdfConfig and you

The AsdfConfig class provides properties that can be adjusted to change the behavior of the asdf library for all files. For example, to disable schema validation on read:

>>> import asdf
>>> asdf.get_config().validate_on_read = False  

This will prevent validation on any subsequent call to open.

Obtaining an AsdfConfig instance

There are two methods available that give access to an AsdfConfig instance: get_config and config_context. The former simply returns the currently active config:

>>> import asdf
>>> asdf.get_config()
<AsdfConfig
  array_inline_threshold: None
  all_array_storage: None
  all_array_compression: input
  all_array_compression_kwargs: None
  default_array_save_base: True
  convert_unknown_ndarray_subclasses: True
  default_version: 1.5.0
  io_block_size: -1
  legacy_fill_schema_defaults: True
  validate_on_read: True
  lazy_tree: False
>

The latter method, config_context, returns a context manager that yields a copy of the currently active config. The copy is also returned by subsequent calls to get_config, but only until the context manager exits. This allows for short-lived configuration changes that do not impact other code:

>>> import asdf
>>> with asdf.config_context() as config:
...     config.validate_on_read = False
...     asdf.get_config()
...
<AsdfConfig
  array_inline_threshold: None
  all_array_storage: None
  all_array_compression: input
  all_array_compression_kwargs: None
  default_array_save_base: True
  convert_unknown_ndarray_subclasses: True
  default_version: 1.5.0
  io_block_size: -1
  legacy_fill_schema_defaults: True
  validate_on_read: False
  lazy_tree: False
>
>>> asdf.get_config()
<AsdfConfig
  array_inline_threshold: None
  all_array_storage: None
  all_array_compression: input
  all_array_compression_kwargs: None
  default_array_save_base: True
  convert_unknown_ndarray_subclasses: True
  default_version: 1.5.0
  io_block_size: -1
  legacy_fill_schema_defaults: True
  validate_on_read: True
  lazy_tree: False
>

Special note to library maintainers

Libraries that use asdf are encouraged to only modify AsdfConfig within a surrounding call to config_context. The downstream library will then be able to customize asdf’s behavior without impacting other libraries or clobbering changes made by the user.

Config options

array_inline_threshold

The threshold number of array elements under which arrays are automatically stored inline in the ASDF tree instead of in binary blocks. If None, array storage type is not managed automatically.

Defaults to None.

all_array_storage

Use this storage type for all arrays within an ASDF file. Must be one of

"internal"
"external"
"inline"
None

If None a different storage type can be used for each array. See AsdfFile.set_array_storage for more details.

Defaults to None.

all_array_compression

Use this compression type for all arrays within an ASDF file. If "input" a different compression type can be used for each array. See AsdfFile.set_array_compression for more details.

Defaults to "input".

all_array_compression_kwargs

Use these additional compression keyword arguments for all arrays within an ASDF file. If None diffeerent keyword arguments can be set for each array. See AsdfFile.set_array_compression for more details.

Defaults to None.

default_array_save_base

Controls the default behavior asdf will follow when saving an array view. If True (the default) the base array for the view will be saved in an ASDF binary block. If False the data corresponding to the view will be saved in an ASDF binary block.

convert_unknown_ndarray_subclasses

Convert otherwise unhandled instances of subclasses of ndarray into ndarrays prior to serialization.

Previous extension code allowed AsdfTypes to convert instances of subclasses of supported types. Internally, the handling of ndarrays has been moved from an AsdfType to a Converter which does not support converting instances of subclasses unless they are explicitly listed. This means that code that previously relied on asdf converting instances of subclasses of ndarray into an ndarray will need to be updated to define a Converter for the ndarray subclass or to request that support be added directly in asdf (for subclasses in existing asdf dependencies).

With this setting enabled, asdf will continue to convert instances of subclasses of ndarray but will issue a warning when an instance is converted. In a future version of asdf this default will change to False, a deprecation warning will be issued and finally the conversion of instances of subclasses will be removed.

Defaults to True.

default_version

The default ASDF Standard version used for new files. This can be overridden on an individual file basis (using the version argument to AsdfFile.__init__) or set here to change the default for all new files created in the current session.

Defaults to the latest stable ASDF Standard version.

io_block_size

The buffer size used when reading and writing to the filesystem. Users may wish to adjust this value to improve I/O performance. Set to -1 to use the preferred block size for each file, as reported by st_blksize.

Defaults to -1.

legacy_fill_schema_defaults

Flag that controls filling default values from schemas for older versions of the ASDF Standard. This library used to remove nodes from the tree whose values matched the default property in the schema. That behavior was changed in asdf 2.8, but in order to read files produced by older versions of the library, default values must still be filled from the schema for ASDF Standard <= 1.5.0.

Set to False to disable filling default values from the schema for these older ASDF Standard versions. The flag has no effect for ASDF Standard >= 1.6.0.

Defaults to True.

validate_on_read

Flag that controls schema validation of the ASDF tree when opening files. Users who trust the source of their files may wish to disable validation on read to improve performance.

Defaults to True.

Additional AsdfConfig features

AsdfConfig also provides methods for adding and removing plugins at runtime. For example, the AsdfConfig.add_resource_mapping method can be used to register a schema, which can then be used to validate a file:

>>> import asdf
>>> content = b"""
... %YAML 1.1
... ---
... $schema: http://stsci.edu/schemas/yaml-schema/draft-01
... id: http://example.com/example-project/schemas/foo-1.0.0
... type: object
... properties:
...   foo:
...     type: string
... required: [foo]
... ...
... """
>>> asdf.get_config().add_resource_mapping(
...     {"http://example.com/example-project/schemas/foo-1.0.0": content}
... )
>>> af = asdf.AsdfFile(custom_schema="http://example.com/example-project/schemas/foo-1.0.0")
>>> af.validate()
Traceback (most recent call last):
...
asdf._jsonschema.exceptions.ValidationError: 'foo' is a required property
...
>>> af["foo"] = "bar"
>>> af.validate()

See the AsdfConfig API documentation for more detail.