API Reference

base64

Utilities to encode and decode Base64.

Added in version 1.10.

oslo_serialization.base64.decode_as_bytes(encoded: str | bytes) → bytes

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: str | bytes, encoding: str = 'utf-8') → str

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: str | bytes, encoding: str = 'utf-8') → bytes

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: str | bytes, encoding: str = 'utf-8') → str

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.

oslo_serialization.jsonutils.dump(obj: Any, fp: SupportsWrite, *args: Any, **kwargs: Any) → None

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: ~typing.Any, default: ~collections.abc.Callable[[~typing.Any], ~typing.Any] = <function to_primitive>, encoding: str = 'utf-8', **kwargs: ~typing.Any) → bytes

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: ~typing.Any, default: ~collections.abc.Callable[[~typing.Any], ~typing.Any] = <function to_primitive>, **kwargs: ~typing.Any) → str

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.

oslo_serialization.jsonutils.load(fp: ReadableStream, encoding: str = 'utf-8', **kwargs: Any) → Any

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: str | bytes, encoding: str = 'utf-8', **kwargs: Any) → Any

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: Any, convert_instances: bool = False, convert_datetime: bool = True, level: int = 0, max_depth: int = 3, encoding: str = 'utf-8', fallback: Callable[[Any], str | int | None | bool | float] | None = None) → Any

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.CountHandler
class oslo_serialization.msgpackutils.DateHandler(registry: HandlerRegistry)
class oslo_serialization.msgpackutils.DateTimeHandler(registry: HandlerRegistry)
class oslo_serialization.msgpackutils.FrozenSetHandler(registry: HandlerRegistry)
class oslo_serialization.msgpackutils.HandlerProtocol(*args, **kwargs)
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: bool = False) → Self

Deep copy the given registry (and its handlers).

get(identity: int) → HandlerProtocol[Any] | None

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

match(obj: Any) → HandlerProtocol[Any] | None

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: HandlerProtocol[Any], reserved: bool = False, override: bool = False) → None

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: int, max_value: int)

Small and/or simple immutable interval class.

Interval checking is inclusive of the min/max boundaries.

class oslo_serialization.msgpackutils.NetAddrIPHandler
class oslo_serialization.msgpackutils.SetHandler(registry: HandlerRegistry)
class oslo_serialization.msgpackutils.UUIDHandler
class oslo_serialization.msgpackutils.XMLRPCDateTimeHandler(registry: HandlerRegistry)
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: Any, fp: SupportsWrite, registry: HandlerRegistry | None = None) → None

Serialize obj as a messagepack formatted stream to fp.

Changed in version 1.5: Added registry parameter.

oslo_serialization.msgpackutils.dumps(obj: Any, registry: HandlerRegistry | None = None) → bytes

Serialize obj to a messagepack formatted str.

Changed in version 1.5: Added registry parameter.

oslo_serialization.msgpackutils.load(fp: ReadableStream, registry: HandlerRegistry | None = None) → Any

Deserialize fp into a Python object.

Changed in version 1.5: Added registry parameter.

oslo_serialization.msgpackutils.loads(s: bytes, registry: HandlerRegistry | None = None) → Any

Deserialize s messagepack str into a Python object.

Changed in version 1.5: Added registry parameter.