# AsdfFile

class asdf.AsdfFile(tree=None, uri=None, extensions=None, version=None, ignore_version_mismatch=True, ignore_unrecognized_tag=False, ignore_implicit_conversion=False, copy_arrays=False, lazy_load=True, custom_schema=None, _readonly=False)

  Bases: `object`

  The main class that represents an ASDF file object.

  Parameters
    tree dict or AsdfFile, optional

      The main tree data in the ASDF file. Must conform to the ASDF schema.

    uri str, optional

      The URI for this ASDF file. Used to resolve relative references against. If not provided, will be automatically determined from the associated file object, if possible and if created from `AsdfFile.open`.

    extensions object, optional

      Additional extensions to use when reading and writing the file. May be any of the following: `asdf.extension.AsdfExtension`, `asdf.extension.Extension`, `asdf.extension.AsdfExtensionList` or a `list` of extensions.

    version str, optional

      The ASDF Standard version. If not provided, defaults to the configured default version. See `asdf.config.AsdfConfig.default_version`.

    ignore_version_mismatch bool, optional

      When `True`, do not raise warnings for mismatched schema versions. Set to `True` by default.

    ignore_unrecognized_tag bool, optional

      When `True`, do not raise warnings for unrecognized tags. Set to `False` by default.

    ignore_implicit_conversion bool

      When `True`, do not raise warnings when types in the tree are implicitly converted into a serializable object. The motivating case for this is currently `namedtuple`, which cannot be serialized as-is.

    copy_arrays bool, optional

      When `False`, when reading files, attempt to memmap underlying data arrays when possible.

    lazy_load bool, optional

      When `True` and the underlying file handle is seekable, data arrays will only be loaded lazily: i.e. when they are accessed for the first time. In this case the underlying file must stay open during the lifetime of the tree. Setting to False causes all data arrays to be loaded up front, which means that they can be accessed even after the underlying file is closed. Note: even if `lazy_load` is `False`, `copy_arrays` is still taken into account.

    custom_schema str, optional

      Path to a custom schema file that will be used for a secondary validation pass. This can be used to ensure that particular ASDF files follow custom conventions beyond those enforced by the standard.

  Attributes Summary

  `blocks` | Get the block manager associated with the `AsdfFile`.
  `comments` | Get the comments after the header, before the tree.
  `extension_list` | Get the AsdfExtensionList for this AsdfFile.
  `extension_manager` | Get the ExtensionManager for this AsdfFile.
  `extensions` | Get the list of user extensions that are enabled for use with this AsdfFile.
  `file_format_version` |
  `resolver` |
  `tag_mapping` |
  `tag_to_schema_resolver` |
  `tree` | Get/set the tree of data in the ASDF file.
  `type_index` |
  `uri` | Get the URI associated with the `AsdfFile`.
  `url_mapping` |
  `version` | Get this AsdfFile's ASDF Standard version.
  `version_map` |
  `version_string` | Get this AsdfFile's ASDF Standard version as a string.

  Methods Summary

  `add_history_entry`(description[, software]) | Add an entry to the history list.
  `close`() | Close the file handles associated with the `AsdfFile`.
  `copy`() |
  `fill_defaults`() | Fill in any values that are missing in the tree using default values from the schema.
  `find_references`() | Finds all external "JSON References" in the tree and converts them to `reference.Reference` objects.
  `get_array_compression`(arr) | Get the compression type for the given array data.
  `get_array_compression_kwargs`(arr) |
  `get_array_storage`(arr) | Get the block type for the given array data.
  `get_history_entries`() | Get a list of history entries from the file object.
  `info`([max_rows, max_cols, show_values]) | Print a rendering of this file's tree to stdout.
  `keys`() |
  `make_reference`([path]) | Make a new reference to a part of this file's tree, that can be assigned as a reference to another tree.
  `open`(fd[, uri, mode, validate_checksums, ...]) | Open an existing ASDF file.
  `open_external`(uri, **kwargs) | Open an external ASDF file, from the given (possibly relative) URI.
  `remove_defaults`() | Remove any values in the tree that are the same as the default values in the schema
  `resolve_and_inline`() | Resolves all external references and inlines all data.
  `resolve_references`(**kwargs) | Finds all external "JSON References" in the tree, loads the external content, and places it directly in the tree.
  `resolve_uri`(uri) | Resolve a (possibly relative) URI against the URI of this ASDF file.
  `run_hook`(hookname) | Run a "hook" for each custom type found in the tree.
  `run_modifying_hook`(hookname[, validate]) | Run a "hook" for each custom type found in the tree.
  `search`([key, type, value, filter]) | Search this file's tree.
  `set_array_compression`(arr, compression, ...) | Set the compression to use for the given array data.
  `set_array_storage`(arr, array_storage) | Set the block type to use for the given array data.
  `update`([all_array_storage, ...]) | Update the file on disk in place.
  `validate`() | Validate the current state of the tree against the ASDF schema.
  `write_to`(fd[, all_array_storage, ...]) | Write the ASDF file to the given file-like object.

  Attributes Documentation

  blocks

    Get the block manager associated with the `AsdfFile`.

  comments

    Get the comments after the header, before the tree.

  extension_list

    Get the AsdfExtensionList for this AsdfFile.

    Returns
      asdf.extension.AsdfExtensionList
  extension_manager

    Get the ExtensionManager for this AsdfFile.

    Returns
      asdf.extension.ExtensionManager
  extensions

    Get the list of user extensions that are enabled for use with this AsdfFile.

    Returns
      list of asdf.extension.ExtensionProxy
  file_format_version
  resolver
  tag_mapping
  tag_to_schema_resolver
  tree

    Get/set the tree of data in the ASDF file.

    When set, the tree will be validated against the ASDF schema.

  type_index
  uri

    Get the URI associated with the `AsdfFile`.

    In many cases, it is automatically determined from the file handle used to read or write the file.

  url_mapping
  version

    Get this AsdfFile’s ASDF Standard version.

    Returns
      asdf.versioning.AsdfVersion
  version_map
  version_string

    Get this AsdfFile’s ASDF Standard version as a string.

    Returns
      str

  Methods Documentation

  add_history_entry(description, software=None)

    Add an entry to the history list.

    Parameters
      description str

        A description of the change.

      software dict or list of dict

        A description of the software used. It should not include asdf itself, as that is automatically notated in the `asdf_library` entry.

        Each dict must have the following keys:

        - `name`: The name of the software

        - `author`: The author or institution that produced the software

        - `homepage`: A URI to the homepage of the software

        - `version`: The version of the software

  close()

    Close the file handles associated with the `AsdfFile`.

  copy()
  fill_defaults()

    Fill in any values that are missing in the tree using default values from the schema.

  find_references()

    Finds all external “JSON References” in the tree and converts them to `reference.Reference` objects.

  get_array_compression(arr)

    Get the compression type for the given array data.

    Parameters
      arr numpy.ndarray
    Returns
      compression str or None
  get_array_compression_kwargs(arr)
  get_array_storage(arr)

    Get the block type for the given array data.

    Parameters
      arr numpy.ndarray
  get_history_entries()

    Get a list of history entries from the file object.

    Returns
      entries list

        A list of history entries.

  info(max_rows=24, max_cols=120, show_values=True)

    Print a rendering of this file’s tree to stdout.

    Parameters
      max_rows int, tuple, or None, optional

        Maximum number of lines to print. Nodes that cannot be displayed will be elided with a message. If int, constrain total number of displayed lines. If tuple, constrain lines per node at the depth corresponding to the tuple index. If None, display all lines.

      max_cols int or None, optional

        Maximum length of line to print. Nodes that cannot be fully displayed will be truncated with a message. If int, constrain length of displayed lines. If None, line length is unconstrained.

      show_values bool, optional

        Set to False to disable display of primitive values in the rendered tree.

  keys() → a set-like object providing a view on D's keys
  make_reference(path=[])

    Make a new reference to a part of this file’s tree, that can be assigned as a reference to another tree.

    Parameters
      path list of str and int, optional

        The parts of the path pointing to an item in this tree. If omitted, points to the root of the tree.

    Returns
      reference reference.Reference

        A reference object.

    Examples

    For the given AsdfFile `ff`, add an external reference to the data in an external file:

        >>> import asdf
        >>> flat = asdf.open("http://stsci.edu/reference_files/flat.asdf")
        >>> ff.tree['flat_field'] = flat.make_reference(['data'])

  classmethod open(fd, uri=None, mode='r', validate_checksums=False, extensions=None, ignore_version_mismatch=True, ignore_unrecognized_tag=False, _force_raw_types=False, copy_arrays=False, lazy_load=True, custom_schema=None, strict_extension_check=False, ignore_missing_extensions=False, **kwargs)

    Open an existing ASDF file.

    Deprecated since version 2.2: Use `asdf.open` instead.

  open_external(uri, **kwargs)

    Open an external ASDF file, from the given (possibly relative) URI. There is a cache (internal to this ASDF file) that ensures each external ASDF file is loaded only once.

    Parameters
      uri str

        An absolute or relative URI to resolve against the URI of this ASDF file.

    Returns
      asdffile AsdfFile

        The external ASDF file.

  remove_defaults()

    Remove any values in the tree that are the same as the default values in the schema

  resolve_and_inline()

    Resolves all external references and inlines all data. This produces something that, when saved, is a 100% valid YAML file.

  resolve_references(**kwargs)

    Finds all external “JSON References” in the tree, loads the external content, and places it directly in the tree. Saving a ASDF file after this operation means it will have no external references, and will be completely self-contained.

  resolve_uri(uri)

    Resolve a (possibly relative) URI against the URI of this ASDF file. May be overridden by base classes to change how URIs are resolved. This does not apply any `uri_mapping` that was passed to the constructor.

    Parameters
      uri str

        An absolute or relative URI to resolve against the URI of this ASDF file.

    Returns
      uri str

        The resolved URI.

  run_hook(hookname)

    Run a “hook” for each custom type found in the tree.

    Parameters
      hookname str

        The name of the hook. If a `AsdfType` is found with a method with this name, it will be called for every instance of the corresponding custom type in the tree.

  run_modifying_hook(hookname, validate=True)

    Run a “hook” for each custom type found in the tree. The hook is free to return a different object in order to modify the tree.

    Parameters
      hookname str

        The name of the hook. If a `AsdfType` is found with a method with this name, it will be called for every instance of the corresponding custom type in the tree.

      validate bool

        When `True` (default) validate the resulting tree.

  search(key=NotSet, type=NotSet, value=NotSet, filter=None)

    Search this file’s tree.

    Parameters
      key NotSet, str, or any other object

        Search query that selects nodes by dict key or list index. If NotSet, the node key is unconstrained. If str, the input is searched among keys/indexes as a regular expression pattern. If any other object, node’s key or index must equal the queried key.

      type NotSet, str, or builtins.type

        Search query that selects nodes by type. If NotSet, the node type is unconstrained. If str, the input is searched among (fully qualified) node type names as a regular expression pattern. If builtins.type, the node must be an instance of the input.

      value NotSet, str, or any other object

        Search query that selects nodes by value. If NotSet, the node value is unconstrained. If str, the input is searched among values as a regular expression pattern. If any other object, node’s value must equal the queried value.

      filter callable

        Callable that filters nodes by arbitrary criteria. The callable accepts one or two arguments:

        - the node

        - the node’s list index or dict key (optional)

        and returns True to retain the node, or False to remove it from the search results.

    Returns
      asdf.search.AsdfSearchResult

        the result of the search

  set_array_compression(arr, compression, **compression_kwargs)

    Set the compression to use for the given array data.

    Parameters
      arr numpy.ndarray

        The array to set. If multiple views of the array are in the tree, only the most recent compression setting will be used, since all views share a single block.

      compression str or None

        Must be one of:

        - `''` or `None`: no compression

        - `zlib`: Use zlib compression

        - `bzp2`: Use bzip2 compression

        - `lz4`: Use lz4 compression

        - `input`: Use the same compression as in the file read. If there is no prior file, acts as None.

  set_array_storage(arr, array_storage)

    Set the block type to use for the given array data.

    Parameters
      arr numpy.ndarray

        The array to set. If multiple views of the array are in the tree, only the most recent block type setting will be used, since all views share a single block.

      array_storage str

        Must be one of:

        - `internal`: The default. The array data will be stored in a binary block in the same ASDF file.

        - `external`: Store the data in a binary block in a separate ASDF file.

        - `inline`: Store the data as YAML inline in the tree.

  update(all_array_storage=None, all_array_compression='input', pad_blocks=False, include_block_index=True, version=None, compression_kwargs=None, **kwargs)

    Update the file on disk in place.

    Parameters
      all_array_storage string, optional

        If provided, override the array storage type of all blocks in the file immediately before writing. Must be one of:

        - `internal`: The default. The array data will be stored in a binary block in the same ASDF file.

        - `external`: Store the data in a binary block in a separate ASDF file.

        - `inline`: Store the data as YAML inline in the tree.

      all_array_compression string, optional

        If provided, set the compression type on all binary blocks in the file. Must be one of:

        - `''` or `None`: No compression.

        - `zlib`: Use zlib compression.

        - `bzp2`: Use bzip2 compression.

        - `lz4`: Use lz4 compression.

        - `input`: Use the same compression as in the file read. If there is no prior file, acts as None

      pad_blocks float or bool, optional

        Add extra space between blocks to allow for updating of the file. If `False` (default), add no padding (always return 0). If `True`, add a default amount of padding of 10% If a float, it is a factor to multiple content_size by to get the new total size.

      include_block_index bool, optional

        If `False`, don’t include a block index at the end of the file. (Default: `True`) A block index is never written if the file has a streamed block.

      version str, optional

        Update the ASDF Standard version of this AsdfFile before writing.

      auto_inline int, optional

        DEPRECATED. When the number of elements in an array is less than this threshold, store the array as inline YAML, rather than a binary block. This only works on arrays that do not share data with other arrays. Default is the value specified in `asdf.get_config().array_inline_threshold`.

  validate()

    Validate the current state of the tree against the ASDF schema.

  write_to(fd, all_array_storage=None, all_array_compression='input', pad_blocks=False, include_block_index=True, version=None, compression_kwargs=None, **kwargs)

    Write the ASDF file to the given file-like object.

    `write_to` does not change the underlying file descriptor in the `AsdfFile` object, but merely copies the content to a new file.

    Parameters
      fd string or file-like object

        May be a string path to a file, or a Python file-like object. If a string path, the file is automatically closed after writing. If not a string path, it is the caller’s responsibility to close the object.

      all_array_storage string, optional

        If provided, override the array storage type of all blocks in the file immediately before writing. Must be one of:

        - `internal`: The default. The array data will be stored in a binary block in the same ASDF file.

        - `external`: Store the data in a binary block in a separate ASDF file.

        - `inline`: Store the data as YAML inline in the tree.

      all_array_compression string, optional

        If provided, set the compression type on all binary blocks in the file. Must be one of:

        - `''` or `None`: No compression.

        - `zlib`: Use zlib compression.

        - `bzp2`: Use bzip2 compression.

        - `lz4`: Use lz4 compression.

        - `input`: Use the same compression as in the file read. If there is no prior file, acts as None.

      pad_blocks float or bool, optional

        Add extra space between blocks to allow for updating of the file. If `False` (default), add no padding (always return 0). If `True`, add a default amount of padding of 10% If a float, it is a factor to multiple content_size by to get the new total size.

      include_block_index bool, optional

        If `False`, don’t include a block index at the end of the file. (Default: `True`) A block index is never written if the file has a streamed block.

      version str, optional

        Update the ASDF Standard version of this AsdfFile before writing.

      auto_inline int, optional

        DEPRECATED. When the number of elements in an array is less than this threshold, store the array as inline YAML, rather than a binary block. This only works on arrays that do not share data with other arrays. Default is the value specified in `asdf.get_config().array_inline_threshold`.