3
3
[ ![ Build Status] ( https://github.com/msgpack/msgpack-python/actions/workflows/wheel.yml/badge.svg )] ( https://github.com/msgpack/msgpack-python/actions/workflows/wheel.yml )
4
4
[ ![ Documentation Status] ( https://readthedocs.org/projects/msgpack-python/badge/?version=latest )] ( https://msgpack-python.readthedocs.io/en/latest/?badge=latest )
5
5
6
- ## What's this
6
+ ## What is this?
7
7
8
8
[ MessagePack] ( https://msgpack.org/ ) is an efficient binary serialization format.
9
9
It lets you exchange data among multiple languages like JSON.
@@ -25,21 +25,21 @@ But msgpack provides a pure Python implementation (`msgpack.fallback`) for PyPy.
25
25
26
26
### Windows
27
27
28
- When you can't use a binary distribution, you need to install Visual Studio
29
- or Windows SDK on Windows.
30
- Without extension, using pure Python implementation on CPython runs slowly.
28
+ If you can't use a binary distribution, you need to install Visual Studio
29
+ or the Windows SDK on Windows.
30
+ Without the extension, the pure Python implementation on CPython runs slowly.
31
31
32
32
33
33
## How to use
34
34
35
35
### One-shot pack & unpack
36
36
37
37
Use ` packb ` for packing and ` unpackb ` for unpacking.
38
- msgpack provides ` dumps ` and ` loads ` as an alias for compatibility with
38
+ msgpack provides ` dumps ` and ` loads ` as aliases for compatibility with
39
39
` json ` and ` pickle ` .
40
40
41
- ` pack ` and ` dump ` packs to a file-like object.
42
- ` unpack ` and ` load ` unpacks from a file-like object.
41
+ ` pack ` and ` dump ` pack to a file-like object.
42
+ ` unpack ` and ` load ` unpack from a file-like object.
43
43
44
44
``` pycon
45
45
>>> import msgpack
@@ -73,7 +73,7 @@ for unpacked in unpacker:
73
73
```
74
74
75
75
76
- ### Packing/unpacking of custom data type
76
+ ### Packing/unpacking of custom data types
77
77
78
78
It is also possible to pack/unpack custom data types. Here is an example for
79
79
` datetime.datetime ` .
@@ -140,16 +140,16 @@ True
140
140
### Advanced unpacking control
141
141
142
142
As an alternative to iteration, ` Unpacker ` objects provide ` unpack ` ,
143
- ` skip ` , ` read_array_header ` and ` read_map_header ` methods. The former two
144
- read an entire message from the stream, respectively de-serialising and returning
143
+ ` skip ` , ` read_array_header ` , and ` read_map_header ` methods. The former two
144
+ read an entire message from the stream, respectively deserializing and returning
145
145
the result, or ignoring it. The latter two methods return the number of elements
146
146
in the upcoming container, so that each element in an array, or key-value pair
147
147
in a map, can be unpacked or skipped individually.
148
148
149
149
150
150
## Notes
151
151
152
- ### string and binary type in old msgpack spec
152
+ ### String and binary types in the old MessagePack spec
153
153
154
154
Early versions of msgpack didn't distinguish string and binary types.
155
155
The type for representing both string and binary types was named ** raw** .
@@ -167,7 +167,7 @@ and `raw=True` options.
167
167
168
168
### ext type
169
169
170
- To use the ** ext** type, pass ` msgpack.ExtType ` object to packer.
170
+ To use the ** ext** type, pass a ` msgpack.ExtType ` object to the packer.
171
171
172
172
``` pycon
173
173
>>> import msgpack
@@ -181,34 +181,34 @@ You can use it with `default` and `ext_hook`. See below.
181
181
182
182
### Security
183
183
184
- To unpacking data received from unreliable source, msgpack provides
184
+ When unpacking data received from an unreliable source, msgpack provides
185
185
two security options.
186
186
187
187
` max_buffer_size ` (default: ` 100*1024*1024 ` ) limits the internal buffer size.
188
- It is used to limit the preallocated list size too .
188
+ It is also used to limit preallocated list sizes .
189
189
190
190
` strict_map_key ` (default: ` True ` ) limits the type of map keys to bytes and str.
191
- While msgpack spec doesn't limit the types of the map keys ,
192
- there is a risk of the hashdos .
191
+ While the MessagePack spec doesn't limit map key types ,
192
+ there is a risk of a hash DoS .
193
193
If you need to support other types for map keys, use ` strict_map_key=False ` .
194
194
195
195
196
196
### Performance tips
197
197
198
- CPython's GC starts when growing allocated object .
199
- This means unpacking may cause useless GC.
200
- You can use ` gc.disable() ` when unpacking large message.
198
+ CPython's GC starts when the number of allocated objects grows .
199
+ This means unpacking may trigger unnecessary GC.
200
+ You can use ` gc.disable() ` when unpacking a large message.
201
201
202
- List is the default sequence type of Python.
203
- But tuple is lighter than list.
202
+ A list is the default sequence type in Python.
203
+ However, a tuple is lighter than a list.
204
204
You can use ` use_list=False ` while unpacking when performance is important.
205
205
206
206
207
207
## Major breaking changes in the history
208
208
209
209
### msgpack 0.5
210
210
211
- Package name on PyPI was changed from ` msgpack-python ` to ` msgpack ` from 0.5.
211
+ The package name on PyPI was changed from ` msgpack-python ` to ` msgpack ` in 0.5.
212
212
213
213
When upgrading from msgpack-0.4 or earlier, do ` pip uninstall msgpack-python ` before
214
214
` pip install -U msgpack ` .
@@ -218,25 +218,25 @@ When upgrading from msgpack-0.4 or earlier, do `pip uninstall msgpack-python` be
218
218
219
219
* Python 2 support
220
220
221
- * The extension module does not support Python 2 anymore .
221
+ * The extension module no longer supports Python 2.
222
222
The pure Python implementation (` msgpack.fallback ` ) is used for Python 2.
223
223
224
224
* msgpack 1.0.6 drops official support of Python 2.7, as pip and
225
- GitHub Action ( setup-python) no longer support Python 2.7.
225
+ GitHub Action " setup-python" no longer supports Python 2.7.
226
226
227
227
* Packer
228
228
229
229
* Packer uses ` use_bin_type=True ` by default.
230
- Bytes are encoded in bin type in msgpack .
231
- * The ` encoding ` option is removed. UTF-8 is used always.
230
+ Bytes are encoded in the bin type in MessagePack .
231
+ * The ` encoding ` option is removed. UTF-8 is always used .
232
232
233
233
* Unpacker
234
234
235
- * Unpacker uses ` raw=False ` by default. It assumes str types are valid UTF-8 string
236
- and decode them to Python str (unicode) object .
235
+ * Unpacker uses ` raw=False ` by default. It assumes str values are valid UTF-8 strings
236
+ and decodes them to Python str (Unicode) objects .
237
237
* ` encoding ` option is removed. You can use ` raw=True ` to support old format (e.g. unpack into bytes, not str).
238
- * Default value of ` max_buffer_size ` is changed from 0 to 100 MiB to avoid DoS attack .
238
+ * The default value of ` max_buffer_size ` is changed from 0 to 100 MiB to avoid DoS attacks .
239
239
You need to pass ` max_buffer_size=0 ` if you have large but safe data.
240
- * Default value of ` strict_map_key ` is changed to True to avoid hashdos .
241
- You need to pass ` strict_map_key=False ` if you have data which contain map keys
242
- which type is not bytes or str.
240
+ * The default value of ` strict_map_key ` is changed to True to avoid hash DoS .
241
+ You need to pass ` strict_map_key=False ` if you have data that contain map keys
242
+ whose type is neither bytes nor str.
0 commit comments