0
# srsly
1

2
Modern high-performance serialization utilities for Python that bundle JSON, MessagePack, and pickle serialization into a single package with a unified API. srsly provides cross-platform compatibility, optimized performance through C extensions, and comprehensive serialization support with zero external dependencies.
3

4
## Package Information
5

6
- **Package Name**: srsly
7
- **Language**: Python
8
- **Installation**: `pip install srsly`
9

10
## Core Imports
11

12
```python
13
import srsly
14
```
15

16
All functions are available directly from the main module:
17

18
```python
19
from srsly import json_dumps, json_loads, msgpack_dumps, msgpack_loads, pickle_dumps, pickle_loads
20
```
21

22
For advanced usage, access underlying modules:
23

24
```python
25
import srsly.ujson      # High-performance JSON
26
import srsly.msgpack    # MessagePack with numpy support
27
import srsly.cloudpickle # Enhanced pickle
28
```
29

30
## Basic Usage
31

32
```python
33
import srsly
34

35
# JSON serialization
36
data = {"name": "John", "age": 30, "scores": [85, 92, 78]}
37
json_string = srsly.json_dumps(data, indent=2)
38
parsed_data = srsly.json_loads(json_string)
39

40
# File operations
41
srsly.write_json("data.json", data)
42
loaded_data = srsly.read_json("data.json")
43

44
# JSONL (newline-delimited JSON)
45
lines = [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]
46
srsly.write_jsonl("data.jsonl", lines)
47
for item in srsly.read_jsonl("data.jsonl"):
48
    print(item)
49

50
# MessagePack serialization
51
msgpack_bytes = srsly.msgpack_dumps(data)
52
restored_data = srsly.msgpack_loads(msgpack_bytes)
53

54
# Pickle serialization
55
pickle_bytes = srsly.pickle_dumps(data)
56
unpickled_data = srsly.pickle_loads(pickle_bytes)
57
```
58

59
## Architecture
60

61
srsly integrates optimized forks of leading Python serialization libraries:
62

63
- **ujson**: Ultra-fast JSON encoding/decoding with C extensions
64
- **msgpack**: Binary serialization with numpy array support via msgpack-numpy
65
- **cloudpickle**: Enhanced pickle for cloud computing and complex objects
66
- **Unified API**: Consistent interface across all formats with file I/O utilities
67

68
The library handles cross-platform serialization issues (encodings, locales, large files) and provides utilities for standard input/output, gzip compression, and validation.
69

70
## Capabilities
71

72
### JSON Serialization
73

74
High-performance JSON operations with file I/O support, gzip compression, JSONL format handling, and cross-platform compatibility. Includes validation utilities and support for standard input/output streams.
75

76
```python { .api }
77
def json_dumps(data, indent=0, sort_keys=False): ...
78
def json_loads(data): ...
79
def read_json(location): ...
80
def write_json(location, data, indent=2): ...
81
def read_gzip_json(location): ...
82
def write_gzip_json(location, data, indent=2): ...
83
def read_jsonl(location, skip=False): ...
84
def write_jsonl(location, lines, append=False, append_new_line=True): ...
85
def is_json_serializable(obj): ...
86
```
87

88
[JSON Operations](./json.md)
89

90
### MessagePack Serialization
91

92
Binary serialization with numpy array support, optimized for performance and cross-language compatibility. Provides both high-level API functions and access to underlying packer/unpacker classes.
93

94
```python { .api }
95
def msgpack_dumps(data): ...
96
def msgpack_loads(data, use_list=True): ...
97
def read_msgpack(location, use_list=True): ...
98
def write_msgpack(location, data): ...
99
```
100

101
[MessagePack Operations](./msgpack.md)
102

103
### Pickle Serialization
104

105
Enhanced pickle operations using cloudpickle for cloud computing compatibility and complex object serialization including functions, lambdas, and classes.
106

107
```python { .api }
108
def pickle_dumps(data, protocol=None): ...
109
def pickle_loads(data): ...
110
```
111

112
[Pickle Operations](./pickle.md)
113

114
### Ultra-fast JSON (ujson)
115

116
Low-level, high-performance JSON serialization with C extensions, providing the fastest possible JSON encoding and decoding operations. Used internally by the main JSON API functions.
117

118
```python { .api }
119
def dumps(obj, indent=0, ensure_ascii=True, double_precision=9, encode_html_chars=False, escape_forward_slashes=True): ...
120
def loads(data, precise_float=False): ...
121
def dump(obj, fp, indent=0, ensure_ascii=True, double_precision=9, encode_html_chars=False, escape_forward_slashes=True): ...
122
def load(fp, precise_float=False): ...
123
def encode(obj, indent=0, ensure_ascii=True, double_precision=9, encode_html_chars=False, escape_forward_slashes=True): ...
124
def decode(data, precise_float=False): ...
125
```
126

127
[Ultra-fast JSON (ujson)](./ujson.md)
128

129
## Common Types
130

131
```python { .api }
132
# Path-like objects supported throughout the API
133
PathLike = str | pathlib.Path
134

135
# Special location values
136
Location = PathLike | "-"  # "-" represents stdin/stdout
137

138
# JSON-serializable data types
139
JSONSerializable = dict | list | str | int | float | bool | None
140
```