0
# ormsgpack
1

2
A fast msgpack serialization library for Python with native support for complex data types including dataclasses, datetime objects, numpy arrays, and pydantic models. Built with Rust for optimal performance, ormsgpack provides a simple API with extensive customization options for serialization behavior.
3

4
## Package Information
5

6
- **Package Name**: ormsgpack
7
- **Language**: Python (with Rust backend)
8
- **Installation**: `pip install ormsgpack`
9

10
## Core Imports
11

12
```python
13
import ormsgpack
14
```
15

16
Common pattern for accessing options:
17

18
```python
19
import ormsgpack
20
from ormsgpack import OPT_NAIVE_UTC, OPT_SERIALIZE_NUMPY
21
```
22

23
## Basic Usage
24

25
```python
26
import ormsgpack
27
import datetime
28
import numpy as np
29

30
# Basic serialization and deserialization
31
data = {"key": "value", "number": 42, "list": [1, 2, 3]}
32
packed = ormsgpack.packb(data)
33
unpacked = ormsgpack.unpackb(packed)
34
print(unpacked)  # {'key': 'value', 'number': 42, 'list': [1, 2, 3]}
35

36
# Serialization with options for complex types
37
complex_data = {
38
    "timestamp": datetime.datetime(2023, 1, 15, 10, 30, 45),
39
    "array": np.array([[1, 2], [3, 4]]),
40
    "status": "active"
41
}
42

43
# Use options to handle datetime and numpy serialization
44
packed = ormsgpack.packb(
45
    complex_data, 
46
    option=ormsgpack.OPT_NAIVE_UTC | ormsgpack.OPT_SERIALIZE_NUMPY
47
)
48
unpacked = ormsgpack.unpackb(packed)
49
print(unpacked)
50
```
51

52
## Capabilities
53

54
### Serialization
55

56
Converts Python objects to msgpack format with extensive customization options for handling various data types.
57

58
```python { .api }
59
def packb(
60
    __obj: Any,
61
    default: Optional[Callable[[Any], Any]] = None,
62
    option: Optional[int] = None,
63
) -> bytes:
64
    """
65
    Serialize Python objects to msgpack format.
66
    
67
    Parameters:
68
    - __obj: Any Python object to serialize (positional-only)
69
    - default: Optional callable for handling non-natively supported types
70
    - option: Optional integer bitmask of serialization options
71
    
72
    Returns:
73
    bytes: The serialized msgpack data
74
    
75
    Raises:
76
    MsgpackEncodeError: If serialization fails due to:
77
                       - Unsupported object type
78
                       - Invalid UTF-8 in str objects
79
                       - Non-str/bytes dict keys (without OPT_NON_STR_KEYS)
80
                       - Circular references
81
                       - Unsupported tzinfo on datetime objects
82
                       - Default callable recursion > 254 levels
83
    """
84
```
85

86
### Deserialization
87

88
Converts msgpack data back to Python objects with optional extension type handling.
89

90
```python { .api }
91
def unpackb(
92
    __obj: Union[bytes, bytearray, memoryview],
93
    /,
94
    ext_hook: Optional[Callable[[int, bytes], Any]] = None,
95
    option: Optional[int] = None,
96
) -> Any:
97
    """
98
    Deserialize msgpack data to Python objects.
99
    
100
    Parameters:
101
    - __obj: bytes, bytearray, or memoryview containing msgpack data (positional-only)
102
    - ext_hook: Optional callable for handling extension types during deserialization
103
    - option: Optional integer bitmask of deserialization options
104
             Supported options: OPT_DATETIME_AS_TIMESTAMP_EXT, OPT_NON_STR_KEYS
105
    
106
    Returns:
107
    Any: The deserialized Python object
108
    
109
    Raises:
110
    MsgpackDecodeError: If deserialization fails due to:
111
                       - Invalid msgpack format
112
                       - Unsupported msgpack type
113
    """
114
```
115

116
### Extension Types
117

118
Handle custom data types through msgpack extension mechanism.
119

120
```python { .api }
121
class Ext:
122
    """
123
    Represents a msgpack extension type with a tag and data.
124
    """
125
    def __init__(self, tag: int, data: bytes) -> None:
126
        """
127
        Create an extension type.
128
        
129
        Parameters:
130
        - tag: Integer tag identifying the extension type (0-127)
131
        - data: bytes containing the extension data
132
        """
133
    
134
    tag: int  # The extension type tag (0-127)
135
    data: bytes  # The extension data as bytes
136
```
137

138
## Serialization Options
139

140
Options can be combined using bitwise OR (`|`) operator to customize serialization behavior:
141

142
```python
143
option = ormsgpack.OPT_NAIVE_UTC | ormsgpack.OPT_SERIALIZE_NUMPY | ormsgpack.OPT_SORT_KEYS
144
```
145

146
### DateTime Options
147

148
```python { .api }
149
OPT_NAIVE_UTC: int  # Treat naive datetime objects as UTC (packb only)
150
OPT_OMIT_MICROSECONDS: int  # Omit microseconds from datetime serialization (packb only)
151
OPT_DATETIME_AS_TIMESTAMP_EXT: int  # Serialize/deserialize datetime as msgpack timestamp extension (packb/unpackb)
152
OPT_UTC_Z: int  # Use 'Z' suffix for UTC timezone in datetime strings (packb only)
153
```
154

155
### Collection Options
156

157
```python { .api }
158
OPT_NON_STR_KEYS: int  # Allow non-string keys in dictionaries (packb/unpackb)
159
OPT_SORT_KEYS: int  # Sort dictionary keys in serialized output (packb only)
160
```
161

162
### Type-Specific Serialization
163

164
```python { .api }
165
OPT_SERIALIZE_NUMPY: int  # Enable native serialization of numpy arrays (packb only)
166
OPT_SERIALIZE_PYDANTIC: int  # Enable native serialization of pydantic models (packb only)
167
```
168

169
### Passthrough Options
170

171
These options disable custom serialization for specific types, passing them through as-is (packb only):
172

173
```python { .api }
174
OPT_PASSTHROUGH_BIG_INT: int  # Pass through large integers without custom serialization
175
OPT_PASSTHROUGH_DATACLASS: int  # Pass through dataclass objects without custom serialization
176
OPT_PASSTHROUGH_DATETIME: int  # Pass through datetime objects without custom serialization
177
OPT_PASSTHROUGH_ENUM: int  # Pass through enum objects without custom serialization
178
OPT_PASSTHROUGH_SUBCLASS: int  # Pass through subclass instances without custom serialization
179
OPT_PASSTHROUGH_TUPLE: int  # Pass through tuple objects without custom serialization
180
OPT_PASSTHROUGH_UUID: int  # Pass through UUID objects without custom serialization
181
```
182

183
## Exception Types
184

185
```python { .api }
186
class MsgpackDecodeError(ValueError):
187
    """
188
    Raised when msgpack deserialization fails.
189
    
190
    Inherits from ValueError. Occurs when the input data is not valid msgpack
191
    format or contains unsupported msgpack types.
192
    """
193

194
class MsgpackEncodeError(TypeError):
195
    """
196
    Raised when msgpack serialization fails.
197
    
198
    Inherits from TypeError. Provides detailed error messages describing
199
    the object type that caused the serialization failure, with format:
200
    'Type is not msgpack serializable: <type_name>'
201
    """
202
```
203

204
## Supported Data Types
205

206
ormsgpack natively supports serialization of:
207

208
- **Basic types**: None, bool, int, float, str, bytes
209
- **Collections**: list, tuple, dict
210
- **Advanced types**: dataclass, datetime, date, time, enum, UUID
211
- **Third-party types**: numpy arrays (with OPT_SERIALIZE_NUMPY), pydantic models (with OPT_SERIALIZE_PYDANTIC)
212
- **Extension types**: Custom types via Ext class and ext_hook
213

214
## Advanced Usage Examples
215

216
### Custom Type Handling
217

218
```python
219
import ormsgpack
220
from decimal import Decimal
221

222
def decimal_handler(obj):
223
    if isinstance(obj, Decimal):
224
        return str(obj)
225
    raise TypeError
226

227
# Serialize with custom handler
228
data = {"price": Decimal("19.99")}
229
packed = ormsgpack.packb(data, default=decimal_handler)
230
unpacked = ormsgpack.unpackb(packed)
231
```
232

233
### Extension Types
234

235
```python
236
import ormsgpack
237

238
# Create extension type
239
ext_data = ormsgpack.Ext(42, b"custom_data")
240
packed = ormsgpack.packb(ext_data)
241

242
# Handle extension during unpacking
243
def ext_handler(tag, data):
244
    if tag == 42:
245
        return f"Custom: {data.decode()}"
246
    return ormsgpack.Ext(tag, data)
247

248
unpacked = ormsgpack.unpackb(packed, ext_hook=ext_handler)
249
```
250

251
### Dataclass Serialization
252

253
```python
254
import ormsgpack
255
from dataclasses import dataclass
256

257
@dataclass
258
class Person:
259
    name: str
260
    age: int
261

262
person = Person("Alice", 30)
263
packed = ormsgpack.packb(person)  # Default behavior serializes as dict
264
unpacked = ormsgpack.unpackb(packed)  # Returns {'name': 'Alice', 'age': 30}
265
```
266

267
## Version Information
268

269
```python { .api }
270
__version__: str  # Version string of the ormsgpack library
271
```