Description

<a href="https://explosion.ai"><img src="https://explosion.ai/assets/img/logo.svg" width="125" height="125" align="right" /></a> # srsly: Modern high-performance serialization utilities for Python This package bundles some of the best Python serialization libraries into one standalone package, with a high-level API that makes it easy to write code that's correct across platforms and Pythons. This allows us to provide all the serialization utilities we need in a single binary wheel. Currently supports **JSON**, **JSONL**, **MessagePack**, **Pickle** and **YAML**. [](https://github.com/explosion/srsly/actions/workflows/tests.yml) [](https://pypi.python.org/pypi/srsly) [](https://anaconda.org/conda-forge/srsly) [](https://github.com/explosion/srsly) [](https://github.com/explosion/wheelwright/releases) ## Motivation Serialization is hard, especially across Python versions and multiple platforms. After dealing with many subtle bugs over the years (encodings, locales, large files) our libraries like [spaCy](https://github.com/explosion/spaCy) and [Prodigy](https://prodi.gy) had steadily grown a number of utility functions to wrap the multiple serialization formats we need to support (especially `json`, `msgpack` and `pickle`). These wrapping functions ended up duplicated across our codebases, so we wanted to put them in one place. At the same time, we noticed that having a lot of small dependencies was making maintenance harder, and making installation slower. To solve this, we've made `srsly` standalone, by including the component packages directly within it. This way we can provide all the serialization utilities we need in a single binary wheel. `srsly` currently includes forks of the following packages: - [`ujson`](https://github.com/esnme/ultrajson) - [`msgpack`](https://github.com/msgpack/msgpack-python) - [`msgpack-numpy`](https://github.com/lebedov/msgpack-numpy) - [`cloudpickle`](https://github.com/cloudpipe/cloudpickle) - [`ruamel.yaml`](https://github.com/pycontribs/ruamel-yaml) (without unsafe implementations!) ## Installation > ⚠️ Note that `v2.x` is only compatible with **Python 3.6+**. For 2.7+ > compatibility, use `v1.x`. `srsly` can be installed from pip. Before installing, make sure that your `pip`, `setuptools` and `wheel` are up to date. ```bash python -m pip install -U pip setuptools wheel python -m pip install srsly ``` Or from conda via conda-forge: ```bash conda install -c conda-forge srsly ``` Alternatively, you can also compile the library from source. You'll need to make sure that you have a development environment with a Python distribution including header files, a compiler (XCode command-line tools on macOS / OS X or Visual C++ build tools on Windows), pip and git installed. Install from source: ```bash # clone the repo git clone https://github.com/explosion/srsly cd srsly # create a virtual environment python -m venv .env source .env/bin/activate # update pip python -m pip install -U pip setuptools wheel # compile and install from source python -m pip install . ``` For developers, install requirements separately and then install in editable mode without build isolation: ```bash # install in editable mode python -m pip install -r requirements.txt python -m pip install --no-build-isolation --editable . # run test suite python -m pytest --pyargs srsly ``` ## API ### JSON > 📦 The underlying module is exposed via `srsly.ujson`. However, we normally > interact with it via the utility functions only. #### <kbd>function</kbd> `srsly.json_dumps` Serialize an object to a JSON string. Falls back to `json` if `sort_keys=True` is used (until it's fixed in `ujson`). ```python data = {"foo": "bar", "baz": 123} json_string = srsly.json_dumps(data) ``` | Argument | Type | Description | | ----------- | ---- | ------------------------------------------------------ | | `data` | - | The JSON-serializable data to output. | | `indent` | int | Number of spaces used to indent JSON. Defaults to `0`. | | `sort_keys` | bool | Sort dictionary keys. Defaults to `False`. | | **RETURNS** | str | The serialized string. | #### <kbd>function</kbd> `srsly.json_loads` Deserialize unicode or bytes to a Python object. ```python data = '{"foo": "bar", "baz": 123}' obj = srsly.json_loads(data) ``` | Argument | Type | Description