| single |
# MessagePack for Python
[Build Status]
[Documentation Status]
## What's this
[MessagePack] is an efficient binary serialization format.
It lets you exchange data among multiple languages like JSON.
But it's faster and smaller.
This package provides CPython bindings for reading and writing MessagePack
data.
## Very important notes for existing users
### PyPI package name
Package name on PyPI was changed from `msgpack-python` to `msgpack` from
0.5.
When upgrading from msgpack-0.4 or earlier, do `pip uninstall
msgpack-python` before
`pip install -U msgpack`.
### Compatibility with the old format
You can use `use_bin_type=False` option to pack `bytes`
object into raw type in the old msgpack spec, instead of bin type in new
msgpack spec.
You can unpack old msgpack format using `raw=True` option.
It unpacks str (raw) type in msgpack into Python bytes.
See note below for detail.
### Major breaking changes in msgpack 1.0
* Python 2
* The extension module does not support Python 2 anymore.
The pure Python implementation (`msgpack.fallback`) is used for Python
2.
* Packer
* `use_bin_type=True` by default. bytes are encoded in bin type in
msgpack.
**If you are still using Python 2, you must use unicode for all string
types.**
You can use `use_bin_type=False` to encode into old msgpack format.
* `encoding` option is removed. UTF-8 is used always.
* Unpacker
* `raw=False` by default. It assumes str types are valid UTF-8 string
and decode them to Python str (unicode) object.
* `encoding` option is removed. You can use `raw=True` to support old
format.
* Default value of `max_buffer_size` is changed from 0 to 100 MiB.
* Default value of `strict_map_key` is changed to True to avoid hashdos.
You need to pass `strict_map_key=False` if you have data which contain
map keys
which type is not bytes or str.
## Install
```
$ pip install msgpack
```
### Pure Python implementation
The extension module in msgpack (`msgpack._cmsgpack`) does not support
Python 2 and PyPy.
But msgpack provides a pure Python implementation (`msgpack.fallback`)
for PyPy and Python 2.
Since the [pip] uses the pure Python implementation,
Python 2 support will not be dropped in the foreseeable future.
### Windows
When you can't use a binary distribution, you need to install Visual Studio
or Windows SDK on Windows.
Without extension, using pure Python implementation on CPython runs slowly.
## How to use
NOTE: In examples below, I use `raw=False` and `use_bin_type=True` for
users
using msgpack < 1.0. These options are default from msgpack 1.0 so you can
omit them.
### One-shot pack & unpack
Use `packb` for packing and `unpackb` for unpacking.
msgpack provides `dumps` and `loads` as an alias for compatibility with
`json` and `pickle`.
|