API Docs¶

Encoder¶

class quickle.Encoder(*, memoize=True, collect_buffers=False, registry=None, write_buffer_size=4096)¶

A quickle encoder.

Creating an Encoder and calling the Encoder.dumps method multiple times is more efficient than calling quickle.dumps multiple times.

Parameters

  • memoize (bool, optional) – Whether to enable memoization. If True (default), any duplicate objects will only be serialized once. Disabling memoization can be more efficient for objects unlikely to contain duplicate values, but self-referential objects will then fail to serialize.

  • collect_buffers (bool, optional) – Whether to collect out-of-band buffers. If True, the return value of Encoder.dumps will be the serialized bytes, and a list of any PickleBuffer objects found (or None if none are found).

  • registry (list or dict, optional) – A registry of user-defined types this decoder instance should support. Can be either a list of types (recommended), or a dict mapping the type to a unique positive integer. Note that for deserialization to be successful, the registry should match that of the corresponding Decoder.

  • write_buffer_size (int, optional) – The size of the internal static write buffer.

dumps(*, memoize=None, collect_buffers=None)¶

Serialize an object to bytes.

Parameters

  • memoize (bool, optional) – Whether to enable memoization. Defaults to the value set on the encoder. If True, any duplicate objects will only be serialized once. Disabling memoization can be more efficient for objects unlikely to contain duplicate values, but self-referential objects will then fail to serialize.

  • collect_buffers (bool, optional) – Whether to collect out-of-band buffers. Defaults to the value set on the encoder. If True, the return value will be the serialized object, and a list of any PickleBuffer objects found (or None if none are found).

Returns

  • data (bytes) – The serialized object

  • buffers (list of PickleBuffer or None, optional) – If collect_buffers is True, a list of out-of-band buffers will also be returned (or None if no buffers are found). Not returned if collect_buffers is False

Decoder¶

class quickle.Decoder(registry=None)¶

A quickle decoder.

Creating a Decoder and calling the Decoder.loads method multiple times is more efficient than calling quickle.loads multiple times.

Parameters

registry (list or dict, optional) – A registry of user-defined types this encoder instance should support. Can be either a list of types (recommended), or a dict mapping positive integers to each type. Note that for deserialization to be successful, the registry should match that of the corresponding Encoder.

loads(data, *, buffers=None)¶

Deserialize an object from bytes.

Parameters

  • data (bytes) – The serialized data

  • buffers (iterable of bytes, optional) – An iterable of out-of-band buffers generated by passing collect_buffers=True to the corresponding Encoder.dumps call.

Returns

obj – The deserialized object

Return type

object

Struct¶

class quickle.Struct¶

A base class for defining efficient serializable objects.

Fields are defined using type annotations. Fields may optionally have default values, which result in keyword parameters to the constructor. Note that mutable default values are deepcopied in the constructor to prevent accidental sharing.

Structs automatically define __init__, __eq__, __repr__, and __copy__ methods. Additional methods can be defined on the class as needed. Note that __init__/__new__ cannot be overridden, but other methods can. A tuple of the field names is available on the class via the __struct_fields__ attribute if needed.

Examples

Here we define a new Struct type for describing a dog. It has three fields; two required and one optional.

>>> class Dog(Struct):
...     name: str
...     breed: str
...     is_good_boy: bool = True
...
>>> Dog('snickers', breed='corgi')
Dog(name='snickers', breed='corgi', is_good_boy=True)

To serialize or deserialize Struct types, they need to be registered with an Encoder and Decoder through the registry argument.

>>> enc = Encoder(registry=[Dog])
>>> dec = Decoder(registry=[Dog])
>>> data = enc.dumps(Dog('snickers', 'corgi'))
>>> dec.loads(data)
Dog(name='snickers', breed='corgi', is_good_boy=True)

PickleBuffer¶

class quickle.PickleBuffer¶

Wrapper for potentially out-of-band buffers

raw()¶

Return a memoryview of the raw memory underlying this buffer. Will raise BufferError is the buffer isn’t contiguous.

release()¶

Release the underlying buffer exposed by the PickleBuffer object.

Functions¶

quickle.dumps(obj, *, memoize=True, collect_buffers=False, registry=None)¶

Serialize an object to bytes.

Parameters

  • memoize (bool, optional) – Whether to enable memoization. If True (default), any duplicate objects will only be serialized once. Disabling memoization can be more efficient for objects unlikely to contain duplicate values, but self-referential objects will then fail to serialize.

  • collect_buffers (bool, optional) – Whether to collect out-of-band buffers. If True, the return value will be the serialized bytes, and a list of any PickleBuffer objects found (or None if none are found).

  • registry (list or dict, optional) – A registry of user-defined types to support. Can be either a list of types (recommended), or a dict mapping the type to a unique positive integer. Note that for deserialization to be successful, the registry should match that of the corresponding loads.

Returns

  • data (bytes) – The serialized object

  • buffers (list of PickleBuffer or None, optional) – If collect_buffers is True, a list of out-of-band buffers will also be returned (or None if no buffers are found). Not returned if collect_buffers is False

See also

Encoder.dumps

quickle.loads(data, *, buffers=None, registry=None)¶

Deserialize an object from bytes.

Parameters

  • buffers (iterable of bytes, optional) – An iterable of out-of-band buffers generated by passing collect_buffers=True to the corresponding dumps call.

  • registry (list or dict, optional) – A registry of user-defined types to support. Can be either a list of types (recommended), or a dict mapping positive integers to each type. Note that for deserialization to be successful, the registry should match that of the corresponding dumps.

Returns

obj – The deserialized object.

Return type

object

See also

Decoder.loads

Exceptions¶

exception quickle.QuickleError¶

Bases: Exception

Base class for all Quickle protocol exceptions

exception quickle.EncodingError¶

Bases: quickle.QuickleError

A protocol error occurred while encoding an object

exception quickle.DecodingError¶

Bases: quickle.QuickleError

A protocol error occurred while decoding an object