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)

Experimental API . 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)

Experimental API . 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)

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

open_filename(filename, *args, **kw)

Experimental API . Open a file/URL with or without compression

Takes the same arguments as built-in open and returns a file-like object. However, filename can also be a file-like object itself, in which case it is simple returned. Also, if filename is a string that begins with “http:”, then it is interpreted as an URL.

If the file is opened for input, compression is checked for and handled automatically. If the file is opened for output, the compress keyword can be used to force or suppress compression. If the keyword is not given, then compression will occur if the file name ends in the appropriate suffix (e.g. ‘.gz’). If compressing, you can supply args compatible with the appropriate “open” function (e.g. gzip.open).

‘~’ is expanded unless the expand_user keyword is specified as False.

Uncompressed non-binary files will be opened for reading with universal newline support.

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

Experimental API . Returns list of known formats.

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

Experimental API . 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)