0
# PyMongo
1

2
The official Python driver for MongoDB, providing comprehensive tools for interacting with MongoDB databases from Python applications. PyMongo includes three main components: the `bson` package for BSON format handling, the `pymongo` package as the core driver, and the `gridfs` package for GridFS file storage.
3

4
## Package Information
5

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

10
## Core Imports
11

12
```python
13
import pymongo
14
from pymongo import MongoClient, ASCENDING, DESCENDING
15
```
16

17
For BSON handling:
18

19
```python
20
import bson
21
from bson import ObjectId, encode, decode, Binary, Decimal128
22
```
23

24
For GridFS file storage:
25

26
```python
27
import gridfs
28
from gridfs import GridFS, GridFSBucket
29
```
30

31
Common bulk operations:
32

33
```python
34
from pymongo.operations import InsertOne, UpdateOne, DeleteOne, ReplaceOne
35
```
36

37
## Basic Usage
38

39
```python
40
from pymongo import MongoClient
41
from bson import ObjectId
42

43
# Connect to MongoDB
44
client = MongoClient('mongodb://localhost:27017/')
45
db = client.mydatabase
46
collection = db.mycollection
47

48
# Insert a document
49
doc = {"name": "Alice", "age": 30, "city": "New York"}
50
result = collection.insert_one(doc)
51
print(f"Inserted document with id: {result.inserted_id}")
52

53
# Find documents
54
for doc in collection.find({"age": {"$gte": 25}}):
55
    print(doc)
56

57
# Update a document
58
collection.update_one(
59
    {"name": "Alice"},
60
    {"$set": {"age": 31}}
61
)
62

63
# Delete a document
64
collection.delete_one({"name": "Alice"})
65
```
66

67
## Architecture
68

69
PyMongo follows MongoDB's hierarchical structure:
70

71
- **MongoClient**: Connection management and client configuration
72
- **Database**: Database-level operations and collection access
73
- **Collection**: Document CRUD operations, indexing, and aggregation
74
- **Cursor**: Result iteration with filtering and sorting capabilities
75

76
The driver provides comprehensive support for MongoDB features including transactions, change streams, aggregation pipelines, GridFS, and advanced authentication mechanisms.
77

78
## Capabilities
79

80
### Client Connection and Configuration
81

82
MongoDB client creation, connection management, authentication, and configuration options including connection pooling, timeouts, and replica set support.
83

84
```python { .api }
85
class MongoClient:
86
    def __init__(self, host='localhost', port=27017, **kwargs): ...
87
    def get_database(self, name, **kwargs): ...
88
    def list_database_names(self, session=None, **kwargs): ...
89
    def close(self): ...
90

91
class MongoReplicaSetClient:
92
    """DEPRECATED - Legacy replica set client interface."""
93
```
94

95
[Client and Connection Management](./client-connection.md)
96

97
### Database and Collection Operations
98

99
Database management, collection operations, document CRUD operations, indexing, and basic query functionality.
100

101
```python { .api }
102
class Database:
103
    def get_collection(self, name, **kwargs): ...
104
    def list_collection_names(self, session=None, **kwargs): ...
105
    def create_collection(self, name, **kwargs): ...
106

107
class Collection:
108
    def insert_one(self, document, **kwargs): ...
109
    def find(self, filter=None, **kwargs): ...
110
    def update_one(self, filter, update, **kwargs): ...
111
    def delete_one(self, filter, **kwargs): ...
112
```
113

114
[Database and Collection Operations](./database-collection.md)
115

116
### BSON Data Types and Encoding
117

118
BSON encoding/decoding functions and MongoDB-specific data types including ObjectId, Decimal128, Binary data, and timestamp handling.
119

120
```python { .api }
121
def encode(document, **kwargs): ...
122
def decode(data, **kwargs): ...
123

124
class ObjectId:
125
    def __init__(self, oid=None): ...
126
    @classmethod
127
    def from_datetime(cls, generation_time): ...
128

129
class Decimal128:
130
    def __init__(self, value): ...
131
```
132

133
[BSON Handling](./bson-handling.md)
134

135
### Advanced Query Operations
136

137
Aggregation pipelines, advanced querying, sorting, pagination, and cursor operations for complex data retrieval patterns.
138

139
```python { .api }
140
class Collection:
141
    def aggregate(self, pipeline, **kwargs): ...
142
    def find_one_and_update(self, filter, update, **kwargs): ...
143
    def create_index(self, keys, **kwargs): ...
144
    def distinct(self, key, filter=None, **kwargs): ...
145

146
class Cursor:
147
    def sort(self, key_or_list, direction=1): ...
148
    def limit(self, limit): ...
149
    def skip(self, skip): ...
150
```
151

152
[Advanced Queries and Aggregation](./advanced-queries.md)
153

154
### Bulk Operations and Transactions
155

156
Bulk write operations, transaction support, and session management for high-performance and ACID-compliant operations.
157

158
```python { .api }
159
class Collection:
160
    def bulk_write(self, requests, **kwargs): ...
161

162
class MongoClient:
163
    def start_session(self, **kwargs): ...
164

165
class ClientSession:
166
    def start_transaction(self, **kwargs): ...
167
    def commit_transaction(self): ...
168
    def abort_transaction(self): ...
169

170
# Bulk Operation Classes
171
class InsertOne:
172
    def __init__(self, document): ...
173

174
class UpdateOne:
175
    def __init__(self, filter, update, upsert=False): ...
176

177
class UpdateMany:
178
    def __init__(self, filter, update, upsert=False): ...
179

180
class ReplaceOne:
181
    def __init__(self, filter, replacement, upsert=False): ...
182

183
class DeleteOne:
184
    def __init__(self, filter): ...
185

186
class DeleteMany:
187
    def __init__(self, filter): ...
188

189
class IndexModel:
190
    def __init__(self, keys, **kwargs): ...
191
```
192

193
[Bulk Operations and Transactions](./bulk-transactions.md)
194

195
### GridFS File Storage
196

197
GridFS support for storing and retrieving large files, including streaming operations and metadata management.
198

199
```python { .api }
200
class GridFS:
201
    def __init__(self, database, collection='fs', **kwargs): ...
202
    def put(self, data, **kwargs): ...
203
    def get(self, file_id, **kwargs): ...
204

205
class GridFSBucket:
206
    def __init__(self, db, bucket_name='fs', **kwargs): ...
207
    def upload_from_stream(self, filename, source, **kwargs): ...
208
    def download_to_stream(self, file_id, destination, **kwargs): ...
209
```
210

211
[GridFS File Storage](./gridfs-storage.md)
212

213
### Monitoring and Events
214

215
Change streams, monitoring capabilities, and event handling for real-time data updates and application performance monitoring.
216

217
```python { .api }
218
class Collection:
219
    def watch(self, pipeline=None, **kwargs): ...
220

221
class ChangeStream:
222
    def __iter__(self): ...
223
    def next(self): ...
224
    def close(self): ...
225
```
226

227
[Monitoring and Change Streams](./monitoring-events.md)
228

229
## Utility Functions
230

231
Core utility functions for version checking and C extension detection:
232

233
```python { .api }
234
def get_version_string():
235
    """
236
    Get PyMongo version string.
237

238
    Returns:
239
    str: Version string (e.g., "3.13.0")
240
    """
241

242
def has_c():
243
    """
244
    Check if C extensions are available.
245

246
    Returns:
247
    bool: True if C extensions are loaded
248
    """
249

250
version: str  # Current PyMongo version
251
version_tuple: tuple  # Version as tuple (3, 13, 0)
252
```
253

254
## Types
255

256
Core types used throughout the PyMongo API:
257

258
```python { .api }
259
# Read/Write Preferences
260
class ReadPreference:
261
    PRIMARY: int
262
    SECONDARY: int
263
    PRIMARY_PREFERRED: int
264
    SECONDARY_PREFERRED: int
265

266
class WriteConcern:
267
    def __init__(self, w=None, wtimeout=None, j=None, fsync=None): ...
268

269
# Common Result Types
270
class InsertOneResult:
271
    inserted_id: ObjectId
272

273
class UpdateResult:
274
    matched_count: int
275
    modified_count: int
276
    upserted_id: ObjectId
277

278
class DeleteResult:
279
    deleted_count: int
280

281
# Sort Constants
282
ASCENDING: int  # 1
283
DESCENDING: int  # -1
284

285
# Index Types
286
GEO2D: str  # "2d"
287
GEOSPHERE: str  # "2dsphere"
288
GEOHAYSTACK: str  # "geoHaystack" (DEPRECATED)
289
HASHED: str  # "hashed"
290
TEXT: str  # "text"
291

292
# Database Profiling Levels (DEPRECATED)
293
OFF: int  # 0 (DEPRECATED)
294
SLOW_ONLY: int  # 1 (DEPRECATED)
295
ALL: int  # 2 (DEPRECATED)
296

297
# Wire Protocol Constants
298
MAX_SUPPORTED_WIRE_VERSION: int
299
MIN_SUPPORTED_WIRE_VERSION: int
300

301
# Bulk Operation Result Types
302
class BulkWriteResult:
303
    acknowledged: bool
304
    deleted_count: int
305
    inserted_count: int
306
    matched_count: int
307
    modified_count: int
308
    upserted_count: int
309
    upserted_ids: dict
310

311
class InsertManyResult:
312
    acknowledged: bool
313
    inserted_ids: list
314

315
# Exception Classes
316
class PyMongoError(Exception):
317
    """Base exception for PyMongo errors."""
318

319
class ConfigurationError(PyMongoError):
320
    """Configuration related errors."""
321

322
class OperationFailure(PyMongoError):
323
    """Database operation failures."""
324

325
class DuplicateKeyError(OperationFailure):
326
    """Duplicate key violations."""
327

328
class BulkWriteError(OperationFailure):
329
    """Bulk write operation errors."""
330

331
class NetworkTimeout(PyMongoError):
332
    """Network timeout errors."""
333

334
class ServerSelectionTimeoutError(PyMongoError):
335
    """Server selection timeout errors."""
336
```