codekingpro/portable-devtools

1Metadata-Version: 2.4
2Name: msgpack
3Version: 1.1.2
4Summary: MessagePack serializer
5Author-email: Inada Naoki <songofacandy@gmail.com>
6License-Expression: Apache-2.0
7Project-URL: Homepage, https://msgpack.org/
8Project-URL: Documentation, https://msgpack-python.readthedocs.io/
9Project-URL: Repository, https://github.com/msgpack/msgpack-python/
10Project-URL: Tracker, https://github.com/msgpack/msgpack-python/issues
11Project-URL: Changelog, https://github.com/msgpack/msgpack-python/blob/main/ChangeLog.rst
12Keywords: msgpack,messagepack,serializer,serialization,binary
13Classifier: Development Status :: 5 - Production/Stable
14Classifier: Operating System :: OS Independent
15Classifier: Topic :: File Formats
16Classifier: Intended Audience :: Developers
17Classifier: Programming Language :: Python :: Implementation :: CPython
18Classifier: Programming Language :: Python :: Implementation :: PyPy
19Requires-Python: >=3.9
20Description-Content-Type: text/markdown
21License-File: COPYING
22Dynamic: license-file
23
24# MessagePack for Python
25
26[![Build Status](https://github.com/msgpack/msgpack-python/actions/workflows/wheel.yml/badge.svg)](https://github.com/msgpack/msgpack-python/actions/workflows/wheel.yml)
27[![Documentation Status](https://readthedocs.org/projects/msgpack-python/badge/?version=latest)](https://msgpack-python.readthedocs.io/en/latest/?badge=latest)
28
29## What is this?
30
31[MessagePack](https://msgpack.org/) is an efficient binary serialization format.
32It lets you exchange data among multiple languages like JSON.
33But it's faster and smaller.
34This package provides CPython bindings for reading and writing MessagePack data.
35
36## Install
37
38```
39$ pip install msgpack
40```
41
42### Pure Python implementation
43
44The extension module in msgpack (`msgpack._cmsgpack`) does not support PyPy.
45
46But msgpack provides a pure Python implementation (`msgpack.fallback`) for PyPy.
47
48
49### Windows
50
51If you can't use a binary distribution, you need to install Visual Studio
52or the Windows SDK on Windows.
53Without the extension, the pure Python implementation on CPython runs slowly.
54
55
56## How to use
57
58### One-shot pack & unpack
59
60Use `packb` for packing and `unpackb` for unpacking.
61msgpack provides `dumps` and `loads` as aliases for compatibility with
62`json` and `pickle`.
63
64`pack` and `dump` pack to a file-like object.
65`unpack` and `load` unpack from a file-like object.
66
67```pycon
68>>> import msgpack
69>>> msgpack.packb([1, 2, 3])
70'\x93\x01\x02\x03'
71>>> msgpack.unpackb(_)
72[1, 2, 3]
73```
74
75Read the docstring for options.
76
77
78### Streaming unpacking
79
80`Unpacker` is a "streaming unpacker". It unpacks multiple objects from one
81stream (or from bytes provided through its `feed` method).
82
83```py
84import msgpack
85from io import BytesIO
86
87buf = BytesIO()
88for i in range(100):
89   buf.write(msgpack.packb(i))
90
91buf.seek(0)
92
93unpacker = msgpack.Unpacker(buf)
94for unpacked in unpacker:
95    print(unpacked)
96```
97
98
99### Packing/unpacking of custom data types
100
101It is also possible to pack/unpack custom data types. Here is an example for
102`datetime.datetime`.
103
104```py
105import datetime
106import msgpack
107
108useful_dict = {
109    "id": 1,
110    "created": datetime.datetime.now(),
111}
112
113def decode_datetime(obj):
114    if '__datetime__' in obj:
115        obj = datetime.datetime.strptime(obj["as_str"], "%Y%m%dT%H:%M:%S.%f")
116    return obj
117
118def encode_datetime(obj):
119    if isinstance(obj, datetime.datetime):
120        return {'__datetime__': True, 'as_str': obj.strftime("%Y%m%dT%H:%M:%S.%f")}
121    return obj
122
123
124packed_dict = msgpack.packb(useful_dict, default=encode_datetime)
125this_dict_again = msgpack.unpackb(packed_dict, object_hook=decode_datetime)
126```
127
128`Unpacker`'s `object_hook` callback receives a dict; the
129`object_pairs_hook` callback may instead be used to receive a list of
130key-value pairs.
131
132NOTE: msgpack can encode datetime with tzinfo into standard ext type for now.
133See `datetime` option in `Packer` docstring.
134
135
136### Extended types
137
138It is also possible to pack/unpack custom data types using the **ext** type.
139
140```pycon
141>>> import msgpack
142>>> import array
143>>> def default(obj):
144...     if isinstance(obj, array.array) and obj.typecode == 'd':
145...         return msgpack.ExtType(42, obj.tostring())
146...     raise TypeError("Unknown type: %r" % (obj,))
147...
148>>> def ext_hook(code, data):
149...     if code == 42:
150...         a = array.array('d')
151...         a.fromstring(data)
152...         return a
153...     return ExtType(code, data)
154...
155>>> data = array.array('d', [1.2, 3.4])
156>>> packed = msgpack.packb(data, default=default)
157>>> unpacked = msgpack.unpackb(packed, ext_hook=ext_hook)
158>>> data == unpacked
159True
160```
161
162
163### Advanced unpacking control
164
165As an alternative to iteration, `Unpacker` objects provide `unpack`,
166`skip`, `read_array_header`, and `read_map_header` methods. The former two
167read an entire message from the stream, respectively deserializing and returning
168the result, or ignoring it. The latter two methods return the number of elements
169in the upcoming container, so that each element in an array, or key-value pair
170in a map, can be unpacked or skipped individually.
171
172
173## Notes
174
175### String and binary types in the old MessagePack spec
176
177Early versions of msgpack didn't distinguish string and binary types.
178The type for representing both string and binary types was named **raw**.
179
180You can pack into and unpack from this old spec using `use_bin_type=False`
181and `raw=True` options.
182
183```pycon
184>>> import msgpack
185>>> msgpack.unpackb(msgpack.packb([b'spam', 'eggs'], use_bin_type=False), raw=True)
186[b'spam', b'eggs']
187>>> msgpack.unpackb(msgpack.packb([b'spam', 'eggs'], use_bin_type=True), raw=False)
188[b'spam', 'eggs']
189```
190
191### ext type
192
193To use the **ext** type, pass a `msgpack.ExtType` object to the packer.
194
195```pycon
196>>> import msgpack
197>>> packed = msgpack.packb(msgpack.ExtType(42, b'xyzzy'))
198>>> msgpack.unpackb(packed)
199ExtType(code=42, data='xyzzy')
200```
201
202You can use it with `default` and `ext_hook`. See below.
203
204
205### Security
206
207When unpacking data received from an unreliable source, msgpack provides
208two security options.
209
210`max_buffer_size` (default: `100*1024*1024`) limits the internal buffer size.
211It is also used to limit preallocated list sizes.
212
213`strict_map_key` (default: `True`) limits the type of map keys to bytes and str.
214While the MessagePack spec doesn't limit map key types,
215there is a risk of a hash DoS.
216If you need to support other types for map keys, use `strict_map_key=False`.
217
218
219### Performance tips
220
221CPython's GC starts when the number of allocated objects grows.
222This means unpacking may trigger unnecessary GC.
223You can use `gc.disable()` when unpacking a large message.
224
225A list is the default sequence type in Python.
226However, a tuple is lighter than a list.
227You can use `use_list=False` while unpacking when performance is important.
228
229
230## Major breaking changes in the history
231
232### msgpack 0.5
233
234The package name on PyPI was changed from `msgpack-python` to `msgpack` in 0.5.
235
236When upgrading from msgpack-0.4 or earlier, do `pip uninstall msgpack-python` before
237`pip install -U msgpack`.
238
239
240### msgpack 1.0
241
242* Python 2 support
243
244  * The extension module no longer supports Python 2.
245    The pure Python implementation (`msgpack.fallback`) is used for Python 2.
246  
247  * msgpack 1.0.6 drops official support of Python 2.7, as pip and
248    GitHub Action "setup-python" no longer supports Python 2.7.
249
250* Packer
251
252  * Packer uses `use_bin_type=True` by default.
253    Bytes are encoded in the bin type in MessagePack.
254  * The `encoding` option is removed. UTF-8 is always used.
255
256* Unpacker
257
258  * Unpacker uses `raw=False` by default. It assumes str values are valid UTF-8 strings
259    and decodes them to Python str (Unicode) objects.
260  * `encoding` option is removed.  You can use `raw=True` to support old format (e.g. unpack into bytes, not str).
261  * The default value of `max_buffer_size` is changed from 0 to 100 MiB to avoid DoS attacks.
262    You need to pass `max_buffer_size=0` if you have large but safe data.
263  * The default value of `strict_map_key` is changed to True to avoid hash DoS.
264    You need to pass `strict_map_key=False` if you have data that contain map keys
265    whose type is neither bytes nor str.
266