register_codec#

barecat._api.Barecat.register_codec(exts, encoder, decoder, nonfinal=False)[source]#

Register an encoder and decoder for one or more file extensions.

This allows automatic encoding and decoding (serialization/deserialization) of files based on their extension, used in the dictionary interface, e.g., __getitem__(), __setitem__() and items() methods.

If auto_codec was True in the constructor, then the codecs are already registered by default for the following extensions:

Data formats: - .json — dict/list (stdlib json) - .pkl, .pickle — any object (pickle) - .npy — numpy array - .npz — dict of numpy arrays - .msgpack — any object (requires msgpack-numpy)

Image formats (uses cv2 > PIL > imageio, whichever is available): - .jpg, .jpeg, .png, .bmp, .gif - .tiff, .tif, .webp, .exr

Compression (stackable with other codecs): - .gz, .gzip — gzip - .xz, .lzma — lzma - .bz2 — bzip2

Parameters:

  • exts (list[str]) – List of file extensions to register the codec for.

  • encoder (Callable[[Any], bytes]) – Function to encode data into bytes.

  • decoder (Callable[[bytes], Any]) – Function to decode bytes into data.

  • nonfinal (bool) – If True, other codecs are allowed to be applied afterwards in a nested manner. This is useful for, e.g., compression codecs.

Examples

Simple text encoding:

>>> bc = Barecat('test.barecat', readonly=False)
>>> def encode(data):
...     return data.encode('utf-8')
>>> def decode(data):
...     return data.decode('utf-8')
>>> bc.register_codec(['.txt'], encode, decode)

Or using a codec from a library:

>>> import cv2
>>> bc = Barecat('test.barecat', readonly=False)
>>> def encode_png(data):
...     return cv2.imencode('.png', data)[1].tobytes()
>>> def decode_png(data):
...     return cv2.imdecode(np.frombuffer(data, np.uint8), cv2.IMREAD_UNCHANGED)
>>> bc.register_codec(['.png'], encode_png, decode_png)

Or using a compression library:

>>> import zlib
>>> bc = Barecat('test.barecat', readonly=False)
>>> def encode_zlib(data):
...     return zlib.compress(data)
>>> def decode_zlib(data):
...     return zlib.decompress(data)
>>> bc.register_codec(['.gz'], encode_zlib, decode_zlib, nonfinal=True)

Or pickling:

>>> import pickle
>>> bc = Barecat('test.barecat', readonly=False)
>>> bc.register_codec(['.pkl'], pickle.dumps, pickle.loads)