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

this page last updated: 2026-03-26 20:30:20

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug