13.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')[source]¶

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

>>> file = FileIOPicklable(PDB)
>>> file.readline()
>>> file_pickled = pickle.loads(pickle.dumps(file))
>>> print(file.tell(), file_pickled.tell())
    55 55

See also

TextIOPicklable, BufferIOPicklable

New in version 2.0.0.

class MDAnalysis.lib.picklable_file_io.BufferIOPicklable(raw)[source]¶

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

New in version 2.0.0.

class MDAnalysis.lib.picklable_file_io.TextIOPicklable(raw)[source]¶

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.

Note

After pickling, the current position is reset. universe.trajectory[i] has to be used to return to its original frame.

Parameters:	raw (FileIO object) –

Example

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

See also

FileIOPicklable, BufferIOPicklable

New in version 2.0.0.

class MDAnalysis.lib.picklable_file_io.BZ2Picklable(name, mode='rb')[source]¶

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

>>> file = BZ2Picklable(XYZ_bz2)
>>> file.readline()
>>> file_pickled = pickle.loads(pickle.dumps(file))
>>> print(file.tell(), file_pickled.tell())
    5 5

New in version 2.0.0.

class MDAnalysis.lib.picklable_file_io.GzipPicklable(name, mode='rb')[source]¶

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

>>> file = GzipPicklable(MMTF_gz)
>>> file.readline()
>>> file_pickled = pickle.loads(pickle.dumps(file))
>>> print(file.tell(), file_pickled.tell())
    1218 1218

New in version 2.0.0.

MDAnalysis.lib.picklable_file_io.pickle_open(name, mode='rt')[source]¶

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()

New in version 2.0.0.

MDAnalysis.lib.picklable_file_io.bz2_pickle_open(name, mode='rb')[source]¶

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()

New in version 2.0.0.

MDAnalysis.lib.picklable_file_io.gzip_pickle_open(name, mode='rb')[source]¶

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()

New in version 2.0.0.

13.2.12. Picklable read-only I/O classes — MDAnalysis.lib.picklable_file_io¶

13.2.12. Picklable read-only I/O classes — `MDAnalysis.lib.picklable_file_io`¶