0
# MessagePack
1

2
MessagePack is an efficient binary serialization format that enables data exchange among multiple languages like JSON but is faster and smaller. This Python implementation provides CPython bindings for high performance and a pure Python fallback for PyPy compatibility.
3

4
## Package Information
5

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

10
## Core Imports
11

12
```python
13
import msgpack
14
```
15

16
Common usage pattern:
17

18
```python
19
from msgpack import packb, unpackb
20
```
21

22
For streaming applications:
23

24
```python
25
from msgpack import Packer, Unpacker
26
```
27

28
## Basic Usage
29

30
```python
31
import msgpack
32

33
# Pack Python objects to binary data
34
data = {'name': 'Alice', 'age': 30, 'scores': [95, 87, 92]}
35
packed = msgpack.packb(data)
36

37
# Unpack binary data back to Python objects
38
unpacked = msgpack.unpackb(packed)
39
print(unpacked)  # {'name': 'Alice', 'age': 30, 'scores': [95, 87, 92]}
40

41
# File operations
42
with open('data.msgpack', 'wb') as f:
43
    msgpack.pack(data, f)
44

45
with open('data.msgpack', 'rb') as f:
46
    loaded_data = msgpack.unpack(f)
47
```
48

49
## Architecture
50

51
MessagePack Python provides two implementation paths:
52

53
- **C Extension**: High-performance implementation using Cython (`msgpack._cmsgpack`)
54
- **Pure Python**: Fallback implementation for PyPy compatibility (`msgpack.fallback`)
55

56
The library automatically selects the best available implementation unless overridden via the `MSGPACK_PUREPYTHON` environment variable.
57

58
## Capabilities
59

60
### High-Level Functions
61

62
Core convenience functions for one-shot packing and unpacking operations, providing simple interfaces for the most common serialization tasks.
63

64
```python { .api }
65
def packb(o, **kwargs): ...
66
def unpackb(packed, **kwargs): ...
67
def pack(o, stream, **kwargs): ...  
68
def unpack(stream, **kwargs): ...
69
```
70

71
[Core Functions](./core-functions.md)
72

73
### Streaming Classes
74

75
Advanced classes for efficient streaming serialization and deserialization, enabling processing of large datasets and continuous data streams.
76

77
```python { .api }
78
class Packer:
79
    def __init__(self, **kwargs): ...
80
    def pack(self, obj): ...
81

82
class Unpacker:
83
    def __init__(self, file_like=None, **kwargs): ...
84
    def feed(self, data): ...
85
    def unpack(self): ...
86
```
87

88
[Streaming](./streaming.md)
89

90
### Custom Types
91

92
Specialized types for handling extension data and timestamps, enabling custom serialization of complex data structures.
93

94
```python { .api }
95
class ExtType:
96
    def __init__(self, code: int, data: bytes): ...
97

98
class Timestamp:
99
    def __init__(self, seconds: int, nanoseconds: int = 0): ...
100
```
101

102
[Types](./types.md)
103

104
### Exception Handling
105

106
Comprehensive exception hierarchy for robust error handling during serialization and deserialization operations.
107

108
```python { .api }
109
class UnpackException(Exception): ...
110
class FormatError(ValueError, UnpackException): ...
111
class ExtraData(UnpackValueError): ...
112
```
113

114
[Exceptions](./exceptions.md)