This document is for Kombu's development version, which can be significantly different from previous releases. Get the stable docs here: 5.0.

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.

Parameters

  • 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

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.

Return type

Tuple[str, str, str]

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.

Parameters

  • 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

The unserialized data.

Return type

Any

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.

Parameters

  • 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.

Parameters

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.