Writing BinPickle Files

The easy, single-function entry point for saving data is binpickle.dump():

from binpickle import dump
dump(obj, 'file.bpk')

The dump Function

binpickle.dump(obj, file, *, mappable=False, codecs=['gzip'])

Dump an object to a BinPickle file. This is a convenience wrapper around BinPickler.

To save with default compression for storage or transport:

dump(obj, 'file.bpk')

To save in a file optimized for memory-mapping:

dump(obj, 'file.bpk', mappable=True)

Parameters:

• obj (object) – The object to dump.

• file (str | PathLike[str]) – The file in which to save the object.

• mappable (bool) – If True, save for memory-mapping. codec is ignored in this case.

• codecs (list[Codec | str | dict[str, str | bool | int | float | None] | Callable[[Buffer], Codec | str | dict[str, str | bool | int | float | None] | None]]) – The codecs to use to compress the data, when not saving for memory-mapping.

The BinPickler Class

For full control over the serialization process, you can directly use the binpickle.BinPickler backend class.

class binpickle.BinPickler(filename, *, align=False, codecs=None)

Save an object into a binary pickle file. This is like pickle.Pickler, except it works on file paths instead of byte streams.

A BinPickler is also a context manager that closes itself when exited:

with BinPickler('file.bpk') as bpk:
    bpk.dump(obj)

Only one object can be dumped to a BinPickler. Other methods are exposed for manually constructing BinPickle files but their use is highly discouraged.

Parameters:

• filename (str | PathLike[str]) – The path to the file to write.

• align (bool) – If True, align buffers to the page size.

• codecs (list[Codec | Callable[[Buffer], Codec | str | dict[str, str | bool | int | float | None] | None]]) –

  The list of codecs to use for encoding buffers. The codecs are applied in sequence to encode a buffer, and in reverse order to decode the buffer. There are 4 ways to specify a codec:

  • A numcodecs.abc.Codec instance.

  • A dictionary specifying a codec configuration, suitable for use by numcodecs.get_config().

  • A string, which is used as a codec ID to look up the codec (the id field recognized by get_config())

  • A function that takes a buffer and returns any of the above (or None, to skip the step for that buffer), allowing encoding to vary from buffer to buffer.

classmethod mappable(filename)

Convenience method to construct a pickler for memory-mapped use.

Parameters:

filename (str | PathLike[str]) –

classmethod compressed(filename, codec='gzip')

Convenience method to construct a pickler for compressed storage.

Parameters:

• filename (str | PathLike[str]) –

• codec (Codec | str | dict[str, str | bool | int | float | None] | Callable[[Buffer], Codec | str | dict[str, str | bool | int | float | None] | None]) –

dump(obj)

Dump an object to the file. Can only be called once.

Parameters:

obj (object) –

Return type:

None

close()

Close the bin pickler.

Return type:

None