0
# Core Functions
1

2
High-level convenience functions that provide simple interfaces for the most common MessagePack serialization tasks. These functions handle one-shot packing and unpacking operations with automatic resource management.
3

4
## Capabilities
5

6
### Binary Packing
7

8
Converts Python objects to MessagePack binary format with automatic type detection and encoding.
9

10
```python { .api }
11
def packb(o, **kwargs):
12
    """
13
    Pack object `o` and return packed bytes.
14

15
    Parameters:
16
    - o: Python object to pack
17
    - default: callable to handle unsupported types  
18
    - use_single_float: bool, use 32-bit floats (default: False)
19
    - use_bin_type: bool, use bin type for bytes (default: True)
20
    - strict_types: bool, check exact types (default: False)
21
    - datetime: bool, pack datetime as Timestamp (default: False)
22
    - unicode_errors: str, Unicode error handling (default: 'strict')
23

24
    Returns:
25
    bytes: Packed binary data
26

27
    Raises:
28
    TypeError: When object cannot be serialized
29
    OverflowError: When numbers are too large
30
    """
31
```
32

33
### Binary Unpacking
34

35
Converts MessagePack binary data back to Python objects with configurable options for type handling and security.
36

37
```python { .api }
38
def unpackb(packed, **kwargs):
39
    """
40
    Unpack an object from `packed` bytes.
41

42
    Parameters:
43
    - packed: bytes, MessagePack binary data
44
    - raw: bool, return bytes instead of str (default: False)
45
    - use_list: bool, use list instead of tuple (default: True)
46
    - timestamp: int, timestamp unpacking mode (0-3, default: 0)
47
    - strict_map_key: bool, restrict map key types (default: True)
48
    - object_hook: callable, hook for dict objects
49
    - object_pairs_hook: callable, hook for key-value pairs
50
    - unicode_errors: str, Unicode error handling (default: 'strict')
51
    - max_buffer_size: int, buffer size limit (default: 100MB)
52
    - ext_hook: callable, extension type handler
53

54
    Returns:
55
    object: Unpacked Python object
56

57
    Raises:
58
    ExtraData: When packed contains extra bytes
59
    ValueError: When packed is incomplete
60
    FormatError: When packed is not valid msgpack
61
    StackError: When packed contains too nested data
62
    """
63
```
64

65
### Stream Packing
66

67
Packs Python objects and writes directly to a file-like object, useful for efficient file operations.
68

69
```python { .api }
70
def pack(o, stream, **kwargs):
71
    """
72
    Pack object `o` and write it to `stream`.
73

74
    Parameters:
75
    - o: Python object to pack
76
    - stream: file-like object with write() method
77
    - **kwargs: All Packer options (see packb)
78

79
    Returns:
80
    None
81

82
    Raises:
83
    TypeError: When object cannot be serialized
84
    OverflowError: When numbers are too large
85
    """
86
```
87

88
### Stream Unpacking
89

90
Unpacks MessagePack data from a file-like object, automatically reading all available data.
91

92
```python { .api }
93
def unpack(stream, **kwargs):
94
    """
95
    Unpack an object from `stream`.
96

97
    Parameters:
98
    - stream: file-like object with read() method
99
    - **kwargs: All Unpacker options (see unpackb)
100

101
    Returns:
102
    object: Unpacked Python object
103

104
    Raises:
105
    ExtraData: When stream contains extra bytes
106
    ValueError: When stream data is incomplete
107
    FormatError: When stream data is not valid msgpack
108
    StackError: When stream data contains too nested data
109
    """
110
```
111

112
### Compatibility Aliases
113

114
JSON and pickle compatibility functions that provide familiar interfaces for users migrating from other serialization libraries.
115

116
```python { .api }
117
def loads(packed, **kwargs):
118
    """Alias for unpackb (compatibility with json and pickle)."""
119

120
def dumps(o, **kwargs):
121
    """Alias for packb (compatibility with json and pickle)."""
122

123
def load(stream, **kwargs):
124
    """Alias for unpack (compatibility with json and pickle)."""
125

126
def dump(o, stream, **kwargs):
127
    """Alias for pack (compatibility with json and pickle)."""
128
```
129

130
## Usage Examples
131

132
### Custom Type Handling
133

134
```python
135
import datetime
136
import msgpack
137

138
def default_handler(obj):
139
    if isinstance(obj, datetime.datetime):
140
        return {'__datetime__': True, 'iso': obj.isoformat()}
141
    raise TypeError(f'Object of type {type(obj)} is not JSON serializable')
142

143
def object_hook(obj):
144
    if '__datetime__' in obj:
145
        return datetime.datetime.fromisoformat(obj['iso'])
146
    return obj
147

148
# Pack with custom type
149
data = {'timestamp': datetime.datetime.now()}
150
packed = msgpack.packb(data, default=default_handler)
151

152
# Unpack with custom type
153
unpacked = msgpack.unpackb(packed, object_hook=object_hook)
154
```
155

156
### Security Options
157

158
```python
159
import msgpack
160

161
# Safe unpacking with limits
162
try:
163
    data = msgpack.unpackb(
164
        untrusted_data,
165
        max_buffer_size=1024*1024,  # 1MB limit
166
        strict_map_key=True,        # Only str/bytes keys
167
        raw=False                   # Decode strings
168
    )
169
except msgpack.ExtraData as e:
170
    print(f"Extra data found: {len(e.extra)} bytes")
171
    data = e.unpacked
172
```