API Reference

base64

Utilities to encode and decode Base64.

Added in version 1.10.

oslo_serialization.base64.decode_as_bytes(encoded)

Decode a Base64 encoded string.

Parameters:

encoded – bytes or text Base64 encoded string to be decoded

Returns:

decoded bytes string (bytes)

Use decode_as_text() to get the decoded string as text.

A TypeError is raised if the input is invalid (or incorrectly padded).

oslo_serialization.base64.decode_as_text(encoded, encoding='utf-8')

Decode a Base64 encoded string.

Decode the Base64 string and then decode the result from encoding (UTF-8 by default).

Parameters:

encoded – bytes or text Base64 encoded string to be decoded

Returns:

decoded text string (bytes)

Use decode_as_bytes() to get the decoded string as bytes.

oslo_serialization.base64.encode_as_bytes(s, encoding='utf-8')

Encode a string using Base64.

If s is a text string, first encode it to encoding (UTF-8 by default).

Parameters:

  • s – bytes or text string to be encoded

  • encoding – encoding used to encode s if it’s a text string

Returns:

Base64 encoded byte string (bytes)

Use encode_as_text() to get the Base64 encoded string as text.

oslo_serialization.base64.encode_as_text(s, encoding='utf-8')

Encode a string using Base64.

If s is a text string, first encode it to encoding (UTF-8 by default).

Parameters:

  • s – bytes or text string to be encoded

  • encoding – encoding used to encode s if it’s a text string

Returns:

Base64 encoded text string (Unicode)

Use encode_as_bytes() to get the Base64 encoded string as bytes.

jsonutils

JSON related utilities.

This module provides a few things:

  1. A handy function for getting an object down to something that can be JSON serialized. See to_primitive().

  2. Wrappers around loads() and dumps(). The dumps() wrapper will automatically use to_primitive() for you if needed.

  3. This sets up anyjson to use the loads() and dumps() wrappers if anyjson is available.

oslo_serialization.jsonutils.dump(obj, fp, *args, **kwargs)

Serialize obj as a JSON formatted stream to fp

Parameters:

  • obj – object to be serialized

  • fp – a .write()-supporting file-like object

  • default – function that returns a serializable version of an object, to_primitive() is used by default.

  • args – extra arguments, please see documentation of json.dump

  • kwargs –

    extra named parameters, please see documentation of json.dump

Changed in version 1.3: The default parameter now uses to_primitive() by default.

oslo_serialization.jsonutils.dump_as_bytes(obj, default=<function to_primitive>, encoding='utf-8', **kwargs)

Serialize obj to a JSON formatted bytes.

Parameters:

  • obj – object to be serialized

  • default – function that returns a serializable version of an object, to_primitive() is used by default.

  • encoding – encoding used to encode the serialized JSON output

  • kwargs – extra named parameters, please see documentation of json.dumps

Returns:

json formatted string

Added in version 1.10.

oslo_serialization.jsonutils.dumps(obj, default=<function to_primitive>, **kwargs)

Serialize obj to a JSON formatted str.

Parameters:

  • obj – object to be serialized

  • default – function that returns a serializable version of an object, to_primitive() is used by default.

  • kwargs –

    extra named parameters, please see documentation of json.dumps

Returns:

json formatted string

Use dump_as_bytes() to ensure that the result type is bytes on Python 2 and Python 3.

oslo_serialization.jsonutils.load(fp, encoding='utf-8', **kwargs)

Deserialize fp to a Python object.

Parameters:

  • fp – a .read() -supporting file-like object

  • encoding – encoding used to interpret the string

  • kwargs – extra named parameters, please see documentation of json.loads

Returns:

python object

oslo_serialization.jsonutils.loads(s, encoding='utf-8', **kwargs)

Deserialize s (a str or unicode instance containing a JSON

Parameters:

  • s – string to deserialize

  • encoding – encoding used to interpret the string

  • kwargs –

    extra named parameters, please see documentation of json.loads

Returns:

python object

oslo_serialization.jsonutils.to_primitive(value, convert_instances=False, convert_datetime=True, level=0, max_depth=3, encoding='utf-8', fallback=None)

Convert a complex object into primitives.

Handy for JSON serialization. We can optionally handle instances, but since this is a recursive function, we could have cyclical data structures.

To handle cyclical data structures we could track the actual objects visited in a set, but not all objects are hashable. Instead we just track the depth of the object inspections and don’t go too deep.

Therefore, convert_instances=True is lossy … be aware.

If the object cannot be converted to primitive, it is returned unchanged if fallback is not set, return fallback(value) otherwise.

Changed in version 2.22: Added fallback parameter.

Changed in version 1.3: Support UUID encoding.

Changed in version 1.6: Dictionary keys are now also encoded.

msgpackutils

MessagePack related utilities.

This module provides a few things:

  1. A handy registry for getting an object down to something that can be msgpack serialized. See HandlerRegistry.

  2. Wrappers around loads() and dumps(). The dumps() wrapper will automatically use the default_registry for you if needed.

Added in version 1.3.

class oslo_serialization.msgpackutils.HandlerRegistry

Registry of type specific msgpack handlers extensions.

See: https://github.com/msgpack/msgpack/blob/master/spec.md#formats-ext

Do note that due to the current limitations in the msgpack python library we can not currently dump/load a tuple without converting it to a list.

This may be fixed in: https://github.com/msgpack/msgpack-python/pull/100

Added in version 1.5.

copy(unfreeze=False)

Deep copy the given registry (and its handlers).

get(identity)

Get the handler for the given numeric identity (or none).

match(obj)

Match the registries handlers to the given object (or none).

max_value = 127

Applications can assign 0 to 127 to store application (or library) specific type handlers; see above ranges for what is reserved by this library and what is not.

min_value = 0

Applications can assign 0 to 127 to store application (or library) specific type handlers; see above ranges for what is reserved by this library and what is not.

non_reserved_extension_range = Interval(33, 127)

These ranges are always reserved for use by applications building their own type specific handlers (the meaning of extensions in this range will typically vary depending on application).

register(handler, reserved=False, override=False)

Register a extension handler to handle its associated type.

reserved_extension_range = Interval(0, 32)

These ranges are always reserved for use by oslo.serialization and its own add-ons extensions (these extensions are meant to be generally applicable to all of python).

class oslo_serialization.msgpackutils.Interval(min_value, max_value)

Small and/or simple immutable integer/float interval class.

Interval checking is inclusive of the min/max boundaries.

oslo_serialization.msgpackutils.default_registry = <oslo_serialization.msgpackutils.HandlerRegistry object>

Default, read-only/frozen registry that will be used when none is provided.

This registry has msgpack extensions for the following:

  • DateTime objects.

  • Date objects.

  • UUID objects.

  • itertools.count objects/iterators.

  • set and frozenset container(s).

  • netaddr.IPAddress objects (only if netaddr is importable).

  • xmlrpclib.DateTime datetime objects.

Added in version 1.5.

oslo_serialization.msgpackutils.dump(obj, fp, registry=None)

Serialize obj as a messagepack formatted stream to fp.

Changed in version 1.5: Added registry parameter.

oslo_serialization.msgpackutils.dumps(obj, registry=None)

Serialize obj to a messagepack formatted str.

Changed in version 1.5: Added registry parameter.

oslo_serialization.msgpackutils.load(fp, registry=None)

Deserialize fp into a Python object.

Changed in version 1.5: Added registry parameter.

oslo_serialization.msgpackutils.loads(s, registry=None)

Deserialize s messagepack str into a Python object.

Changed in version 1.5: Added registry parameter.