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, codec=<binpickle.codecs.gz.GZ object>)

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)
  • obj – The object to dump.

  • file (str or pathlib.Path) – The file in which to save the object.

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

  • codec (codecs.Codec) – The codec 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, codec=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:
  • filename (str or pathlib.Path) – The path to the file to write.

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

  • codec – The codec to use for encoding buffers. This can be anything that can be passed to binpickle.codecs.make_codec(), or it can be a function that takes a buffer and returns the codec to use for that buffer (to use different codecs for different types or sizes of buffers).

classmethod mappable(filename)

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

classmethod compressed(filename, codec=<binpickle.codecs.gz.GZ object>)

Convenience method to construct a pickler for compressed storage.


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


Close the bin pickler.