Skip to content

Commit ea24448

Browse files
vsergeevvsergeev
committed
update docs and version to v2.0
1 parent 76737aa commit ea24448

5 files changed

Lines changed: 90 additions & 33 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
* Version 2.0 - 09/29/2014
2+
* Add streaming serialization and deserialization with `pack`/`dump` and `unpack`/`load`, respectively, for file-like objects.
3+
14
* Version 1.8 - 09/17/2014
25
* Add support for unpacking maps with array container keys. Thanks to ralphjzhang for the report and suggestion (https://github.com/vsergeev/u-msgpack-python/issues/10).
36

‎README.md‎

Lines changed: 57 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# u-msgpack-python v1.8
1+
# u-msgpack-python v2.0
22

3-
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.
3+
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-defined ext types.
44

55
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)
66

@@ -46,20 +46,23 @@ A more complicated example:
4646
>>>
4747
```
4848

49-
The more complicated example in Python 3:
49+
Streaming serialization with file-like objects:
5050
``` python
51-
>>> umsgpack.packb( [1, True, False, 0xffffffff, {u"foo": b"\x80\x01\x02",
52-
u"bar": [1,2,3, {u"a": [1,2,3,{}]}]}, -1, 2.12345] )
53-
b'\x97\x01\xc3\xc2\xce\xff\xff\xff\xff\x82\xa3foo\xc4\x03\x80\x01
54-
\x02\xa3bar\x94\x01\x02\x03\x81\xa1a\x94\x01\x02\x03\x80\xff\xcb@
55-
\x00\xfc\xd3Z\x85\x87\x94'
56-
>>> umsgpack.unpackb(_)
57-
[1, True, False, 4294967295, {'foo': b'\x80\x01\x02',
58-
'bar': [1, 2, 3, {'a': [1, 2, 3, {}]}]}, -1, 2.12345]
51+
>>> f = open('test.bin', 'w')
52+
>>> umsgpack.pack({u"compact": True, u"schema": 0}, f)
53+
>>> umsgpack.pack([1,2,3], f)
54+
>>> f.close()
55+
>>>
56+
>>> f = open('test.bin')
57+
>>> umsgpack.unpack(f)
58+
{u'compact': True, u'schema': 0}
59+
>>> umsgpack.unpack(f)
60+
[1, 2, 3]
61+
>>> f.close()
5962
>>>
6063
```
6164

62-
An example of encoding and decoding an application ext type:
65+
Encoding and decoding an application-defined ext type:
6366
``` python
6467
# Create an Ext object with type 0x05 and data b"\x01\x02\x03"
6568
>>> foo = umsgpack.Ext(0x05, b"\x01\x02\x03")
@@ -75,7 +78,7 @@ b'\x01\x02\x03'
7578
>>>
7679
```
7780

78-
Python standard library style `loads` and `dumps` functions are also available as aliases:
81+
Python standard library style names `dump`, `dumps`, `load`, `loads` are also available:
7982

8083
``` python
8184
>>> import umsgpack
@@ -84,6 +87,45 @@ Python standard library style `loads` and `dumps` functions are also available a
8487
>>> umsgpack.loads(_)
8588
{u'compact': True, u'schema': 0}
8689
>>>
90+
>>> f = open('test.bin', 'w')
91+
>>> umsgpack.dump({u"compact": True, u"schema": 0}, f)
92+
>>> f.close()
93+
>>>
94+
>>> f = open('test.bin')
95+
>>> umsgpack.load(f)
96+
{u'compact': True, u'schema': 0}
97+
>>>
98+
```
99+
100+
## Streaming Serialization and Deserialization
101+
102+
The streaming `pack()`/`dump()` and `unpack()`/`load()` functions allow packing and unpacking objects directly to and from a stream, respectively. Streaming may be necessary when unpacking serialized bytes whose size is unknown in advance, or it may be more convenient and efficient when working directly with stream objects (e.g. files or stream sockets).
103+
104+
`pack(obj, fp)` / `dump(obj, fp)` serialize Python object `obj` to a `.write()` supporting file-like object `fp`.
105+
106+
``` python
107+
>>> class Foo:
108+
... def write(self, data):
109+
... # write 'data' bytes
110+
... pass
111+
...
112+
>>> f = Foo()
113+
>>> umsgpack.pack({u"compact": True, u"schema": 0}, f)
114+
>>>
115+
```
116+
117+
`unpack(fp)` / `load(fp)` deserialize a Python object from a `.read()` supporting file-like object `fp`.
118+
119+
``` python
120+
>>> class Bar:
121+
... def read(self, n):
122+
... # read and return 'n' number of bytes
123+
... return "\x01"*n
124+
...
125+
>>> f = Bar()
126+
>>> umsgpack.unpack(f)
127+
1
128+
>>>
87129
```
88130

89131
## Compatibility Mode
@@ -104,7 +146,7 @@ b'\x92\xabsome string\xaasome bytes'
104146

105147
### Packing Exceptions
106148

107-
If an error occurs during packing, `umsgpack.packb()` will raise an exception derived from `umsgpack.PackException`. All possible packing exceptions are described below.
149+
If an error occurs during packing, umsgpack will raise an exception derived from `umsgpack.PackException`. All possible packing exceptions are described below.
108150

109151
* `UnsupportedTypeException`: Object type not supported for packing.
110152

@@ -124,7 +166,7 @@ If an error occurs during packing, `umsgpack.packb()` will raise an exception de
124166

125167
### Unpacking Exceptions
126168

127-
If a non-byte-string argument is passed to `umsgpack.unpackb()`, it will raise a `TypeError` exception. If an error occurs during unpacking, `umsgpack.unpackb()` will raise an exception derived from `umsgpack.UnpackException`. All possible unpacking exceptions are described below.
169+
If a non-byte-string argument is passed to `umsgpack.unpackb()`, it will raise a `TypeError` exception. If an error occurs during unpacking, umsgpack will raise an exception derived from `umsgpack.UnpackException`. All possible unpacking exceptions are described below.
128170

129171
* `TypeError`: Packed data is not type `str` (Python 2), or not type `bytes` (Python 3).
130172

‎msgpack.org.md‎

Lines changed: 25 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# u-msgpack-python v1.8
1+
# u-msgpack-python v2.0
22

33
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).
44

@@ -32,6 +32,7 @@ Basic Example:
3232
{u'compact': True, u'schema': 0}
3333
>>>
3434
```
35+
3536
A more complicated example:
3637
``` python
3738
>>> umsgpack.packb(
@@ -46,21 +47,23 @@ A more complicated example:
4647
>>>
4748
```
4849

49-
The more complicated example in Python 3:
50+
Streaming serialization with file-like objects:
5051
``` python
51-
>>> umsgpack.packb(
52-
[1, True, False, 0xffffffff, {u"foo": b"\x80\x01\x02",
53-
u"bar": [1,2,3, {u"a": [1,2,3,{}]}]}, -1, 2.12345] )
54-
b'\x97\x01\xc3\xc2\xce\xff\xff\xff\xff\x82\xa3foo\xc4\x03\x80\x01
55-
\x02\xa3bar\x94\x01\x02\x03\x81\xa1a\x94\x01\x02\x03\x80\xff\xcb@
56-
\x00\xfc\xd3Z\x85\x87\x94'
57-
>>> umsgpack.unpackb(_)
58-
[1, True, False, 4294967295, {'foo': b'\x80\x01\x02',
59-
'bar': [1, 2, 3, {'a': [1, 2, 3, {}]}]}, -1, 2.12345]
52+
>>> f = open('test.bin', 'w')
53+
>>> umsgpack.pack({u"compact": True, u"schema": 0}, f)
54+
>>> umsgpack.pack([1,2,3], f)
55+
>>> f.close()
56+
>>>
57+
>>> f = open('test.bin')
58+
>>> umsgpack.unpack(f)
59+
{u'compact': True, u'schema': 0}
60+
>>> umsgpack.unpack(f)
61+
[1, 2, 3]
62+
>>> f.close()
6063
>>>
6164
```
6265

63-
An example of encoding and decoding an application ext type:
66+
Encoding and decoding an application-defined ext type:
6467
``` python
6568
>>> # Create an Ext object with type 0x05 and data b"\x01\x02\x03"
6669
... foo = umsgpack.Ext(0x05, b"\x01\x02\x03")
@@ -76,7 +79,8 @@ b'\x01\x02\x03'
7679
>>>
7780
```
7881

79-
Python standard library style `loads` and `dumps` functions are also available as aliases:
82+
Python standard library style names `dump`, `dumps`, `load`, `loads` are also
83+
available:
8084

8185
``` python
8286
>>> import umsgpack
@@ -85,6 +89,14 @@ Python standard library style `loads` and `dumps` functions are also available a
8589
>>> umsgpack.loads(_)
8690
{u'compact': True, u'schema': 0}
8791
>>>
92+
>>> f = open('test.bin', 'w')
93+
>>> umsgpack.dump({u"compact": True, u"schema": 0}, f)
94+
>>> f.close()
95+
>>>
96+
>>> f = open('test.bin')
97+
>>> umsgpack.load(f)
98+
{u'compact': True, u'schema': 0}
99+
>>>
88100
```
89101

90102
## More Information

‎setup.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,13 @@
22

33
setup(
44
name='u-msgpack-python',
5-
version='1.8',
5+
version='2.0',
66
description='A portable, lightweight msgpack serializer and deserializer written in pure Python.',
77
author='vsergeev',
88
author_email='vsergeev at gmail',
99
url='https://github.com/vsergeev/u-msgpack-python',
1010
py_modules=['umsgpack'],
11-
long_description="""u-msgpack-python is a lightweight `MessagePack <http://msgpack.org/>`_ serializer and deserializer module written in pure Python, compatible with both Python 2 and Python 3, as well as 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. See https://github.com/vsergeev/u-msgpack-python for more information.""",
11+
long_description="""u-msgpack-python is a lightweight `MessagePack <http://msgpack.org/>`_ serializer and deserializer module written in pure Python, compatible with both Python 2 and Python 3, as well as 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-defined ext types. See https://github.com/vsergeev/u-msgpack-python for more information.""",
1212
classifiers=[
1313
"Development Status :: 5 - Production/Stable",
1414
"License :: OSI Approved :: MIT License",

‎umsgpack.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# u-msgpack-python v1.8 - vsergeev at gmail
1+
# u-msgpack-python v2.0 - vsergeev at gmail
22
# https://github.com/vsergeev/u-msgpack-python
33
#
44
# u-msgpack-python is a lightweight MessagePack serializer and deserializer
@@ -31,7 +31,7 @@
3131
# THE SOFTWARE.
3232
#
3333
"""
34-
u-msgpack-python v1.8 - vsergeev at gmail
34+
u-msgpack-python v2.0 - vsergeev at gmail
3535
https://github.com/vsergeev/u-msgpack-python
3636
3737
u-msgpack-python is a lightweight MessagePack serializer and deserializer
@@ -44,7 +44,7 @@
4444
License: MIT
4545
"""
4646

47-
version = (1,8)
47+
version = (2,0)
4848
"Module version tuple"
4949

5050
import struct

0 commit comments

Comments
 (0)