0
# ODMantic
1

2
ODMantic is a modern async Object Document Mapper (ODM) for MongoDB in Python that leverages type hints and is built on top of Pydantic for model definition and validation. It provides a developer-friendly API for defining MongoDB document models using standard Python types, supports both synchronous and asynchronous operations with AsyncIO frameworks like FastAPI, and offers features including automatic data validation, JSON serialization and schema generation, functional query building using Python operators, and comprehensive type safety.
3

4
## Package Information
5

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

10
## Core Imports
11

12
```python
13
import odmantic
14
```
15

16
Common imports for database operations:
17

18
```python
19
from odmantic import AIOEngine, SyncEngine, Model, Field, ObjectId
20
from odmantic.config import ODMConfigDict
21
```
22

23
## Basic Usage
24

25
```python
26
from odmantic import AIOEngine, Model, Field
27
from motor.motor_asyncio import AsyncIOMotorClient
28
import asyncio
29

30
# Define a model
31
class User(Model):
32
    name: str
33
    email: str = Field(unique=True)
34
    age: int = Field(ge=0)
35

36
# Setup async engine
37
client = AsyncIOMotorClient("mongodb://localhost:27017")
38
engine = AIOEngine(client, database="my_db")
39

40
async def main():
41
    # Create and save a user
42
    user = User(name="John Doe", email="john@example.com", age=30)
43
    await engine.save(user)
44
    
45
    # Find users
46
    users = await engine.find(User, User.age >= 18)
47
    async for user in users:
48
        print(f"{user.name}: {user.email}")
49
    
50
    # Find one user
51
    user = await engine.find_one(User, User.email == "john@example.com")
52
    if user:
53
        print(f"Found: {user.name}")
54

55
asyncio.run(main())
56
```
57

58
## Architecture
59

60
ODMantic's architecture provides both async and sync database operations:
61

62
- **Engines**: Database operation handlers (AIOEngine for async, SyncEngine for sync)
63
- **Models**: Document schemas with type validation using Pydantic
64
- **Fields**: MongoDB-specific field definitions with indexing and constraints
65
- **Sessions**: Transaction and session management for atomic operations
66
- **Query Builder**: Functional query construction using Python operators
67
- **BSON Types**: Native MongoDB types like ObjectId, Int64, Decimal128
68

69
This design allows for type-safe MongoDB operations while maintaining high performance through motor (async) and pymongo (sync) drivers.
70

71
## Capabilities
72

73
### Database Engines
74

75
Async and sync MongoDB operation engines providing complete CRUD functionality, query building, session management, and database configuration.
76

77
```python { .api }
78
class AIOEngine:
79
    def __init__(self, client=None, database="test"): ...
80
    async def save(self, instance, session=None): ...
81
    async def find(self, model, *queries, sort=None, skip=0, limit=None, session=None): ...
82
    async def find_one(self, model, *queries, sort=None, session=None): ...
83
    async def delete(self, instance, session=None): ...
84
    async def count(self, model, *queries, session=None): ...
85

86
class SyncEngine:
87
    def __init__(self, client=None, database="test"): ...
88
    def save(self, instance, session=None): ...
89
    def find(self, model, *queries, sort=None, skip=0, limit=None, session=None): ...
90
    def find_one(self, model, *queries, sort=None, session=None): ...
91
    def delete(self, instance, session=None): ...
92
    def count(self, model, *queries, session=None): ...
93
```
94

95
[Database Engines](./engines.md)
96

97
### Model Definition
98

99
Document model classes with Pydantic integration for validation, serialization, and MongoDB-specific features like embedded documents and references.
100

101
```python { .api }
102
class Model:
103
    def model_copy(self, **changes): ...
104
    def model_update(self, **changes): ...
105
    def model_dump_doc(self, include=None, exclude=None, by_alias=False, exclude_unset=False, exclude_defaults=False): ...
106
    @classmethod
107
    def model_validate_doc(cls, raw_doc): ...
108

109
class EmbeddedModel:
110
    def model_update(self, **changes): ...
111
```
112

113
[Models](./models.md)
114

115
### Field Definitions
116

117
MongoDB-specific field definitions with indexing, validation, and constraint options.
118

119
```python { .api }
120
def Field(
121
    default=...,
122
    *,
123
    key_name=None,
124
    primary_field=False,
125
    index=False,
126
    unique=False,
127
    default_factory=None,
128
    title=None,
129
    description=None,
130
    **kwargs
131
): ...
132
```
133

134
[Fields](./fields.md)
135

136
### Query Building
137

138
Functional query construction using Python operators for MongoDB queries and sorting.
139

140
```python { .api }
141
def eq(field, value): ...
142
def ne(field, value): ...
143
def gt(field, value): ...
144
def gte(field, value): ...
145
def lt(field, value): ...
146
def lte(field, value): ...
147
def in_(field, sequence): ...
148
def not_in(field, sequence): ...
149
def match(field, pattern): ...
150
def and_(*elements): ...
151
def or_(*elements): ...
152
def nor_(*elements): ...
153
def asc(field): ...
154
def desc(field): ...
155
```
156

157
[Queries](./queries.md)
158

159
### Session Management
160

161
Session and transaction support for atomic operations and consistency guarantees.
162

163
```python { .api }
164
class AIOSession:
165
    async def __aenter__(self): ...
166
    async def __aexit__(self, exc_type, exc_val, exc_tb): ...
167

168
class AIOTransaction:
169
    async def __aenter__(self): ...
170
    async def __aexit__(self, exc_type, exc_val, exc_tb): ...
171

172
class SyncSession:
173
    def __enter__(self): ...
174
    def __exit__(self, exc_type, exc_val, exc_tb): ...
175

176
class SyncTransaction:
177
    def __enter__(self): ...
178
    def __exit__(self, exc_type, exc_val, exc_tb): ...
179
```
180

181
[Sessions](./sessions.md)
182

183
### BSON Types
184

185
MongoDB BSON types including ObjectId, Int64, Decimal128, Binary, and Regex.
186

187
```python { .api }
188
class ObjectId:
189
    def __init__(self, oid=None): ...
190
    def __str__(self): ...
191

192
class WithBsonSerializer:
193
    def __bson__(self): ...
194
```
195

196
[BSON Types](./bson-types.md)
197

198
### Index Management
199

200
Index definition and management for MongoDB collections.
201

202
```python { .api }
203
class Index:
204
    def __init__(self, *fields, **kwargs): ...
205

206
def Reference(*, key_name=None): ...
207
```
208

209
[Indexes](./indexes.md)
210

211
## Types
212

213
```python { .api }
214
from typing import Optional, Union, List, Dict, Any, Literal, Callable, Iterable
215
from motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorClientSession
216
from pymongo import MongoClient, IndexModel
217
from pymongo.client_session import ClientSession
218
from pydantic import ConfigDict
219
from pydantic_core import PydanticCustomError
220

221
# Engine types
222
AIOSessionType = Union[AsyncIOMotorClientSession, AIOSession, AIOTransaction, None]
223
SyncSessionType = Union[ClientSession, SyncSession, SyncTransaction, None]
224

225
# Configuration type
226
class ODMConfigDict(ConfigDict):
227
    collection: str | None
228
    parse_doc_with_default_factories: bool
229
    indexes: Callable[[], Iterable[Index | IndexModel]] | None
230

231
# Field proxy for query building
232
class FieldProxy:
233
    def __eq__(self, other): ...
234
    def __ne__(self, other): ...
235
    def __gt__(self, other): ...
236
    def __ge__(self, other): ...
237
    def __lt__(self, other): ...
238
    def __le__(self, other): ...
239

240
# Query and sort expressions
241
class QueryExpression(Dict[str, Any]): ...
242
class SortExpression(Dict[str, Literal[-1, 1]]): ...
243

244
# Cursors for result iteration
245
class AIOCursor:
246
    def __aiter__(self): ...
247
    def __await__(self): ...
248

249
class SyncCursor:
250
    def __iter__(self): ...
251
```
252

253
## Exceptions
254

255
```python { .api }
256
class BaseEngineException(Exception): ...
257
class DocumentNotFoundError(BaseEngineException): ...
258
class DuplicateKeyError(BaseEngineException): ...
259
class DocumentParsingError(ValueError): ...
260

261
def ODManticCustomError(error_type: str, message_template: str, context: Union[Dict[str, Any], None] = None) -> PydanticCustomError: ...
262
def KeyNotFoundInDocumentError(key_name: str) -> PydanticCustomError: ...
263
def ReferencedDocumentNotFoundError(foreign_key_name: str) -> PydanticCustomError: ...
264
def IncorrectGenericEmbeddedModelValue(value: Any) -> PydanticCustomError: ...
265
```