io: Manage file formats that can be opened and saved

The io module keeps track of the functions that can open and save data in various formats.

I/O sources and destinations are specified as filenames, and the appropriate open or export function is found by deducing the format from the suffix of the filename. An additional compression suffix, i.e., .gz, indicates that the file is or should be compressed.

All data I/O is in binary.

register_format(format_name, category, extensions, nicknames=None, *, mime=(), reference=None, dangerous=None, icon=None, encoding=None, synopsis=None, **kw)

Register file format’s I/O functions and meta-data

Parameters:
  • format_name – format’s name
  • category – says what kind of data the should be classified as.
  • extensions – is a sequence of filename suffixes starting with a period. If the format doesn’t open from a filename (e.g., PDB ID code), then extensions should be an empty sequence.
  • nicknames – abbreviated names for the format. If not given, it defaults to a lowercase version of the format name.
  • mime – is a sequence of mime types, possibly empty.
  • reference – a URL link to the specification.
  • dangerous – should be True for formats that can write/delete a users’s files. False by default except for the SCRIPT category.

Todo

possibly break up in to multiple functions

open_data(session, filespec, format=None, name=None, **kw)

open a (compressed) file

Parameters:
  • filespec – filename
  • format – file as if it has the given format
  • name – optional name used to identify data source

If a file format requires a filename, then compressed files are uncompressed into a temporary file before calling the open function.

open_multiple_data(session, filespecs, format=None, name=None, **kw)

Open one or more files, including handling formats where multiple files contribute to a single model, such as image stacks.

formats(open=True, export=True, source_is_file=False)

Returns list of known formats.

deduce_format(filename, has_format=None, open=True, save=False, no_raise=False)

Figure out named format associated with filename. If open is True then the format must have an open method. If save is True then the format must have a save method.

Return tuple of deduced format, the unmangled filename, and the compression format (if present).

Example:

io.register_format("mmCIF", "Molecular structure",
    (".cif",), ("mmcif", "cif"),
    mime=("chemical/x-cif", "chemical/x-mmcif"),
    reference="http://mmcif.wwpdb.org/",
    requires_seeking=True, open_func=open_mmCIF)