I/O Registry (
The I/O registry is only meant to be used directly by users who want
to define their own custom readers/writers. Users who want to find
out more about what built-in formats are supported by
Table by default should see
Unified File Read/Write Interface. No built-in formats are currently defined for
NDData, but this will be added in
This section demonstrates how to create a custom reader/writer. A reader is
written as a function that can take any arguments except
format (which is
needed when manually specifying the format — see below) and returns an
instance of the
NDData classes (or subclasses).
Here we assume that we are trying to write a reader/writer for the
from astropy.table import Table def my_table_reader(filename, some_option=1): # Read in the table by any means necessary return table # should be an instance of Table
Such a function can then be registered with the I/O registry:
from astropy.io import registry registry.register_reader('my-table-format', Table, my_table_reader)
where the first argument is the name of the format, the second argument is the class that the function returns an instance for, and the third argument is the reader itself.
We can then read in a table with:
d = Table.read('my_table_file.mtf', format='my-table-format')
In practice, it would be nice to have the
read method automatically
identify that this file is in the
my-table-format format, so we can
construct a function that can recognize these files, which we refer to here as
an identifier function.
An identifier function should take a first argument that is a string
which indicates whether the identifier is being called from
write, and should then accept an arbitrary number of positional and keyword
**kwargs, which are the arguments passed to
In the above case, we can write a function that only looks at
filenames (but in practice, this function could even look at the first few
bytes of the file, for example). The only requirement for the identifier
function is that it return a boolean indicating whether the input matches that
expected for the format. In our example, we want to automatically recognize
files with filenames ending in
.mtf as being in the
import os def identify_mtf(origin, *args, **kwargs): return (isinstance(args, str) and os.path.splitext(args.lower()) == '.mtf')
Identifier functions should be prepared for arbitrary input — in particular, the first argument may not be a filename or file object, so it should not assume that this is the case.
We then register this identifier function, similarly to the reader function:
registry.register_identifier('my-table-format', Table, identify_mtf)
Having registered this function, we can then do:
t = Table.read('catalog.mtf')
If multiple formats match the current input, then an exception is
raised, and similarly if no format matches the current input. In that
case, the format should be explicitly given with the
It is also possible to create custom writers. To go with our custom reader above, we can write a custom writer:
def my_table_writer(table, filename, overwrite=False): ... # Write the table out to a file return ... # generally None, but other values are not forbidden.
Writer functions should take a dataset object (either an instance of the
classes or subclasses), and any number of subsequent positional and keyword
arguments — although as for the reader, the
format keyword argument cannot
We then register the writer:
registry.register_writer('my-custom-format', Table, my_table_writer)
We can write the table out to a file:
Since we have already registered the identifier function, we can also do:
Register a reader function.
Register a table writer function.
Associate an identifier function with a specific data type.
Loop through identifiers to see which formats match.
Get reader for
Get writer for
Read in data.
Write out data.
Get the list of registered I/O formats as a Table.
Contextmanager to disable documentation updates when registering reader and writer.
Custom error for registry clashes.
Descriptor class for creating read() and write() methods in unified I/O.
Base class for the worker object used in unified read() or write() methods.