@@ -42,54 +42,6 @@ is recommended solution.
4242For Python 3.5, [Microsoft Visual Studio 2015](https://www.visualstudio.com/en-us/products/vs-2015-product-editions.aspx)
4343Community Edition or Express Edition can be used to build extension module.
4444
45- Notes
46- -----
47-
48- Note for msgpack 2.0 support
49- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
50-
51- msgpack 2.0 adds two types: *bin * and *ext *.
52-
53- *raw * was bytes or string type like Python 2's ``str ``.
54- To distinguish string and bytes, msgpack 2.0 adds *bin *.
55- It is non-string binary like Python 3's ``bytes ``.
56-
57- To use *bin * type for packing ``bytes ``, pass ``use_bin_type=True `` to
58- packer argument.
59-
60- .. code-block :: pycon
61-
62- >>> import msgpack
63- >>> packed = msgpack.packb([b'spam', u'egg'], use_bin_type=True)
64- >>> msgpack.unpackb(packed, encoding='utf-8')
65- ['spam', u'egg']
66-
67- You shoud use it carefully. When you use ``use_bin_type=True ``, packed
68- binary can be unpacked by unpackers supporting msgpack-2.0.
69-
70- To use *ext * type, pass ``msgpack.ExtType `` object to packer.
71-
72- .. code-block :: pycon
73-
74- >>> import msgpack
75- >>> packed = msgpack.packb(msgpack.ExtType(42, b'xyzzy'))
76- >>> msgpack.unpackb(packed)
77- ExtType(code=42, data='xyzzy')
78-
79- You can use it with ``default `` and ``ext_hook ``. See below.
80-
81- Note for msgpack 0.2.x users
82- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
83-
84- The msgpack 0.3 have some incompatible changes.
85-
86- The default value of ``use_list `` keyword argument is ``True `` from 0.3.
87- You should pass the argument explicitly for backward compatibility.
88-
89- `Unpacker.unpack() ` and some unpack methods now raises `OutOfData `
90- instead of `StopIteration `.
91- `StopIteration ` is used for iterator protocol only.
92-
9345
9446How to use
9547-----------
@@ -184,7 +136,7 @@ key-value pairs.
184136Extended types
185137^^^^^^^^^^^^^^^
186138
187- It is also possible to pack/unpack custom data types using the msgpack 2.0 feature .
139+ It is also possible to pack/unpack custom data types using the ** ext ** type .
188140
189141.. code-block :: pycon
190142
@@ -238,6 +190,58 @@ callback function:
238190 unpacker.skip(bytestream.write)
239191 worker.send(bytestream.getvalue())
240192
193+
194+ Notes
195+ -----
196+
197+ string and binary type
198+ ^^^^^^^^^^^^^^^^^^^^^^
199+
200+ In old days, msgpack doesn't distinguish string and binary types like Python 1.
201+ The type for represent string and binary types is named **raw **.
202+
203+ msgpack can distinguish string and binary type for now. But it is not like Python 2.
204+ Python 2 added unicode string. But msgpack renamed **raw ** to **str ** and added **bin ** type.
205+ It is because keep compatibility with data created by old libs. **raw ** was used for text more than binary.
206+
207+ Currently, while msgpack-python supports new **bin ** type, default setting doesn't use it and
208+ decodes **raw ** as `bytes ` instead of `unicode ` (`str ` in Python 3).
209+
210+ You can change this by using `use_bin_type=True ` option in Packer and `encoding="utf-8" ` option in Unpacker.
211+
212+ .. code-block :: pycon
213+
214+ >>> import msgpack
215+ >>> packed = msgpack.packb([b'spam', u'egg'], use_bin_type=True)
216+ >>> msgpack.unpackb(packed, encoding='utf-8')
217+ ['spam', u'egg']
218+
219+ ext type
220+ ^^^^^^^^
221+
222+ To use **ext ** type, pass ``msgpack.ExtType `` object to packer.
223+
224+ .. code-block :: pycon
225+
226+ >>> import msgpack
227+ >>> packed = msgpack.packb(msgpack.ExtType(42, b'xyzzy'))
228+ >>> msgpack.unpackb(packed)
229+ ExtType(code=42, data='xyzzy')
230+
231+ You can use it with ``default `` and ``ext_hook ``. See below.
232+
233+ Note for msgpack-python 0.2.x users
234+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
235+
236+ The msgpack-python 0.3 have some incompatible changes.
237+
238+ The default value of ``use_list `` keyword argument is ``True `` from 0.3.
239+ You should pass the argument explicitly for backward compatibility.
240+
241+ `Unpacker.unpack() ` and some unpack methods now raises `OutOfData `
242+ instead of `StopIteration `.
243+ `StopIteration ` is used for iterator protocol only.
244+
241245Note about performance
242246------------------------
243247
@@ -259,12 +263,17 @@ Python's dict can't use list as key and MessagePack allows array for key of mapp
259263Another way to unpacking such object is using ``object_pairs_hook ``.
260264
261265
266+ Development
267+ ------------
268+
262269Test
263- ----
270+ ^^^^
271+
264272MessagePack uses `pytest ` for testing.
265273Run test with following command:
266274
267275 $ py.test
268276
277+
269278..
270279 vim: filetype=rst
0 commit comments