mirror of
https://github.com/msgpack/msgpack-python.git
synced 2025-11-10 22:41:03 +00:00
Remove msgpack 2.0 from README
There are no versio in spec.
This commit is contained in:
parent
53fcd9b9df
commit
e601ef4c23
1 changed files with 59 additions and 50 deletions
109
README.rst
109
README.rst
|
|
@ -42,54 +42,6 @@ is recommended solution.
|
||||||
For Python 3.5, [Microsoft Visual Studio 2015](https://www.visualstudio.com/en-us/products/vs-2015-product-editions.aspx)
|
For Python 3.5, [Microsoft Visual Studio 2015](https://www.visualstudio.com/en-us/products/vs-2015-product-editions.aspx)
|
||||||
Community Edition or Express Edition can be used to build extension module.
|
Community Edition or Express Edition can be used to build extension module.
|
||||||
|
|
||||||
Notes
|
|
||||||
-----
|
|
||||||
|
|
||||||
Note for msgpack 2.0 support
|
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
msgpack 2.0 adds two types: *bin* and *ext*.
|
|
||||||
|
|
||||||
*raw* was bytes or string type like Python 2's ``str``.
|
|
||||||
To distinguish string and bytes, msgpack 2.0 adds *bin*.
|
|
||||||
It is non-string binary like Python 3's ``bytes``.
|
|
||||||
|
|
||||||
To use *bin* type for packing ``bytes``, pass ``use_bin_type=True`` to
|
|
||||||
packer argument.
|
|
||||||
|
|
||||||
.. code-block:: pycon
|
|
||||||
|
|
||||||
>>> import msgpack
|
|
||||||
>>> packed = msgpack.packb([b'spam', u'egg'], use_bin_type=True)
|
|
||||||
>>> msgpack.unpackb(packed, encoding='utf-8')
|
|
||||||
['spam', u'egg']
|
|
||||||
|
|
||||||
You shoud use it carefully. When you use ``use_bin_type=True``, packed
|
|
||||||
binary can be unpacked by unpackers supporting msgpack-2.0.
|
|
||||||
|
|
||||||
To use *ext* type, pass ``msgpack.ExtType`` object to packer.
|
|
||||||
|
|
||||||
.. code-block:: pycon
|
|
||||||
|
|
||||||
>>> import msgpack
|
|
||||||
>>> packed = msgpack.packb(msgpack.ExtType(42, b'xyzzy'))
|
|
||||||
>>> msgpack.unpackb(packed)
|
|
||||||
ExtType(code=42, data='xyzzy')
|
|
||||||
|
|
||||||
You can use it with ``default`` and ``ext_hook``. See below.
|
|
||||||
|
|
||||||
Note for msgpack 0.2.x users
|
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
The msgpack 0.3 have some incompatible changes.
|
|
||||||
|
|
||||||
The default value of ``use_list`` keyword argument is ``True`` from 0.3.
|
|
||||||
You should pass the argument explicitly for backward compatibility.
|
|
||||||
|
|
||||||
`Unpacker.unpack()` and some unpack methods now raises `OutOfData`
|
|
||||||
instead of `StopIteration`.
|
|
||||||
`StopIteration` is used for iterator protocol only.
|
|
||||||
|
|
||||||
|
|
||||||
How to use
|
How to use
|
||||||
-----------
|
-----------
|
||||||
|
|
@ -184,7 +136,7 @@ key-value pairs.
|
||||||
Extended types
|
Extended types
|
||||||
^^^^^^^^^^^^^^^
|
^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
It is also possible to pack/unpack custom data types using the msgpack 2.0 feature.
|
It is also possible to pack/unpack custom data types using the **ext** type.
|
||||||
|
|
||||||
.. code-block:: pycon
|
.. code-block:: pycon
|
||||||
|
|
||||||
|
|
@ -238,6 +190,58 @@ callback function:
|
||||||
unpacker.skip(bytestream.write)
|
unpacker.skip(bytestream.write)
|
||||||
worker.send(bytestream.getvalue())
|
worker.send(bytestream.getvalue())
|
||||||
|
|
||||||
|
|
||||||
|
Notes
|
||||||
|
-----
|
||||||
|
|
||||||
|
string and binary type
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
In old days, msgpack doesn't distinguish string and binary types like Python 1.
|
||||||
|
The type for represent string and binary types is named **raw**.
|
||||||
|
|
||||||
|
msgpack can distinguish string and binary type for now. But it is not like Python 2.
|
||||||
|
Python 2 added unicode string. But msgpack renamed **raw** to **str** and added **bin** type.
|
||||||
|
It is because keep compatibility with data created by old libs. **raw** was used for text more than binary.
|
||||||
|
|
||||||
|
Currently, while msgpack-python supports new **bin** type, default setting doesn't use it and
|
||||||
|
decodes **raw** as `bytes` instead of `unicode` (`str` in Python 3).
|
||||||
|
|
||||||
|
You can change this by using `use_bin_type=True` option in Packer and `encoding="utf-8"` option in Unpacker.
|
||||||
|
|
||||||
|
.. code-block:: pycon
|
||||||
|
|
||||||
|
>>> import msgpack
|
||||||
|
>>> packed = msgpack.packb([b'spam', u'egg'], use_bin_type=True)
|
||||||
|
>>> msgpack.unpackb(packed, encoding='utf-8')
|
||||||
|
['spam', u'egg']
|
||||||
|
|
||||||
|
ext type
|
||||||
|
^^^^^^^^
|
||||||
|
|
||||||
|
To use **ext** type, pass ``msgpack.ExtType`` object to packer.
|
||||||
|
|
||||||
|
.. code-block:: pycon
|
||||||
|
|
||||||
|
>>> import msgpack
|
||||||
|
>>> packed = msgpack.packb(msgpack.ExtType(42, b'xyzzy'))
|
||||||
|
>>> msgpack.unpackb(packed)
|
||||||
|
ExtType(code=42, data='xyzzy')
|
||||||
|
|
||||||
|
You can use it with ``default`` and ``ext_hook``. See below.
|
||||||
|
|
||||||
|
Note for msgpack-python 0.2.x users
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
The msgpack-python 0.3 have some incompatible changes.
|
||||||
|
|
||||||
|
The default value of ``use_list`` keyword argument is ``True`` from 0.3.
|
||||||
|
You should pass the argument explicitly for backward compatibility.
|
||||||
|
|
||||||
|
`Unpacker.unpack()` and some unpack methods now raises `OutOfData`
|
||||||
|
instead of `StopIteration`.
|
||||||
|
`StopIteration` is used for iterator protocol only.
|
||||||
|
|
||||||
Note about performance
|
Note about performance
|
||||||
------------------------
|
------------------------
|
||||||
|
|
||||||
|
|
@ -259,12 +263,17 @@ Python's dict can't use list as key and MessagePack allows array for key of mapp
|
||||||
Another way to unpacking such object is using ``object_pairs_hook``.
|
Another way to unpacking such object is using ``object_pairs_hook``.
|
||||||
|
|
||||||
|
|
||||||
|
Development
|
||||||
|
------------
|
||||||
|
|
||||||
Test
|
Test
|
||||||
----
|
^^^^
|
||||||
|
|
||||||
MessagePack uses `pytest` for testing.
|
MessagePack uses `pytest` for testing.
|
||||||
Run test with following command:
|
Run test with following command:
|
||||||
|
|
||||||
$ py.test
|
$ py.test
|
||||||
|
|
||||||
|
|
||||||
..
|
..
|
||||||
vim: filetype=rst
|
vim: filetype=rst
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue