diff --git a/README.md b/README.md index 213f7ad..06ed230 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # u-msgpack-python v1.5 -u-msgpack-python is a lightweight [MessagePack](http://msgpack.org/) 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](https://github.com/msgpack/msgpack/blob/master/spec.md). In particular, it supports the new binary, UTF-8 string, and application ext types. +u-msgpack-python is a lightweight [MessagePack](http://msgpack.org/) serializer and deserializer module written in pure Python, 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](https://github.com/msgpack/msgpack/blob/master/spec.md). In particular, it supports the new binary, UTF-8 string, and application ext types. -u-msgpack-python is written in pure Python and is currently distributed on PyPI: https://pypi.python.org/pypi/u-msgpack-python and as a single file: [umsgpack.py](https://raw.github.com/vsergeev/u-msgpack-python/master/umsgpack.py) +u-msgpack-python is currently distributed on PyPI: https://pypi.python.org/pypi/u-msgpack-python and as a single file: [umsgpack.py](https://raw.github.com/vsergeev/u-msgpack-python/master/umsgpack.py) ## Installation @@ -63,15 +63,13 @@ b'\x97\x01\xc3\xc2\xce\xff\xff\xff\xff\x82\xa3foo\xc4\x03\x80\x01 An example of encoding and decoding an application ext type: ``` python ->>> # Create an Ext object with type 0x05 and data b"\x01\x02\x03" -... foo = umsgpack.Ext(0x05, b"\x01\x02\x03") +# Create an Ext object with type 0x05 and data b"\x01\x02\x03" +>>> foo = umsgpack.Ext(0x05, b"\x01\x02\x03") >>> umsgpack.packb({u"special stuff": foo, u"awesome": True}) b'\x82\xadspecial stuff\xc7\x03\x05\x01\x02\x03\xa7awesome\xc3' >>> bar = umsgpack.unpackb(_) >>> print(bar["special stuff"]) -Ext Object - Type: 05 - Data: 01 02 03 +Ext Object (Type: 0x05, Data: 01 02 03) >>> bar["special stuff"].type 5 >>> bar["special stuff"].data @@ -79,6 +77,17 @@ b'\x01\x02\x03' >>> ``` +Python standard library style `loads` and `dumps` functions are also available as aliases: + +``` python +>>> import umsgpack +>>> umsgpack.dumps({u"compact": True, u"schema": 0}) +'\x82\xa7compact\xc3\xa6schema\x00' +>>> umsgpack.loads(_) +{u'compact': True, u'schema': 0} +>>> +``` + ## Compatibility Mode u-msgpack-python offers a compatibility mode for the [old specification](https://github.com/msgpack/msgpack/blob/master/spec-old.md) to handle the old "raw" bytes msgpack type. When the 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. To enable compatibility mode, simply set the `compatibility` boolean of the umsgpack module to `True`. @@ -122,78 +131,78 @@ If a non-byte-string argument is passed to `umsgpack.unpackb()`, it will raise a * `TypeError`: Packed data is not type `str` (Python 2), or not type `bytes` (Python 3). ``` python - >>> # Attempt to unpack non-str type data in Python 2 - ... umsgpack.unpackb(u"no good") + # Attempt to unpack non-str type data in Python 2 + >>> umsgpack.unpackb(u"no good") ... TypeError: expected packed data as type 'str' >>> - >>> # Attempt to unpack non-bytes type data in Python 3 - ... umsgpack.unpackb("no good") + # Attempt to unpack non-bytes type data in Python 3 + >>> umsgpack.unpackb("no good") ... TypeError: expected packed data as type 'bytes' >>> ``` -* `InsufficientDataException`: Insufficient data to unpack encoded object. +* `InsufficientDataException`: Insufficient data to unpack the encoded object. ``` python - >>> # Attempt to unpack a cut-off encoded 32-bit unsigned int - ... umsgpack.unpackb(b"\xce\xff\xff\xff") + # Attempt to unpack a cut-off encoded 32-bit unsigned int + >>> umsgpack.unpackb(b"\xce\xff\xff\xff") ... umsgpack.InsufficientDataException >>> - >>> # Attempt to unpack an array of length 2 missing the second item - ... umsgpack.unpackb(b"\x92\xc2") + # Attempt to unpack an array of length 2 missing the second item + >>> umsgpack.unpackb(b"\x92\xc2") ... umsgpack.InsufficientDataException >>> ``` -* `InvalidStringException`: Invalid string (not UTF-8) encountered. +* `InvalidStringException`: Invalid UTF-8 string encountered during unpacking. String bytes are strictly decoded with UTF-8. This exception is thrown if UTF-8 decoding of string bytes fails. ``` python - >>> # Attempt to unpack the string "\x80\x81" - ... umsgpack.unpackb(b"\xa2\x80\x81") + # Attempt to unpack the string "\x80\x81" + >>> umsgpack.unpackb(b"\xa2\x80\x81") ... umsgpack.InvalidStringException: unpacked string is not utf-8 >>> ``` -* `ReservedCodeException`: msgpack reserved code encountered. +* `ReservedCodeException`: Reserved code encountered during unpacking. ``` python - >>> # Attempt to unpack reserved code 0xc1 - ... umsgpack.unpackb(b"\xc1") + # Attempt to unpack reserved code 0xc1 + >>> umsgpack.unpackb(b"\xc1") ... umsgpack.ReservedCodeException: reserved code encountered: 0xc1 >>> ``` -* `KeyNotPrimitiveException`: Unhashable key encountered during map unpacking. +* `UnhashableKeyException`: Unhashable key encountered during map unpacking. The serialized map cannot be deserialized into a Python dictionary. Python dictionaries only support keys that are instances of `collections.Hashable`, so while the map `{ { u'abc': True } : 5 }` has a msgpack encoding, it cannot be unpacked into a valid Python dictionary. ``` python - >>> # Attempt to unpack { {} : False } - ... umsgpack.unpackb(b"\x82\x80\xc2") + # Attempt to unpack { {} : False } + >>> umsgpack.unpackb(b"\x82\x80\xc2") ... - umsgpack.KeyNotPrimitiveException: encountered non-primitive key type: + umsgpack.UnhashableKeyException: encountered unhashable key type: >>> ``` -* `KeyDuplicateException`: Duplicate key encountered during map unpacking. +* `DuplicateKeyException`: Duplicate key encountered during map unpacking. Python dictionaries do not support duplicate keys, but msgpack maps may be encoded with duplicate keys. ``` python - >>> # Attempt to unpack { 1: True, 1: False } - ... umsgpack.unpackb(b"\x82\x01\xc3\x01\xc2") + # Attempt to unpack { 1: True, 1: False } + >>> umsgpack.unpackb(b"\x82\x01\xc3\x01\xc2") ... - umsgpack.KeyDuplicateException: encountered duplicate key: 1, + umsgpack.DuplicateKeyException: encountered duplicate key: 1, >>> ``` diff --git a/msgpack.org.md b/msgpack.org.md index 5045031..0d4b94b 100644 --- a/msgpack.org.md +++ b/msgpack.org.md @@ -1,8 +1,8 @@ # u-msgpack-python v1.5 -u-msgpack-python is a lightweight [MessagePack](http://msgpack.org/) 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](https://github.com/msgpack/msgpack/blob/master/spec.md). +u-msgpack-python is a lightweight [MessagePack](http://msgpack.org/) serializer and deserializer module written in pure Python, 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](https://github.com/msgpack/msgpack/blob/master/spec.md). -u-msgpack-python is written in pure Python and is currently distributed on PyPI: https://pypi.python.org/pypi/u-msgpack-python and as a single file: [umsgpack.py](https://raw.github.com/vsergeev/u-msgpack-python/master/umsgpack.py) +u-msgpack-python is currently distributed on PyPI: https://pypi.python.org/pypi/u-msgpack-python and as a single file: [umsgpack.py](https://raw.github.com/vsergeev/u-msgpack-python/master/umsgpack.py) ## Installation @@ -68,9 +68,7 @@ An example of encoding and decoding an application ext type: b'\x82\xadspecial stuff\xc7\x03\x05\x01\x02\x03\xa7awesome\xc3' >>> bar = umsgpack.unpackb(_) >>> print(bar["special stuff"]) -Ext Object - Type: 05 - Data: 01 02 03 +Ext Object (Type: 0x05, Data: 01 02 03) >>> bar["special stuff"].type 5 >>> bar["special stuff"].data @@ -78,6 +76,17 @@ b'\x01\x02\x03' >>> ``` +Python standard library style `loads` and `dumps` functions are also available as aliases: + +``` python +>>> import umsgpack +>>> umsgpack.dumps({u"compact": True, u"schema": 0}) +'\x82\xa7compact\xc3\xa6schema\x00' +>>> umsgpack.loads(_) +{u'compact': True, u'schema': 0} +>>> +``` + ## More Information See the [project page](https://github.com/vsergeev/u-msgpack-python) for more information on old specification compatibility mode, exceptions, behavior, and testing. diff --git a/umsgpack.py b/umsgpack.py index b2ca187..e42b51b 100644 --- a/umsgpack.py +++ b/umsgpack.py @@ -178,6 +178,15 @@ class DuplicateKeyException(UnpackException): 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'\x92\xabsome string\xaasome bytes' +>>> umsgpack.unpackb(_) +[b'some string', b'some bytes'] +>>> """ ################################################################################