pybitmessage.fallback.umsgpack.umsgpack module

src/fallback/umsgpack/umsgpack.py

u-msgpack-python v2.4.1 - v at sergeev.io https://github.com/vsergeev/u-msgpack-python

u-msgpack-python is a lightweight MessagePack serializer and deserializer module, compatible with both Python 2 and 3, as well CPython and PyPy implementations of Python. u-msgpack-python is fully compliant with the latest MessagePack specification.com/msgpack/msgpack/blob/master/spec.md). In particular, it supports the new binary, UTF-8 string, and application ext types.

License: MIT

version = (2, 4, 1)[source]

Module version tuple

class Ext(type, data)[source]

The Ext class facilitates creating a serializable extension object to store an application-defined type and data byte array.

class InvalidString[source]

Bases: str

Subclass of bytes to hold invalid UTF-8 strings.

exception PackException[source]

Bases: exceptions.Exception

Base class for exceptions encountered during packing.

exception UnpackException[source]

Bases: exceptions.Exception

Base class for exceptions encountered during unpacking.

exception UnsupportedTypeException[source]

Bases: pybitmessage.fallback.umsgpack.umsgpack.PackException

Object type not supported for packing.

exception InsufficientDataException[source]

Bases: pybitmessage.fallback.umsgpack.umsgpack.UnpackException

Insufficient data to unpack the serialized object.

exception InvalidStringException[source]

Bases: pybitmessage.fallback.umsgpack.umsgpack.UnpackException

Invalid UTF-8 string encountered during unpacking.

exception ReservedCodeException[source]

Bases: pybitmessage.fallback.umsgpack.umsgpack.UnpackException

Reserved code encountered during unpacking.

exception UnhashableKeyException[source]

Bases: pybitmessage.fallback.umsgpack.umsgpack.UnpackException

Unhashable key encountered during map unpacking. The serialized map cannot be deserialized into a Python dictionary.

exception DuplicateKeyException[source]

Bases: pybitmessage.fallback.umsgpack.umsgpack.UnpackException

Duplicate key encountered during map unpacking.

KeyNotPrimitiveException[source]

alias of pybitmessage.fallback.umsgpack.umsgpack.UnhashableKeyException

KeyDuplicateException[source]

alias of pybitmessage.fallback.umsgpack.umsgpack.DuplicateKeyException

pack(obj, fp, **options)[source]

Serialize a Python object into MessagePack bytes.

Parameters:
  • obj – a Python object
  • fp – a .write()-supporting file-like object
Kwargs:
ext_handlers (dict): dictionary of Ext handlers, mapping a custom type
to a callable that packs an instance of the type into an Ext object
force_float_precision (str): “single” to force packing floats as
IEEE-754 single-precision floats, “double” to force packing floats as IEEE-754 double-precision floats.
Returns:None.
Raises:UnsupportedType(PackException) – Object type not supported for packing.

Example: >>> f = open(‘test.bin’, ‘wb’) >>> umsgpack.pack({u”compact”: True, u”schema”: 0}, f) >>>

packb(obj, **options)[source]

Serialize a Python object into MessagePack bytes.

Parameters:obj – a Python object
Kwargs:
ext_handlers (dict): dictionary of Ext handlers, mapping a custom type
to a callable that packs an instance of the type into an Ext object
force_float_precision (str): “single” to force packing floats as
IEEE-754 single-precision floats, “double” to force packing floats as IEEE-754 double-precision floats.
Returns:A ‘str’ containing serialized MessagePack bytes.
Raises:UnsupportedType(PackException) – Object type not supported for packing.

Example: >>> umsgpack.packb({u”compact”: True, u”schema”: 0}) ‘‚§compactæschema’ >>>

unpack(fp, **options)[source]

Deserialize MessagePack bytes into a Python object.

Parameters:fp – a .read()-supporting file-like object
Kwargs:
ext_handlers (dict): dictionary of Ext handlers, mapping integer Ext
type to a callable that unpacks an instance of Ext into an object
use_ordered_dict (bool): unpack maps into OrderedDict, instead of
unordered dict (default False)
allow_invalid_utf8 (bool): unpack invalid strings into instances of
InvalidString, for access to the bytes (default False)
Returns:

A Python object.
Raises:
  • InsufficientDataException(UnpackException) – Insufficient data to unpack the serialized object.
  • InvalidStringException(UnpackException) – Invalid UTF-8 string encountered during unpacking.
  • ReservedCodeException(UnpackException) – Reserved code encountered during unpacking.
  • UnhashableKeyException(UnpackException) – Unhashable key encountered during map unpacking. The serialized map cannot be deserialized into a Python dictionary.
  • DuplicateKeyException(UnpackException) – Duplicate key encountered during map unpacking.

Example: >>> f = open(‘test.bin’, ‘rb’) >>> umsgpack.unpackb(f) {u’compact’: True, u’schema’: 0} >>>

unpackb(s, **options)[source]

Deserialize MessagePack bytes into a Python object.

Parameters:s – a ‘str’ or ‘bytearray’ containing serialized MessagePack bytes
Kwargs:
ext_handlers (dict): dictionary of Ext handlers, mapping integer Ext
type to a callable that unpacks an instance of Ext into an object
use_ordered_dict (bool): unpack maps into OrderedDict, instead of
unordered dict (default False)
allow_invalid_utf8 (bool): unpack invalid strings into instances of
InvalidString, for access to the bytes (default False)
Returns:

A Python object.
Raises:
  • TypeError – Packed data type is neither ‘str’ nor ‘bytearray’.
  • InsufficientDataException(UnpackException) – Insufficient data to unpack the serialized object.
  • InvalidStringException(UnpackException) – Invalid UTF-8 string encountered during unpacking.
  • ReservedCodeException(UnpackException) – Reserved code encountered during unpacking.
  • UnhashableKeyException(UnpackException) – Unhashable key encountered during map unpacking. The serialized map cannot be deserialized into a Python dictionary.
  • DuplicateKeyException(UnpackException) – Duplicate key encountered during map unpacking.

Example: >>> umsgpack.unpackb(b’‚§compactæschema’) {u’compact’: True, u’schema’: 0} >>>

dump(obj, fp, **options)[source]

Serialize a Python object into MessagePack bytes.

Parameters:
  • obj – a Python object
  • fp – a .write()-supporting file-like object
Kwargs:
ext_handlers (dict): dictionary of Ext handlers, mapping a custom type
to a callable that packs an instance of the type into an Ext object
force_float_precision (str): “single” to force packing floats as
IEEE-754 single-precision floats, “double” to force packing floats as IEEE-754 double-precision floats.
Returns:None.
Raises:UnsupportedType(PackException) – Object type not supported for packing.

Example: >>> f = open(‘test.bin’, ‘wb’) >>> umsgpack.pack({u”compact”: True, u”schema”: 0}, f) >>>

dumps(obj, **options)[source]

Serialize a Python object into MessagePack bytes.

Parameters:obj – a Python object
Kwargs:
ext_handlers (dict): dictionary of Ext handlers, mapping a custom type
to a callable that packs an instance of the type into an Ext object
force_float_precision (str): “single” to force packing floats as
IEEE-754 single-precision floats, “double” to force packing floats as IEEE-754 double-precision floats.
Returns:A ‘str’ containing serialized MessagePack bytes.
Raises:UnsupportedType(PackException) – Object type not supported for packing.

Example: >>> umsgpack.packb({u”compact”: True, u”schema”: 0}) ‘‚§compactæschema’ >>>

load(fp, **options)[source]

Deserialize MessagePack bytes into a Python object.

Parameters:fp – a .read()-supporting file-like object
Kwargs:
ext_handlers (dict): dictionary of Ext handlers, mapping integer Ext
type to a callable that unpacks an instance of Ext into an object
use_ordered_dict (bool): unpack maps into OrderedDict, instead of
unordered dict (default False)
allow_invalid_utf8 (bool): unpack invalid strings into instances of
InvalidString, for access to the bytes (default False)
Returns:

A Python object.
Raises:
  • InsufficientDataException(UnpackException) – Insufficient data to unpack the serialized object.
  • InvalidStringException(UnpackException) – Invalid UTF-8 string encountered during unpacking.
  • ReservedCodeException(UnpackException) – Reserved code encountered during unpacking.
  • UnhashableKeyException(UnpackException) – Unhashable key encountered during map unpacking. The serialized map cannot be deserialized into a Python dictionary.
  • DuplicateKeyException(UnpackException) – Duplicate key encountered during map unpacking.

Example: >>> f = open(‘test.bin’, ‘rb’) >>> umsgpack.unpackb(f) {u’compact’: True, u’schema’: 0} >>>

loads(s, **options)[source]

Deserialize MessagePack bytes into a Python object.

Parameters:s – a ‘str’ or ‘bytearray’ containing serialized MessagePack bytes
Kwargs:
ext_handlers (dict): dictionary of Ext handlers, mapping integer Ext
type to a callable that unpacks an instance of Ext into an object
use_ordered_dict (bool): unpack maps into OrderedDict, instead of
unordered dict (default False)
allow_invalid_utf8 (bool): unpack invalid strings into instances of
InvalidString, for access to the bytes (default False)
Returns:

A Python object.
Raises:
  • TypeError – Packed data type is neither ‘str’ nor ‘bytearray’.
  • InsufficientDataException(UnpackException) – Insufficient data to unpack the serialized object.
  • InvalidStringException(UnpackException) – Invalid UTF-8 string encountered during unpacking.
  • ReservedCodeException(UnpackException) – Reserved code encountered during unpacking.
  • UnhashableKeyException(UnpackException) – Unhashable key encountered during map unpacking. The serialized map cannot be deserialized into a Python dictionary.
  • DuplicateKeyException(UnpackException) – Duplicate key encountered during map unpacking.

Example: >>> umsgpack.unpackb(b’‚§compactæschema’) {u’compact’: True, u’schema’: 0} >>>

compatibility = False[source]

Compatibility mode boolean.

When compatibility mode is enabled, u-msgpack-python will serialize both unicode strings and bytes into the old “raw” msgpack type, and deserialize the “raw” msgpack type into bytes. This provides backwards compatibility with the old MessagePack specification.

Example: >>> umsgpack.compatibility = True >>> >>> umsgpack.packb([u”some string”, b”some bytes”]) b’’«some stringªsome bytes’ >>> umsgpack.unpackb(_) [b’some string’, b’some bytes’] >>>