API Reference¶
base64¶
Utilities to encode and decode Base64.
New 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:
A handy function for getting an object down to something that can be JSON serialized. See
to_primitive()
.Wrappers around
loads()
anddumps()
. Thedumps()
wrapper will automatically useto_primitive()
for you if needed.This sets up
anyjson
to use theloads()
anddumps()
wrappers ifanyjson
is available.
- oslo_serialization.jsonutils.dump(obj, fp, *args, **kwargs)¶
Serialize
obj
as a JSON formatted stream tofp
- Parameters:
obj – object to be serialized
fp – a
.write()
-supporting file-like objectdefault – 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 formattedbytes
.- 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
New in version 1.10.
- oslo_serialization.jsonutils.dumps(obj, default=<function to_primitive>, **kwargs)¶
Serialize
obj
to a JSON formattedstr
.- 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 objectencoding – 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
(astr
orunicode
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:
A handy registry for getting an object down to something that can be msgpack serialized. See
HandlerRegistry
.Wrappers around
loads()
anddumps()
. Thedumps()
wrapper will automatically use thedefault_registry
for you if needed.
New 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
New 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
andfrozenset
container(s).netaddr.IPAddress
objects (only ifnetaddr
is importable).xmlrpclib.DateTime
datetime objects.
New in version 1.5.
- oslo_serialization.msgpackutils.dump(obj, fp, registry=None)¶
Serialize
obj
as a messagepack formatted stream tofp
.Changed in version 1.5: Added registry parameter.
- oslo_serialization.msgpackutils.dumps(obj, registry=None)¶
Serialize
obj
to a messagepack formattedstr
.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
messagepackstr
into a Python object.Changed in version 1.5: Added registry parameter.