tessl/pypi-asdf
Python implementation of the Advanced Scientific Data Format (ASDF) Standard
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
file-operations.mddocs/
File Operations
Core file handling functionality for creating, reading, writing, and managing ASDF files. Provides both high-level convenience functions and comprehensive low-level file management through the AsdfFile class.
Capabilities
AsdfFile Class
Main class for representing and manipulating ASDF files, providing complete control over file creation, reading, writing, and validation.
class AsdfFile:
def __init__(self, tree=None, uri=None, extensions=None, version=None,
ignore_unrecognized_tag=False, memmap=False, lazy_load=True,
custom_schema=None):
"""
Create a new AsdfFile object.
Parameters:
- tree (dict or AsdfFile, optional): Main tree data conforming to ASDF schema
- uri (str, optional): URI for resolving relative references
- extensions (object, optional): Additional extensions to use when reading and writing
- version (str, optional): ASDF core schemas version
- ignore_unrecognized_tag (bool, optional): When True, do not raise warnings for unrecognized tags (default: False)
- memmap (bool, optional): When True, attempt to memmap underlying data arrays (default: False)
- lazy_load (bool, optional): When True, data arrays will only be loaded lazily (default: True)
- custom_schema (str, optional): Path to custom schema file for secondary validation
"""
# Properties
@property
def version(self):
"""Get this AsdfFile's ASDF core schemas version."""
@version.setter
def version(self, value):
"""Set this AsdfFile's ASDF core schemas version."""
@property
def version_string(self):
"""Get this AsdfFile's ASDF core schemas version as a string."""
@property
def extensions(self):
"""Get the list of user extensions that are enabled for use with this AsdfFile."""
@extensions.setter
def extensions(self, value):
"""Set the list of user extensions that are enabled for use with this AsdfFile."""
@property
def extension_manager(self):
"""Get the ExtensionManager for this AsdfFile."""
@property
def file_format_version(self):
"""Get the file format version."""
@property
def uri(self):
"""Get the URI associated with the AsdfFile."""
@property
def tree(self):
"""Get/set the tree of data in the ASDF file."""
@tree.setter
def tree(self, tree):
"""Set the tree of data in the ASDF file."""
@property
def comments(self):
"""Get the comments after the header, before the tree."""
# File Operations
def close(self):
"""Close the file handles associated with the asdf.AsdfFile."""
def copy(self):
"""Create a copy of the AsdfFile."""
def update(self, all_array_storage=NotSet, all_array_compression=NotSet,
compression_kwargs=NotSet, pad_blocks=False, include_block_index=True,
version=None):
"""
Update the file on disk in place.
Parameters:
- all_array_storage (str, optional): Override array storage type (internal/external/inline)
- all_array_compression (str, optional): Set compression type (zlib/bzp2/lz4/input/None)
- compression_kwargs (dict, optional): Compression keyword arguments
- pad_blocks (float or bool, optional): Add extra space between blocks (default: False)
- include_block_index (bool, optional): Include block index at end of file (default: True)
- version (str, optional): Update ASDF core schemas version before writing
"""
def write_to(self, fd, all_array_storage=NotSet, all_array_compression=NotSet,
compression_kwargs=NotSet, pad_blocks=False, include_block_index=True,
version=None):
"""
Write the ASDF file to the given file-like object.
Parameters:
- fd (str or file-like): File path or file-like object to write to
- all_array_storage (str, optional): Override array storage type (internal/external/inline)
- all_array_compression (str, optional): Set compression type (zlib/bzp2/lz4/input/None)
- compression_kwargs (dict, optional): Compression keyword arguments
- pad_blocks (float or bool, optional): Add extra space between blocks (default: False)
- include_block_index (bool, optional): Include block index at end of file (default: True)
- version (str, optional): Update ASDF core schemas version before writing
"""
# URI and Reference Operations
def resolve_uri(self, uri):
"""
Resolve a (possibly relative) URI against the URI of this ASDF file.
Parameters:
- uri (str): An absolute or relative URI to resolve
Returns:
str: The resolved URI
"""
def open_external(self, uri, **kwargs):
"""
Open an external ASDF file from the given URI.
Parameters:
- uri (str): An absolute or relative URI to resolve against this ASDF file
Returns:
AsdfFile: The external ASDF file
"""
def make_reference(self, path=None):
"""
Make a new reference to a part of this file's tree.
Parameters:
- path (list of str and int, optional): Parts of path pointing to item in tree
Returns:
reference: A reference object
"""
def find_references(self):
"""Find all external JSON References in the tree and convert them to Reference objects."""
def resolve_references(self):
"""Find all external JSON References in tree, load external content, and place in tree."""
# Array Operations
def set_array_storage(self, arr, array_storage):
"""
Set the block type to use for the given array data.
Parameters:
- arr (numpy.ndarray): The array to set
- array_storage (str): Must be one of: internal, external, inline
"""
def get_array_storage(self, arr):
"""Get the block type for the given array data."""
def set_array_compression(self, arr, compression, **compression_kwargs):
"""
Set the compression to use for the given array data.
Parameters:
- arr (numpy.ndarray): The array to set
- compression (str or None): Must be one of: '', None, zlib, bzp2, lz4, input
"""
def get_array_compression(self, arr):
"""Get the compression type for the given array data."""
def get_array_compression_kwargs(self, arr):
"""Get compression keyword arguments for the array."""
def set_array_save_base(self, arr, save_base):
"""
Set the save_base option for arr.
Parameters:
- arr (numpy.ndarray): The array
- save_base (bool or None): If None, default from config is used
"""
def get_array_save_base(self, arr):
"""
Get the save_base option for arr.
Parameters:
- arr (numpy.ndarray): The array
Returns:
bool or None: The save_base setting
"""
# Schema and Validation Operations
def validate(self):
"""Validate the current state of the tree against the ASDF schema."""
def fill_defaults(self):
"""Fill in any values missing in tree using default values from schema."""
def remove_defaults(self):
"""Remove any values in tree that are same as default values in schema."""
def schema_info(self, key="description", path=None, preserve_list=True, refresh_extension_manager=NotSet):
"""
Get a nested dictionary of the schema information for a given key.
Parameters:
- key (str): The key to look up (default: "description")
- path (str or AsdfSearchResult): Dot-separated path or AsdfSearchResult object
- preserve_list (bool): If True, preserve lists, otherwise turn into dicts
- refresh_extension_manager (bool): Deprecated parameter
"""
# History Operations
def add_history_entry(self, 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
"""
def get_history_entries(self):
"""
Get a list of history entries from the file object.
Returns:
list: A list of history entries
"""
# Information and Search Operations
def info(self, max_rows=24, max_cols=120,
show_values=True, refresh_extension_manager=NotSet):
"""
Print a rendering of this file's tree to stdout.
Parameters:
- max_rows (int, tuple, or None, optional): Maximum number of lines to print
- max_cols (int or None, optional): Maximum length of line to print
- show_values (bool, optional): Set to False to disable display of primitive values
"""
def search(self, key=NotSet, type_=NotSet, value=NotSet, filter_=None):
"""
Search this file's tree.
Parameters:
- key (NotSet, str, or any): Search query that selects nodes by dict key or list index
- type_ (NotSet, str, or type): Search query that selects nodes by type
- value (NotSet, str, or any): Search query that selects nodes by value
- filter_ (callable): Callable that filters nodes by arbitrary criteria
Returns:
AsdfSearchResult: The result of the search
"""
# Dictionary-like Interface
def keys(self):
"""Return the keys of the tree."""
def __getitem__(self, key):
"""Get an item from the tree."""
def __setitem__(self, key, value):
"""Set an item in the tree."""
def __contains__(self, item):
"""Check if item is in the tree."""
# Context Manager Support
def __enter__(self):
"""Enter context manager."""
def __exit__(self, type_, value, traceback):
"""Exit context manager."""File Opening
Open existing ASDF files with comprehensive options for validation, extensions, and performance optimization.
def open(fd, uri=None, mode=None, validate_checksums=False, extensions=None,
ignore_unrecognized_tag=False, _force_raw_types=False, memmap=False,
lazy_tree=NotSet, lazy_load=True, custom_schema=None,
strict_extension_check=False, ignore_missing_extensions=False):
"""
Open an existing ASDF file.
Parameters:
- fd: File descriptor, path, or file-like object
- uri (str, optional): URI for resolving relative references
- mode (str, optional): File open mode
- validate_checksums (bool): Validate array checksums on read (default: False)
- extensions (Extension or list, optional): Additional extensions for custom types
- ignore_unrecognized_tag (bool): Don't warn for unrecognized tags (default: False)
- _force_raw_types (bool): Internal parameter for forcing raw types (default: False)
- memmap (bool): Memory-map arrays when possible (default: False)
- lazy_tree (NotSet): Deprecated parameter (default: NotSet)
- lazy_load (bool): Load arrays lazily when accessed (default: True)
- custom_schema (str, optional): Path to custom validation schema
- strict_extension_check (bool): Strict extension validation (default: False)
- ignore_missing_extensions (bool): Ignore missing extension warnings (default: False)
Returns:
AsdfFile: The opened ASDF file object
"""Simple File Loading
Convenience function for loading ASDF files directly to Python objects without AsdfFile wrapper.
def load(fp, *, uri=None, validate_checksums=False, extensions=None,
custom_schema=None):
"""
Load object tree from ASDF file.
Parameters:
- fp: File path or file-like object
- uri (str, optional): URI for resolving relative references
- validate_checksums (bool): Validate array checksums
- extensions (Extension or list, optional): Additional extensions
- custom_schema (str, optional): Path to custom validation schema
Returns:
Object tree (typically dict)
"""Simple File Writing
Convenience function for writing Python objects directly to ASDF files.
def dump(tree, fp, *, version=None, extensions=None, all_array_storage=NotSet,
all_array_compression=NotSet, compression_kwargs=NotSet, pad_blocks=False,
custom_schema=None):
"""
Serialize object tree to ASDF file.
Parameters:
- tree: Object tree to serialize
- fp: File path or file-like object
- version (str, optional): ASDF version to write
- extensions (Extension or list, optional): Additional extensions
- all_array_storage (str, optional): Array storage mode ('internal', 'external')
- all_array_compression (str, optional): Compression algorithm
- compression_kwargs (dict, optional): Compression-specific options
- pad_blocks (bool): Pad blocks for improved streaming
- custom_schema (str, optional): Path to custom validation schema
"""Usage Examples
Basic File Creation
import asdf
import numpy as np
# Create data
data = {
"arrays": {
"data": np.random.random((1000, 1000)),
"mask": np.zeros(1000, dtype=bool)
},
"metadata": {
"title": "My Dataset",
"version": "1.0"
}
}
# Create and write file
af = asdf.AsdfFile(data)
af.write_to("dataset.asdf")File Reading with Memory Mapping
# Open with memory mapping for large arrays
with asdf.open("dataset.asdf", memmap=True) as af:
# Access data without loading into memory
print(af.tree["arrays"]["data"].shape)
# Only load when needed
subset = af.tree["arrays"]["data"][:100, :100]Validation and Schema Checking
# Open with validation
af = asdf.AsdfFile(tree)
af.validate() # Validate against standard schema
# Write with custom validation
af.write_to("output.asdf", custom_schema="my_schema.json")Working with References
# Resolve external references
af.resolve_references()
# Find all references in tree
refs = af.find_references()
print(f"Found {len(refs)} references")Install with Tessl CLI
npx tessl i tessl/pypi-asdf