API Documentation¶
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 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 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 object - encoding – encoding used to interpret the string
- kwargs – extra named parameters, please see documentation of json.loads
Returns: python object
- fp – a
-
oslo_serialization.jsonutils.
loads
(s, encoding='utf-8', **kwargs)¶ Deserialize
s
(astr
orunicode
instance containing a JSONParameters: - 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')¶ 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.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.