@@ -28,10 +28,10 @@ msgpack is removed, and `import msgpack` fail.
28
28
29
29
### Compatibility with the old format
30
30
31
- You can use `` use_bin_type=False `` option to pack `` bytes ` `
31
+ You can use ` use_bin_type=False ` option to pack ` bytes `
32
32
object into raw type in the old msgpack spec, instead of bin type in new msgpack spec.
33
33
34
- You can unpack old msgpack format using `` raw=True ` ` option.
34
+ You can unpack old msgpack format using ` raw=True ` option.
35
35
It unpacks str (raw) type in msgpack into Python bytes.
36
36
37
37
See note below for detail.
@@ -42,23 +42,23 @@ See note below for detail.
42
42
* Python 2
43
43
44
44
* The extension module does not support Python 2 anymore.
45
- The pure Python implementation (`` msgpack.fallback ` ` ) is used for Python 2.
45
+ The pure Python implementation (` msgpack.fallback ` ) is used for Python 2.
46
46
47
47
* Packer
48
48
49
- * `` use_bin_type=True ` ` by default. bytes are encoded in bin type in msgpack.
49
+ * ` use_bin_type=True ` by default. bytes are encoded in bin type in msgpack.
50
50
** If you are still sing Python 2, you must use unicode for all string types.**
51
- You can use `` use_bin_type=False ` ` to encode into old msgpack format.
52
- * `` encoding ` ` option is removed. UTF-8 is used always.
51
+ You can use ` use_bin_type=False ` to encode into old msgpack format.
52
+ * ` encoding ` option is removed. UTF-8 is used always.
53
53
54
54
* Unpacker
55
55
56
- * `` raw=False ` ` by default. It assumes str types are valid UTF-8 string
56
+ * ` raw=False ` by default. It assumes str types are valid UTF-8 string
57
57
and decode them to Python str (unicode) object.
58
- * `` encoding `` option is removed. You can use `` raw=True ` ` to support old format.
59
- * Default value of `` max_buffer_size ` ` is changed from 0 to 100 MiB.
60
- * Default value of `` strict_map_key ` ` is changed to True to avoid hashdos.
61
- You need to pass `` strict_map_key=False ` ` if you have data which contain map keys
58
+ * ` encoding ` option is removed. You can use ` raw=True ` to support old format.
59
+ * Default value of ` max_buffer_size ` is changed from 0 to 100 MiB.
60
+ * Default value of ` strict_map_key ` is changed to True to avoid hashdos.
61
+ You need to pass ` strict_map_key=False ` if you have data which contain map keys
62
62
which type is not bytes or str.
63
63
64
64
@@ -70,10 +70,10 @@ See note below for detail.
70
70
71
71
### Pure Python implementation
72
72
73
- The extension module in msgpack (`` msgpack._cmsgpack ` ` ) does not support
73
+ The extension module in msgpack (` msgpack._cmsgpack ` ) does not support
74
74
Python 2 and PyPy.
75
75
76
- But msgpack provides a pure Python implementation (`` msgpack.fallback ` ` )
76
+ But msgpack provides a pure Python implementation (` msgpack.fallback ` )
77
77
for PyPy and Python 2.
78
78
79
79
Since the [ pip] ( https://pip.pypa.io/ ) uses the pure Python implementation,
@@ -89,18 +89,18 @@ Without extension, using pure Python implementation on CPython runs slowly.
89
89
90
90
## How to use
91
91
92
- NOTE: In examples below, I use `` raw=False `` and `` use_bin_type=True ` ` for users
92
+ NOTE: In examples below, I use ` raw=False ` and ` use_bin_type=True ` for users
93
93
using msgpack < 1.0. These options are default from msgpack 1.0 so you can omit them.
94
94
95
95
96
96
### One-shot pack & unpack
97
97
98
- Use `` packb `` for packing and `` unpackb ` ` for unpacking.
99
- msgpack provides `` dumps `` and `` loads ` ` as an alias for compatibility with
100
- `` json `` and `` pickle ` ` .
98
+ Use ` packb ` for packing and ` unpackb ` for unpacking.
99
+ msgpack provides ` dumps ` and ` loads ` as an alias for compatibility with
100
+ ` json ` and ` pickle ` .
101
101
102
- `` pack `` and `` dump ` ` packs to a file-like object.
103
- `` unpack `` and `` load ` ` unpacks from a file-like object.
102
+ ` pack ` and ` dump ` packs to a file-like object.
103
+ ` unpack ` and ` load ` unpacks from a file-like object.
104
104
105
105
``` pycon
106
106
>>> import msgpack
@@ -110,23 +110,23 @@ msgpack provides ``dumps`` and ``loads`` as an alias for compatibility with
110
110
[1, 2, 3]
111
111
```
112
112
113
- `` unpack ` ` unpacks msgpack's array to Python's list, but can also unpack to tuple:
113
+ ` unpack ` unpacks msgpack's array to Python's list, but can also unpack to tuple:
114
114
115
115
``` pycon
116
116
>>> msgpack.unpackb(b'\x93\x01\x02\x03', use_list=False, raw=False)
117
117
(1, 2, 3)
118
118
```
119
119
<
628C
td data-grid-cell-id="diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5-119-119-2" data-line-anchor="diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5R119" data-selected="false" role="gridcell" style="background-color:var(--bgColor-default);padding-right:24px" tabindex="-1" valign="top" class="focusable-grid-cell diff-text-cell right-side-diff-cell left-side">
120
- You should always specify the `` use_list ` ` keyword argument for backward compatibility.
120
+ You should always specify the ` use_list ` keyword argument for backward compatibility.
121
121
See performance issues relating to ` use_list option ` _ below.
122
122
123
123
Read the docstring for other options.
124
124
125
125
126
126
### Streaming unpacking
127
127
128
- `` Unpacker ` ` is a "streaming unpacker". It unpacks multiple objects from one
129
- stream (or from bytes provided through its `` feed ` ` method).
128
+ ` Unpacker ` is a "streaming unpacker". It unpacks multiple objects from one
129
+ stream (or from bytes provided through its ` feed ` method).
130
130
131
131
``` py
132
132
import msgpack
@@ -147,7 +147,7 @@ stream (or from bytes provided through its ``feed`` method).
147
147
### Packing/unpacking of custom data type
148
148
149
149
It is also possible to pack/unpack custom data types. Here is an example for
150
- `` datetime.datetime ` ` .
150
+ ` datetime.datetime ` .
151
151
152
152
``` py
153
153
import datetime
@@ -173,8 +173,8 @@ It is also possible to pack/unpack custom data types. Here is an example for
173
173
this_dict_again = msgpack.unpackb(packed_dict, object_hook = decode_datetime, raw = False )
174
174
```
175
175
176
- `` Unpacker `` 's `` object_hook ` ` callback receives a dict; the
177
- `` object_pairs_hook ` ` callback may instead be used to receive a list of
176
+ ` Unpacker ` 's ` object_hook ` callback receives a dict; the
177
+ ` object_pairs_hook ` callback may instead be used to receive a list of
178
178
key-value pairs.
179
179
180
180
@@ -207,8 +207,8 @@ It is also possible to pack/unpack custom data types using the **ext** type.
207
207
208
208
### Advanced unpacking control
209
209
210
- As an alternative to iteration, `` Unpacker `` objects provide `` unpack ` ` ,
211
- `` skip `` , `` read_array_header `` and `` read_map_header ` ` methods. The former two
210
+ As an alternative to iteration, ` Unpacker ` objects provide ` unpack ` ,
211
+ ` skip ` , ` read_array_header ` and ` read_map_header ` methods. The former two
212
212
read an entire message from the stream, respectively de-serialising and returning
213
213
the result, or ignoring it. The latter two methods return the number of elements
214
214
in the upcoming container, so that each element in an array, or key-value pair
@@ -222,8 +222,8 @@ in a map, can be unpacked or skipped individually.
222
222
Early versions of msgpack didn't distinguish string and binary types.
223
223
The type for representing both string and binary types was named ** raw** .
224
224
225
- You can pack into and unpack from this old spec using `` use_bin_type=False ` `
226
- and `` raw=True ` ` options.
225
+ You can pack into and unpack from this old spec using ` use_bin_type=False `
226
+ and ` raw=True ` options.
227
227
228
228
``` pycon
229
229
>>> import msgpack
@@ -235,7 +235,7 @@ and ``raw=True`` options.
235
235
236
236
### ext type
237
237
238
- To use the ** ext** type, pass `` msgpack.ExtType ` ` object to packer.
238
+ To use the ** ext** type, pass ` msgpack.ExtType ` object to packer.
239
239
240
240
``` pycon
241
241
>>> import msgpack
@@ -244,32 +244,32 @@ To use the **ext** type, pass ``msgpack.ExtType`` object to packer.
244
244
ExtType(code=42, data='xyzzy')
245
245
```
246
246
247
- You can use it with `` default `` and `` ext_hook ` ` . See below.
247
+ You can use it with ` default ` and ` ext_hook ` . See below.
248
248
249
249
250
250
### Security
251
251
252
252
To unpacking data received from unreliable source, msgpack provides
253
253
two security options.
254
254
255
- `` max_buffer_size `` (default: 100* 1024* 1024) limits the internal buffer size.
255
+ ` max_buffer_size ` (default: ` 100*1024*1024 ` ) limits the internal buffer size.
256
256
It is used to limit the preallocated list size too.
257
257
258
- `` strict_map_key `` (default: `` True ` ` ) limits the type of map keys to bytes and str.
258
+ ` strict_map_key ` (default: ` True ` ) limits the type of map keys to bytes and str.
259
259
While msgpack spec doesn't limit the types of the map keys,
260
260
there is a risk of the hashdos.
261
- If you need to support other types for map keys, use `` strict_map_key=False ` ` .
261
+ If you need to support other types for map keys, use ` strict_map_key=False ` .
262
262
263
263
264
264
### Performance tips
265
265
266
266
CPython's GC starts when growing allocated object.
267
267
This means unpacking may cause useless GC.
268
- You can use `` gc.disable() ` ` when unpacking large message.
268
+ You can use ` gc.disable() ` when unpacking large message.
269
269
270
270
List is the default sequence type of Python.
271
271
But tuple is lighter than list.
272
- You can use `` use_list=False ` ` while unpacking when performance is important.
272
+ You can use ` use_list=False ` while unpacking when performance is important.
273
273
274
274
275
275
## Development
0 commit comments