0
# Core Serialization
1

2
Primary BSON encoding and decoding functionality that forms the foundation of the bson package. These functions provide complete serialization capabilities for converting between Python objects and BSON binary format.
3

4
## Capabilities
5

6
### BSON Serialization
7

8
Converts Python dictionaries and BSONCoding objects to BSON binary format with optional custom encoding order generation and unknown type handling.
9

10
```python { .api }
11
def dumps(obj, generator=None, on_unknown=None):
12
    """
13
    Convert a Python object to BSON bytes.
14

15
    Parameters:
16
    - obj: dict or BSONCoding object to serialize
17
    - generator: Optional function that accepts (dict/array, traversal_stack) 
18
                and returns iterator for encoding order of keys
19
    - on_unknown: Optional function to handle unknown types during encoding
20

21
    Returns:
22
    bytes: BSON-encoded data
23

24
    Raises:
25
    UnknownSerializerError: If unknown type encountered and no on_unknown handler
26
    """
27
```
28

29
Usage example:
30

31
```python
32
import bson
33

34
# Basic serialization
35
data = {"name": "Alice", "age": 30, "items": ["book", "pen"]}
36
bson_data = bson.dumps(data)
37

38
# With custom key ordering
39
def custom_order(obj, stack):
40
    if isinstance(obj, dict):
41
        # Sort keys alphabetically
42
        return sorted(obj.keys())
43
    return obj.keys()
44

45
ordered_bson = bson.dumps(data, generator=custom_order)
46

47
# With unknown type handler
48
def handle_unknown(value):
49
    if hasattr(value, '__dict__'):
50
        return value.__dict__
51
    return str(value)
52

53
complex_data = {"obj": SomeCustomObject(), "value": 42}
54
bson_data = bson.dumps(complex_data, on_unknown=handle_unknown)
55
```
56

57
### BSON Deserialization
58

59
Converts BSON binary data back to Python dictionaries, automatically handling all supported BSON types and custom BSONCoding objects.
60

61
```python { .api }
62
def loads(data):
63
    """
64
    Convert BSON bytes to a Python object.
65

66
    Parameters:
67
    - data: bytes, BSON-encoded data to deserialize
68

69
    Returns:
70
    dict: Deserialized Python object (usually dict)
71

72
    Raises:
73
    ValueError: If BSON data is malformed or invalid
74
    MissingClassDefinition: If custom object class not registered
75
    """
76
```
77

78
Usage example:
79

80
```python
81
import bson
82

83
# Basic deserialization
84
bson_data = b'\x1a\x00\x00\x00\x02name\x00\x06\x00\x00\x00Alice\x00\x10age\x00\x1e\x00\x00\x00\x00'
85
obj = bson.loads(bson_data)
86
print(obj)  # {'name': 'Alice', 'age': 30}
87

88
# Handles all BSON types automatically
89
complex_bson = bson.dumps({
90
    "string": "hello",
91
    "number": 42,
92
    "float": 3.14,
93
    "bool": True,
94
    "null": None,
95
    "array": [1, 2, 3],
96
    "nested": {"key": "value"}
97
})
98
restored = bson.loads(complex_bson)
99
```
100

101
## Error Handling
102

103
### Serialization Errors
104

105
```python { .api }
106
class UnknownSerializerError(ValueError):
107
    """Raised when unable to serialize unknown type"""
108
    def __init__(self, key, value): ...
109
```
110

111
Occurs when `dumps()` encounters a type it cannot serialize and no `on_unknown` handler is provided.
112

113
### Deserialization Errors
114

115
Common errors during deserialization:
116

117
- **ValueError**: Malformed BSON data, missing null terminators, invalid structure
118
- **MissingClassDefinition**: Custom BSONCoding class not registered with `import_class()`
119
- **UnicodeDecodeError**: Invalid UTF-8 strings in BSON data
120

121
## Type Conversion Details
122

123
### Automatic Type Handling
124

125
The serialization functions automatically handle type conversion between Python and BSON:
126

127
| Python Type | BSON Type | Notes |
128
|-------------|-----------|-------|
129
| `bool` | Boolean | Must be checked before `int` |
130
| `int` | Int32/Int64/UInt64 | Based on value range |
131
| `float` | Double | IEEE 754 double precision |
132
| `str`/`unicode` | String | UTF-8 encoded |
133
| `bytes` | Binary | Binary subtype 0 |
134
| `dict` | Document | Recursive encoding |
135
| `list`/`tuple` | Array | Indexed as string keys |
136
| `datetime` | UTCDateTime | Milliseconds since epoch |
137
| `None` | Null | BSON null type |
138
| `UUID` | Binary | Binary subtype 4 |
139
| `Decimal` | Double | Converted to float |
140
141
### Custom Type Integration
142

143
For explicit type control, use the type wrapper classes:
144

145
```python
146
from bson.types import Int32, Int64, UInt64
147

148
data = {
149
    "small_int": Int32(100),
150
    "big_int": Int64(9223372036854775807),
151
    "unsigned": UInt64(18446744073709551615)
152
}
153
bson_data = bson.dumps(data)
154
```