0
# BSON
1

2
An independent BSON (Binary JSON) codec for Python that operates without dependency on MongoDB. It provides comprehensive serialization and deserialization capabilities for BSON format data, supporting standard Python data types and offering network socket extensions for atomic BSON object transmission.
3

4
## Package Information
5

6
- **Package Name**: bson
7
- **Language**: Python
8
- **Installation**: `pip install bson`
9
- **Dependencies**: `python-dateutil>=2.4.0`, `six>=1.9.0`
10

11
## Core Imports
12

13
```python
14
import bson
15
```
16

17
For serialization and deserialization:
18

19
```python
20
from bson import dumps, loads
21
```
22

23
For ObjectId support:
24

25
```python
26
from bson import ObjectId
27
```
28

29
For network socket extensions:
30

31
```python
32
from bson import patch_socket
33
```
34

35
## Basic Usage
36

37
```python
38
import bson
39

40
# Serialize Python dict to BSON
41
data = {"name": "Alice", "age": 30, "scores": [85, 92, 78]}
42
bson_bytes = bson.dumps(data)
43

44
# Deserialize BSON to Python dict
45
restored_data = bson.loads(bson_bytes)
46
print(restored_data)  # {'name': 'Alice', 'age': 30, 'scores': [85, 92, 78]}
47

48
# Working with ObjectIds
49
from bson import ObjectId
50
oid = ObjectId()
51
print(str(oid))  # e.g., '507f1f77bcf86cd799439011'
52

53
# Network socket usage
54
import socket
55
from bson import patch_socket
56

57
# Patch socket class to add BSON methods
58
bson.patch_socket()
59

60
# Now sockets can send/receive BSON objects
61
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
62
# sock.sendobj({"message": "hello"})
63
# obj = sock.recvobj()
64
```
65

66
## Architecture
67

68
The BSON package is structured around several key components:
69

70
- **Core Codec**: Low-level BSON encoding/decoding functions with support for all BSON types
71
- **High-level API**: Simple `dumps()` and `loads()` functions for easy serialization
72
- **ObjectId Implementation**: MongoDB-compatible ObjectId class forked from PyMongo
73
- **Type System**: Explicit integer type classes (Int32, Int64, UInt64) for precise control
74
- **Network Extensions**: Socket patching for atomic BSON transmission over networks
75
- **Custom Object Support**: BSONCoding abstract base class for custom serializable objects
76

77
## Capabilities
78

79
### Core Serialization
80

81
Primary BSON encoding and decoding functionality with support for all standard Python data types including dictionaries, lists, strings, numbers, dates, and binary data.
82

83
```python { .api }
84
def dumps(obj, generator=None, on_unknown=None):
85
    """Convert Python object to BSON bytes"""
86

87
def loads(data):
88
    """Convert BSON bytes to Python object"""
89
```
90

91
[Core Serialization](./serialization.md)
92

93
### ObjectId Operations
94

95
MongoDB-compatible ObjectId implementation providing unique identifier generation, parsing, validation, and datetime-based creation for range queries.
96

97
```python { .api }
98
class ObjectId:
99
    def __init__(self, oid=None): ...
100
    
101
    @classmethod
102
    def from_datetime(cls, generation_time): ...
103
    
104
    @classmethod
105
    def is_valid(cls, oid): ...
106
    
107
    @property
108
    def binary(self): ...
109
    
110
    @property
111
    def generation_time(self): ...
112
```
113

114
[ObjectId Operations](./objectid.md)
115

116
### Network Socket Extensions
117

118
Socket patching capabilities that add atomic BSON object transmission methods to Python socket objects, enabling seamless BSON communication over network connections.
119

120
```python { .api }
121
def patch_socket():
122
    """Patch socket class with BSON methods"""
123

124
# Methods added to socket objects:
125
def recvbytes(self, bytes_needed, sock_buf=None): ...
126
def recvobj(self): ...  
127
def sendobj(self, obj): ...
128
```
129

130
[Network Socket Extensions](./network.md)
131

132
### Type System
133

134
Explicit integer type wrappers for precise control over BSON integer encoding, supporting 32-bit signed, 64-bit signed, and 64-bit unsigned integers.
135

136
```python { .api }
137
class Int32:
138
    def __init__(self, value): ...
139
    def get_value(self): ...
140

141
class Int64:
142
    def __init__(self, value): ...
143
    def get_value(self): ...
144

145
class UInt64:
146
    def __init__(self, value): ...
147
    def get_value(self): ...
148
```
149

150
[Type System](./types.md)
151

152
### Custom Object Serialization
153

154
Framework for creating custom BSON-serializable objects through the BSONCoding abstract base class, with class registration and automatic serialization/deserialization.
155

156
```python { .api }
157
class BSONCoding:
158
    def bson_encode(self): ...
159
    def bson_init(self, raw_values): ...
160

161
def import_class(cls): ...
162
def import_classes(*args): ...
163
```
164

165
[Custom Object Serialization](./custom-objects.md)
166

167
## Supported BSON Types
168

169
The package supports encoding and decoding of the following BSON types:
170

171
- **Doubles** (float)
172
- **Strings** (str/unicode)  
173
- **Documents** (dict)
174
- **Arrays** (list/tuple)
175
- **Binary data** (bytes)
176
- **ObjectIds**
177
- **Booleans**
178
- **UTC datetime**
179
- **None/null** values
180
- **32-bit integers**
181
- **64-bit signed integers**
182
- **64-bit unsigned integers**
183
- **Decimal** (converted to double)
184
- **UUID** (as binary subtype 4)
185
- **Custom BSONCoding objects**
186

187
## Unsupported BSON Types
188

189
The following BSON types are intentionally not supported for data exchange simplicity:
190

191
- Undefined (0x06)
192
- Regex (0x0b)
193
- DBPointer (0x0c)
194
- JavaScript code (0x0d)
195
- Symbol (0x0e)
196
- JavaScript with scope (0x0f)
197
- MongoDB timestamp (0x11)