# 14.2.12. Picklable read-only I/O classes — `MDAnalysis.lib.picklable_file_io`

Provide with an interface for pickling read-only IO file object. These classes are used for further pickling `MDAnalysis.core.universe` in a object composition approach.

class MDAnalysis.lib.picklable_file_io.FileIOPicklable(name, mode='r')

  File object (read-only) that can be pickled.

  This class provides a file-like object (as returned by `open()`, namely `io.FileIO`) that, unlike standard Python file objects, can be pickled. Only read mode is supported.

  When the file is pickled, filename and position of the open file handle in the file are saved. On unpickling, the file is opened by filename, and the file is seeked to the saved position. This means that for a successful unpickle, the original file still has to be accessible with its filename.

  Note

  This class only supports reading files in binary mode. If you need to open a file in text mode, use the `pickle_open()`.

  Parameters:

    - name (str) – either a text or byte string giving the name (and the path if the file isn’t in the current working directory) of the file to be opened.

    - mode (str) – only reading (‘r’) mode works. It exists to be consistent with a wider API.

  Example

      >>> import pickle
      >>> from MDAnalysis.tests.datafiles import PDB
      >>> file = FileIOPicklable(PDB)
      >>> _ = file.readline()
      >>> file_pickled = pickle.loads(pickle.dumps(file))
      >>> print(file.tell(), file_pickled.tell())
      55 55

  See also

  `TextIOPicklable`, `BufferIOPicklable`

  Added in version 2.0.0.

class MDAnalysis.lib.picklable_file_io.BufferIOPicklable(raw)

  A picklable buffer object for read-only FileIO object.

  This class provides a buffered `io.BufferedReader` that can be pickled. Note that this only works in read mode.

  Parameters:

    raw (FileIO object)

  Example

      file = FileIOPicklable('filename')
      buffer_wrapped = BufferIOPicklable(file)

  See also

  `FileIOPicklable`, `TextIOPicklable`

  Added in version 2.0.0.

class MDAnalysis.lib.picklable_file_io.TextIOPicklable(raw)

  Character and line based picklable file-like object.

  This class provides a file-like `io.TextIOWrapper` object that can be pickled. Note that this only works in read mode.

  Parameters:

    raw (FileIO object)

  Example

      file = FileIOPicklable('filename')
      text_wrapped = TextIOPicklable(file)

  See also

  `FileIOPicklable`, `BufferIOPicklable`

  Added in version 2.0.0.

  Changed in version 2.8.0: The raw class instance instead of the class name that is wrapped inside will be serialized. After deserialization, the current position is no longer reset so universe.trajectory[i] is not needed to seek to the original position.

class MDAnalysis.lib.picklable_file_io.BZ2Picklable(name, mode='rb')

  File object (read-only) for bzip2 (de)compression that can be pickled.

  This class provides a file-like object (as returned by `bz2.open()`, namely `bz2.BZ2File`) that, unlike standard Python file objects, can be pickled. Only read mode is supported.

  When the file is pickled, filename and position of the open file handle in the file are saved. On unpickling, the file is opened by filename, and the file is seeked to the saved position. This means that for a successful unpickle, the original file still has to be accessible with its filename.

  Note

  This class only supports reading files in binary mode. If you need to open to open a compressed file in text mode, use `bz2_pickle_open()`.

  Parameters:

    - name (str) – either a text or byte string giving the name (and the path if the file isn’t in the current working directory) of the file to be opened.

    - mode (str) – can only be ‘r’, ‘rb’ to make pickle work.

  Example

      >>> import pickle
      >>> from MDAnalysis.tests.datafiles import XYZ_bz2
      >>> file = BZ2Picklable(XYZ_bz2)
      >>> _ = file.readline()
      >>> file_pickled = pickle.loads(pickle.dumps(file))
      >>> print(file.tell(), file_pickled.tell())
      5 5

  See also

  `FileIOPicklable`, `BufferIOPicklable`, `TextIOPicklable`, `GzipPicklable`

  Added in version 2.0.0.

  Open a bzip2-compressed file.

  If filename is a str, bytes, or PathLike object, it gives the name of the file to be opened. Otherwise, it should be a file object, which will be used to read or write the compressed data.

  mode can be ‘r’ for reading (default), ‘w’ for (over)writing, ‘x’ for creating exclusively, or ‘a’ for appending. These can equivalently be given as ‘rb’, ‘wb’, ‘xb’, and ‘ab’.

  If mode is ‘w’, ‘x’ or ‘a’, compresslevel can be a number between 1 and 9 specifying the level of compression: 1 produces the least compression, and 9 (default) produces the most compression.

  If mode is ‘r’, the input file may be the concatenation of multiple compressed streams.

class MDAnalysis.lib.picklable_file_io.GzipPicklable(name, mode='rb')

  Gzip file object (read-only) that can be pickled.

  This class provides a file-like object (as returned by `gzip.open()`, namely `gzip.GzipFile`) that, unlike standard Python file objects, can be pickled. Only read mode is supported.

  When the file is pickled, filename and position of the open file handle in the file are saved. On unpickling, the file is opened by filename, and the file is seeked to the saved position. This means that for a successful unpickle, the original file still has to be accessible with its filename.

  Note

  This class only supports reading files in binary mode. If you need to open to open a compressed file in text mode, use the `gzip_pickle_open()`.

  Parameters:

    - name (str) – either a text or byte string giving the name (and the path if the file isn’t in the current working directory) of the file to be opened.

    - mode (str) – can only be ‘r’, ‘rb’ to make pickle work.

  Example

      >>> import pickle
      >>> from MDAnalysis.tests.datafiles import MMTF_gz
      >>> file = GzipPicklable(MMTF_gz)
      >>> _ = file.readline()
      >>> file_pickled = pickle.loads(pickle.dumps(file))
      >>> print(file.tell(), file_pickled.tell())
      1218 1218

  See also

  `FileIOPicklable`, `BufferIOPicklable`, `TextIOPicklable`, `BZ2Picklable`

  Added in version 2.0.0.

  Constructor for the GzipFile class.

  At least one of fileobj and filename must be given a non-trivial value.

  The new class instance is based on fileobj, which can be a regular file, an io.BytesIO object, or any other object which simulates a file. It defaults to None, in which case filename is opened to provide a file object.

  When fileobj is not None, the filename argument is only used to be included in the gzip file header, which may include the original filename of the uncompressed file. It defaults to the filename of fileobj, if discernible; otherwise, it defaults to the empty string, and in this case the original filename is not included in the header.

  The mode argument can be any of ‘r’, ‘rb’, ‘a’, ‘ab’, ‘w’, ‘wb’, ‘x’, or ‘xb’ depending on whether the file will be read or written. The default is the mode of fileobj if discernible; otherwise, the default is ‘rb’. A mode of ‘r’ is equivalent to one of ‘rb’, and similarly for ‘w’ and ‘wb’, ‘a’ and ‘ab’, and ‘x’ and ‘xb’.

  The compresslevel argument is an integer from 0 to 9 controlling the level of compression; 1 is fastest and produces the least compression, and 9 is slowest and produces the most compression. 0 is no compression at all. The default is 9.

  The optional mtime argument is the timestamp requested by gzip. The time is in Unix format, i.e., seconds since 00:00:00 UTC, January 1, 1970. If mtime is omitted or None, the current time is used. Use mtime = 0 to generate a compressed stream that does not depend on creation time.

MDAnalysis.lib.picklable_file_io.pickle_open(name, mode='rt')

  Open file and return a stream with pickle function implemented.

  This function returns a FileIOPicklable object wrapped in a BufferIOPicklable class when given the “rb” reading mode, or a FileIOPicklable object wrapped in a TextIOPicklable class with the “r” or “rt” reading mode. It can be used as a context manager, and replace the built-in `open()` function in read mode that only returns an unpicklable file object. In order to serialize a `MDAnalysis.core.Universe`, this function can used to open trajectory/topology files. This object composition is more flexible and easier than class inheritance to implement pickling for new readers.

  Note

  Can be only used with read mode.

  Parameters:

    - name (str) – either a text or byte string giving the name (and the path if the file isn’t in the current working directory) of the file to be opened.

    - mode ({'r', 'rt', 'rb'} (optional)) – ‘r’: open for reading in text mode; ‘rt’: read in text mode (default); ‘rb’: read in binary mode;

  Returns:

    stream-like object – when mode is ‘r’ or ‘rt’, returns TextIOPicklable; when mode is ‘rb’, returns BufferIOPicklable

  Return type:

    BufferIOPicklable or TextIOPicklable

  Raises:

    ValueError – if mode is not one of the allowed read modes

  Examples

  open as context manager:

      with pickle_open('filename') as f:
          line = f.readline()

  open as function:

      f = pickle_open('filename')
      line = f.readline()
      f.close()

  See also

  `MDAnalysis.lib.util.anyopen()`, `io.open()`

  Added in version 2.0.0.

MDAnalysis.lib.picklable_file_io.bz2_pickle_open(name, mode='rb')

  Open a bzip2-compressed file in binary or text mode with pickle function implemented.

  This function returns a BZ2Picklable object when given the “rb” or “r” reading mode, or a BZ2Picklable object wrapped in a TextIOPicklable class with the “rt” reading mode. It can be used as a context manager, and replace the built-in `bz2.open()` function in read mode that only returns an unpicklable file object.

  Note

  Can be only used with read mode.

  Parameters:

    - name (str) – either a text or byte string giving the name (and the path if the file isn’t in the current working directory) of the file to be opened.

    - mode ({'r', 'rt', 'rb'} (optional)) – ‘r’: open for reading in binary mode; ‘rt’: read in text mode; ‘rb’: read in binary mode; (default)

  Returns:

    stream-like object – when mode is ‘rt’, returns TextIOPicklable; when mode is ‘r’ or ‘rb’, returns BZ2Picklable

  Return type:

    BZ2Picklable or TextIOPicklable

  Raises:

    ValueError – if mode is not one of the allowed read modes

  Examples

  open as context manager:

      with bz2_pickle_open('filename') as f:
          line = f.readline()

  open as function:

      f = bz2_pickle_open('filename')
      line = f.readline()
      f.close()

  See also

  `io.open()`, `bz2.open()`, `MDAnalysis.lib.util.anyopen()`, `MDAnalysis.lib.picklable_file_io.pickle_open()`, `MDAnalysis.lib.picklable_file_io.gzip_pickle_open()`

  Added in version 2.0.0.

MDAnalysis.lib.picklable_file_io.gzip_pickle_open(name, mode='rb')

  Open a gzip-compressed file in binary or text mode with pickle function implemented.

  This function returns a GzipPicklable object when given the “rb” or “r” reading mode, or a GzipPicklable object wrapped in a TextIOPicklable class with the “rt” reading mode. It can be used as a context manager, and replace the built-in `gzip.open()` function in read mode that only returns an unpicklable file object.

  Note

  Can be only used with read mode.

  Parameters:

    - name (str) – either a text or byte string giving the name (and the path if the file isn’t in the current working directory) of the file to be opened.

    - mode ({'r', 'rt', 'rb'} (optional)) – ‘r’: open for reading in binary mode; ‘rt’: read in text mode; ‘rb’: read in binary mode; (default)

  Returns:

    stream-like object – when mode is ‘rt’, returns TextIOPicklable; when mode is ‘r’ or ‘rb’, returns GzipPicklable

  Return type:

    GzipPicklable or TextIOPicklable

  Raises:

    ValueError – if mode is not one of the allowed read modes

  Examples

  open as context manager:

      with gzip_pickle_open('filename') as f:
          line = f.readline()

  open as function:

      f = gzip_pickle_open('filename')
      line = f.readline()
      f.close()

  See also

  `io.open()`, `gzip.open()`, `MDAnalysis.lib.util.anyopen()`, `MDAnalysis.lib.picklable_file_io.pickle_open()`, `MDAnalysis.lib.picklable_file_io.bz2_pickle_open()`

  Added in version 2.0.0.

Added in version 2.0.0.