0
# MessagePack Operations
1

2
Binary serialization format with numpy array support, providing compact, fast, and cross-language compatible serialization through an enhanced msgpack implementation.
3

4
## Capabilities
5

6
### MessagePack String Operations
7

8
Core MessagePack serialization functions for converting between Python objects and binary format.
9

10
```python { .api }
11
def msgpack_dumps(data):
12
    """
13
    Serialize an object to msgpack byte string.
14

15
    Parameters:
16
    - data: Python object to serialize (supports numpy arrays)
17

18
    Returns:
19
    bytes: Serialized msgpack data
20
    """
21

22
def msgpack_loads(data, use_list=True):
23
    """
24
    Deserialize msgpack bytes to Python object.
25

26
    Parameters:
27
    - data (bytes): Msgpack data to deserialize
28
    - use_list (bool): Use lists instead of tuples for arrays
29

30
    Returns:
31
    Any: Deserialized Python object
32
    """
33
```
34

35
### MessagePack File Operations
36

37
Read and write MessagePack data to files with automatic binary mode handling.
38

39
```python { .api }
40
def read_msgpack(location, use_list=True):
41
    """
42
    Load msgpack data from file.
43

44
    Parameters:
45
    - location (str | Path): Path to msgpack file
46
    - use_list (bool): Use lists instead of tuples for arrays
47

48
    Returns:
49
    Any: Loaded and deserialized content
50

51
    Raises:
52
    ValueError: If file doesn't exist
53
    """
54

55
def write_msgpack(location, data):
56
    """
57
    Write data to msgpack file.
58

59
    Parameters:
60
    - location (str | Path): Path for msgpack file
61
    - data: Python object to serialize
62

63
    Returns:
64
    None
65
    """
66
```
67

68
### Advanced MessagePack Classes
69

70
Access to underlying packer and unpacker classes for custom serialization with numpy support.
71

72
```python { .api }
73
class Packer:
74
    """
75
    MessagePack packer with numpy array support.
76
    
77
    Automatically encodes numpy arrays using msgpack-numpy extensions.
78
    """
79
    def __init__(self, **kwargs):
80
        """
81
        Initialize packer with options.
82
        
83
        Parameters:
84
        - default (callable): Custom serialization function
85
        - use_bin_type (bool): Use binary type for bytes
86
        - **kwargs: Additional packer options
87
        """
88
    
89
    def pack(self, obj):
90
        """
91
        Pack object to bytes.
92
        
93
        Parameters:
94
        - obj: Object to pack
95
        
96
        Returns:
97
        bytes: Packed data
98
        """
99

100
class Unpacker:
101
    """
102
    MessagePack unpacker with numpy array support.
103
    
104
    Automatically decodes numpy arrays using msgpack-numpy extensions.
105
    """
106
    def __init__(self, **kwargs):
107
        """
108
        Initialize unpacker with options.
109
        
110
        Parameters:
111
        - object_hook (callable): Custom deserialization function
112
        - raw (bool): Keep raw bytes
113
        - use_list (bool): Use lists instead of tuples
114
        - **kwargs: Additional unpacker options
115
        """
116

117
class ExtType:
118
    """
119
    Extended type for custom msgpack serialization.
120
    
121
    Used to handle custom data types in msgpack format.
122
    """
123
    def __init__(self, code, data):
124
        """
125
        Initialize extended type.
126
        
127
        Parameters:
128
        - code (int): Type code (0-127)
129
        - data (bytes): Type data
130
        """
131
```
132

133
### Stream and Compatibility Functions
134

135
Lower-level functions for streaming and compatibility with standard msgpack API.
136

137
```python { .api }
138
def pack(obj, stream, **kwargs):
139
    """
140
    Pack object and write to stream.
141
    
142
    Parameters:
143
    - obj: Object to pack
144
    - stream: File-like object to write to
145
    - **kwargs: Packer options
146
    """
147

148
def packb(obj, **kwargs):
149
    """
150
    Pack object and return bytes (alias for msgpack_dumps).
151
    
152
    Parameters:
153
    - obj: Object to pack
154
    - **kwargs: Packer options
155
    
156
    Returns:
157
    bytes: Packed data
158
    """
159

160
def unpack(stream, **kwargs):
161
    """
162
    Unpack from stream.
163
    
164
    Parameters:
165
    - stream: File-like object to read from
166
    - **kwargs: Unpacker options
167
    
168
    Returns:
169
    Any: Unpacked object
170
    """
171

172
def unpackb(packed, **kwargs):
173
    """
174
    Unpack from bytes (alias for msgpack_loads).
175
    
176
    Parameters:
177
    - packed (bytes): Packed data
178
    - **kwargs: Unpacker options
179
    
180
    Returns:
181
    Any: Unpacked object
182
    """
183

184
# Compatibility aliases
185
load = unpack
186
loads = unpackb
187
dump = pack
188
dumps = packb
189
```
190

191
## Usage Examples
192

193
### Basic MessagePack Operations
194

195
```python
196
import srsly
197
import numpy as np
198

199
# Serialize various data types
200
data = {
201
    "text": "Hello, world!",
202
    "numbers": [1, 2, 3, 4, 5],
203
    "nested": {"key": "value"},
204
    "array": np.array([1.0, 2.0, 3.0])  # Numpy arrays supported
205
}
206

207
# Pack to bytes
208
packed = srsly.msgpack_dumps(data)
209
print(f"Packed size: {len(packed)} bytes")
210

211
# Unpack from bytes
212
unpacked = srsly.msgpack_loads(packed)
213
print(f"Original array: {unpacked['array']}")
214
print(f"Array type: {type(unpacked['array'])}")  # numpy.ndarray
215
```
216

217
### File I/O Operations
218

219
```python
220
import srsly
221
import numpy as np
222

223
# Prepare data with numpy arrays
224
scientific_data = {
225
    "experiment": "test_001",
226
    "measurements": np.random.random((100, 3)),
227
    "parameters": {"temperature": 23.5, "pressure": 1013.25},
228
    "metadata": {
229
        "timestamp": "2023-01-01T12:00:00Z",
230
        "researcher": "Dr. Smith"
231
    }
232
}
233

234
# Save to msgpack file
235
srsly.write_msgpack("experiment.msgpack", scientific_data)
236

237
# Load from msgpack file
238
loaded_data = srsly.read_msgpack("experiment.msgpack")
239
print(f"Experiment: {loaded_data['experiment']}")
240
print(f"Measurements shape: {loaded_data['measurements'].shape}")
241
```
242

243
### Advanced Usage with Custom Classes
244

245
```python
246
import srsly.msgpack as msgpack
247
import numpy as np
248

249
# Direct access to advanced features
250
data = {
251
    "large_array": np.random.random((1000, 1000)),
252
    "metadata": {"version": 1, "created": "2023-01-01"}
253
}
254

255
# Use custom packer for fine control
256
packer = msgpack.Packer(use_bin_type=True)
257
packed_data = packer.pack(data)
258

259
# Use custom unpacker
260
unpacker = msgpack.Unpacker(raw=False, use_list=True)
261
unpacker.feed(packed_data)
262
for unpacked in unpacker:
263
    print(f"Loaded array shape: {unpacked['large_array'].shape}")
264
    break
265
```
266

267
### Stream Processing
268

269
```python
270
import srsly.msgpack as msgpack
271
import io
272

273
# Stream multiple objects
274
buffer = io.BytesIO()
275

276
# Pack multiple objects to stream
277
objects = [{"id": i, "data": f"item_{i}"} for i in range(5)]
278
for obj in objects:
279
    msgpack.pack(obj, buffer)
280

281
# Read back from stream
282
buffer.seek(0)
283
loaded_objects = []
284
try:
285
    while True:
286
        obj = msgpack.unpack(buffer)
287
        loaded_objects.append(obj)
288
except:
289
    pass  # End of stream
290

291
print(f"Loaded {len(loaded_objects)} objects")
292
for obj in loaded_objects:
293
    print(f"ID: {obj['id']}, Data: {obj['data']}")
294
```