Stowage/msgpack-python
2
0
Fork 0
mirror of https://github.com/msgpack/msgpack-python.git synced 2025-10-19 12:03:15 +00:00
Code Issues Projects Releases Packages Wiki Activity

README: fix typos and grammar (#648)

Browse source
This commit is contained in:
TW 2025-10-08 09:10:46 +02:00 • committed by GitHub
parent c2a9f1fda5
commit 0f3c4be465
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 32 additions and 32 deletions
Download patch file Download diff file Expand all files Collapse all files

64
README.md
View file

@ -3,7 +3,7 @@
[![Build Status](https://github.com/msgpack/msgpack-python/actions/workflows/wheel.yml/badge.svg)](https://github.com/msgpack/msgpack-python/actions/workflows/wheel.yml) [![Build Status](https://github.com/msgpack/msgpack-python/actions/workflows/wheel.yml/badge.svg)](https://github.com/msgpack/msgpack-python/actions/workflows/wheel.yml)
[![Documentation Status](https://readthedocs.org/projects/msgpack-python/badge/?version=latest)](https://msgpack-python.readthedocs.io/en/latest/?badge=latest) [![Documentation Status](https://readthedocs.org/projects/msgpack-python/badge/?version=latest)](https://msgpack-python.readthedocs.io/en/latest/?badge=latest)
## What's this ## What is this?
[MessagePack](https://msgpack.org/) is an efficient binary serialization format. [MessagePack](https://msgpack.org/) is an efficient binary serialization format.
It lets you exchange data among multiple languages like JSON. It lets you exchange data among multiple languages like JSON.
@ -25,9 +25,9 @@ But msgpack provides a pure Python implementation (`msgpack.fallback`) for PyPy.
### Windows ### Windows
When you can't use a binary distribution, you need to install Visual Studio If you can't use a binary distribution, you need to install Visual Studio
or Windows SDK on Windows. or the Windows SDK on Windows.
Without extension, using pure Python implementation on CPython runs slowly. Without the extension, the pure Python implementation on CPython runs slowly.
## How to use ## How to use
@ -35,11 +35,11 @@ Without extension, using pure Python implementation on CPython runs slowly.
### One-shot pack & unpack ### One-shot pack & unpack
Use `packb` for packing and `unpackb` for unpacking. Use `packb` for packing and `unpackb` for unpacking.
msgpack provides `dumps` and `loads` as an alias for compatibility with msgpack provides `dumps` and `loads` as aliases for compatibility with
`json` and `pickle`. `json` and `pickle`.
`pack` and `dump` packs to a file-like object. `pack` and `dump` pack to a file-like object.
`unpack` and `load` unpacks from a file-like object. `unpack` and `load` unpack from a file-like object.
```pycon ```pycon
>>> import msgpack >>> import msgpack
@ -73,7 +73,7 @@ for unpacked in unpacker:
``` ```
### Packing/unpacking of custom data type ### Packing/unpacking of custom data types
It is also possible to pack/unpack custom data types. Here is an example for It is also possible to pack/unpack custom data types. Here is an example for
`datetime.datetime`. `datetime.datetime`.
@ -140,8 +140,8 @@ True
### Advanced unpacking control ### Advanced unpacking control
As an alternative to iteration, `Unpacker` objects provide `unpack`, As an alternative to iteration, `Unpacker` objects provide `unpack`,
`skip`, `read_array_header` and `read_map_header` methods. The former two `skip`, `read_array_header`, and `read_map_header` methods. The former two
read an entire message from the stream, respectively de-serialising and returning read an entire message from the stream, respectively deserializing and returning
the result, or ignoring it. The latter two methods return the number of elements the result, or ignoring it. The latter two methods return the number of elements
in the upcoming container, so that each element in an array, or key-value pair in the upcoming container, so that each element in an array, or key-value pair
in a map, can be unpacked or skipped individually. in a map, can be unpacked or skipped individually.
@ -149,7 +149,7 @@ in a map, can be unpacked or skipped individually.
## Notes ## Notes
### string and binary type in old msgpack spec ### String and binary types in the old MessagePack spec
Early versions of msgpack didn't distinguish string and binary types. Early versions of msgpack didn't distinguish string and binary types.
The type for representing both string and binary types was named **raw**. The type for representing both string and binary types was named **raw**.
@ -167,7 +167,7 @@ and `raw=True` options.
### ext type ### ext type
To use the **ext** type, pass `msgpack.ExtType` object to packer. To use the **ext** type, pass a `msgpack.ExtType` object to the packer.
```pycon ```pycon
>>> import msgpack >>> import msgpack
@ -181,26 +181,26 @@ You can use it with `default` and `ext_hook`. See below.
### Security ### Security
To unpacking data received from unreliable source, msgpack provides When unpacking data received from an unreliable source, msgpack provides
two security options. two security options.
`max_buffer_size` (default: `100*1024*1024`) limits the internal buffer size. `max_buffer_size` (default: `100*1024*1024`) limits the internal buffer size.
It is used to limit the preallocated list size too. It is also used to limit preallocated list sizes.
`strict_map_key` (default: `True`) limits the type of map keys to bytes and str. `strict_map_key` (default: `True`) limits the type of map keys to bytes and str.
While msgpack spec doesn't limit the types of the map keys, While the MessagePack spec doesn't limit map key types,
there is a risk of the hashdos. there is a risk of a hash DoS.
If you need to support other types for map keys, use `strict_map_key=False`. If you need to support other types for map keys, use `strict_map_key=False`.
### Performance tips ### Performance tips
CPython's GC starts when growing allocated object. CPython's GC starts when the number of allocated objects grows.
This means unpacking may cause useless GC. This means unpacking may trigger unnecessary GC.
You can use `gc.disable()` when unpacking large message. You can use `gc.disable()` when unpacking a large message.
List is the default sequence type of Python. A list is the default sequence type in Python.
But tuple is lighter than list. However, a tuple is lighter than a list.
You can use `use_list=False` while unpacking when performance is important. You can use `use_list=False` while unpacking when performance is important.
@ -208,7 +208,7 @@ You can use `use_list=False` while unpacking when performance is important.
### msgpack 0.5 ### msgpack 0.5
Package name on PyPI was changed from `msgpack-python` to `msgpack` from 0.5. The package name on PyPI was changed from `msgpack-python` to `msgpack` in 0.5.
When upgrading from msgpack-0.4 or earlier, do `pip uninstall msgpack-python` before When upgrading from msgpack-0.4 or earlier, do `pip uninstall msgpack-python` before
`pip install -U msgpack`. `pip install -U msgpack`.
@ -218,25 +218,25 @@ When upgrading from msgpack-0.4 or earlier, do `pip uninstall msgpack-python` be
* Python 2 support * Python 2 support
* The extension module does not support Python 2 anymore. * The extension module no longer supports Python 2.
The pure Python implementation (`msgpack.fallback`) is used for Python 2. The pure Python implementation (`msgpack.fallback`) is used for Python 2.
* msgpack 1.0.6 drops official support of Python 2.7, as pip and * msgpack 1.0.6 drops official support of Python 2.7, as pip and
GitHub Action (setup-python) no longer support Python 2.7. GitHub Action "setup-python" no longer supports Python 2.7.
* Packer * Packer
* Packer uses `use_bin_type=True` by default. * Packer uses `use_bin_type=True` by default.
Bytes are encoded in bin type in msgpack. Bytes are encoded in the bin type in MessagePack.
* The `encoding` option is removed. UTF-8 is used always. * The `encoding` option is removed. UTF-8 is always used.
* Unpacker * Unpacker
* Unpacker uses `raw=False` by default. It assumes str types are valid UTF-8 string * Unpacker uses `raw=False` by default. It assumes str values are valid UTF-8 strings
and decode them to Python str (unicode) object. and decodes them to Python str (Unicode) objects.
* `encoding` option is removed. You can use `raw=True` to support old format (e.g. unpack into bytes, not str). * `encoding` option is removed. You can use `raw=True` to support old format (e.g. unpack into bytes, not str).
* Default value of `max_buffer_size` is changed from 0 to 100 MiB to avoid DoS attack. * The default value of `max_buffer_size` is changed from 0 to 100 MiB to avoid DoS attacks.
You need to pass `max_buffer_size=0` if you have large but safe data. You need to pass `max_buffer_size=0` if you have large but safe data.
* Default value of `strict_map_key` is changed to True to avoid hashdos. * The default value of `strict_map_key` is changed to True to avoid hash DoS.
You need to pass `strict_map_key=False` if you have data which contain map keys You need to pass `strict_map_key=False` if you have data that contain map keys
which type is not bytes or str. whose type is neither bytes nor str.