This document describes the current stable version of Kombu (5.3). For development docs, go here.

Message Serialization - kombu.serialization

Serialization utilities.

Overview

Centralized support for encoding/decoding of data structures. Contains json, pickle, msgpack, and yaml serializers.

Optionally installs support for YAML if the PyYAML package is installed.

Optionally installs support for msgpack if the msgpack-python package is installed.

Exceptions

exception kombu.serialization.SerializerNotInstalled[source]

Support for the requested serialization type is not installed.

Serialization

kombu.serialization.dumps(data, serializer=None)

Encode data.

Serialize a data structure into a string suitable for sending as an AMQP message body.

Arguments:

data (List, Dict, str): The message data to send.

serializer (str): An optional string representing

the serialization method you want the data marshalled into. (For example, json, raw, or pickle).

If None (default), then json will be used, unless data is a str or unicode object. In this latter case, no serialization occurs as it would be unnecessary.

Note that if serializer is specified, then that serialization method will be used even if a str or unicode object is passed in.

returns:
  • Tuple[str, str, str] (A three-item tuple containing the)

  • content type (e.g., application/json), content encoding, (e.g.,

  • utf-8) and a string containing the serialized data.

raises SerializerNotInstalled:

If the serialization method: requested is not available.

kombu.serialization.loads(data, content_type, content_encoding, accept=None, force=False, _trusted_content=frozenset({'application/data', 'application/text'}))

Decode serialized data.

Deserialize a data stream as serialized using dumps based on content_type.

Arguments:

data (bytes, buffer, str): The message data to deserialize.

content_type (str): The content-type of the data.

(e.g., application/json).

content_encoding (str): The content-encoding of the data.

(e.g., utf-8, binary, or us-ascii).

accept (Set): List of content-types to accept.

raises ContentDisallowed:

If the content-type is not accepted.:

returns:

Any

rtype:

The unserialized data.

kombu.serialization.raw_encode(data)[source]

Special case serializer.

Registry

kombu.serialization.register(name, encoder, decoder, content_type, content_encoding='utf-8')

Register a new encoder/decoder.

Arguments:

name (str): A convenience name for the serialization method.

encoder (callable): A method that will be passed a python data

structure and should return a string representing the serialized data. If None, then only a decoder will be registered. Encoding will not be possible.

decoder (Callable): A method that will be passed a string

representing serialized data and should return a python data structure. If None, then only an encoder will be registered. Decoding will not be possible.

content_type (str): The mime-type describing the serialized

structure.

content_encoding (str): The content encoding (character set) that

the decoder method will be returning. Will usually be utf-8, us-ascii, or binary.

kombu.serialization.unregister(name)

Unregister registered encoder/decoder.

Arguments:

name (str): Registered serialization method name.

raises SerializerNotInstalled:

If a serializer by that name: cannot be found.

kombu.serialization.registry = <kombu.serialization.SerializerRegistry object>

Global registry of serializers/deserializers.