Mongoz
Typed asynchronous MongoDB documents and queries for Python.
Mongoz is an asynchronous object-document mapper for MongoDB, built on native PyMongo Async and Pydantic. It combines typed documents, composable clone-on-write queries, deliberate persistence semantics, inspectable index reconciliation, sessions, transactions, aggregation, bulk writes, and direct native-driver escape hatches.
- Documentation: mongoz.dymmond.com
- Source: github.com/dymmond/mongoz
- Migration: modernization guide
Installation
python -m pip install mongoz
Mongoz supports Python 3.10–3.14, PyMongo >=4.13,<5.0, and Pydantic 2. The package ships
py.typed for PEP 561 consumers.
Quickstart
from mongoz import Boolean, Document, Registry, String
registry = Registry("mongodb://localhost:27017")
class User(Document):
name: str = String(min_length=1, max_length=80)
email: str = String(unique=True)
active: bool = Boolean(default=True)
class Meta:
registry = registry
database = "app"
async def main() -> None:
async with registry:
user = await User.objects.create(name="Ada", email="ada@example.com")
found = await User.objects.get(id=user.id)
active_users = await User.objects.filter(active=True).sort("name")
await found.update(name="Ada Lovelace")
await found.delete()
assert active_users[0].email == "ada@example.com"
A Registry owns one PyMongo AsyncMongoClient. Reuse it for the application lifecycle and close it
during shutdown; a closed Registry is final. Document declaration performs no database or index I/O.
Why Mongoz
- Pydantic-backed
DocumentandEmbeddedDocumentmodels - familiar Manager filters and explicit
Q/field expressions - immutable query derivation for safe reuse
- atomic patch updates and explicit full-model save behavior
- index planning before reviewed reconciliation
- PyMongo Async sessions, transactions, aggregation, and bulk writes
- deterministic async-only document signals
- typed native client, database, collection, cursor, and session boundaries
- security guidance for raw queries, regex, credentials, and destructive indexes
Mongoz does not replace PyMongo's ownership of topology, pooling, timeouts, retries, read/write
concerns, native errors, or transaction lifecycle. Use registry.driver, database.driver, and
collection.driver when the driver is the right abstraction.
Documentation
New users should begin with the Quickstart. Existing applications should review the migration guide. Production deployments should use the operations checklist and security guide.
Contributing and security
The contributor guide documents the Zensical documentation workflow, quality gates, real MongoDB topologies, typing checks, and package proof.
Report suspected vulnerabilities privately through the repository Security tab according to
SECURITY.md, not through a public issue.
1 maintainer
Release files for mongoz 0.15.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| mongoz-0.15.0.tar.gz | 47.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mongoz-0.15.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 114.9 kB
Release files / mongoz-0.15.0.tar.gz
| Download URL | mongoz-0.15.0.tar.gz |
|---|---|
| Size | 47.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a7b55929bbc3badd123ccccf0dc21785ab6ac799997ca5c97697ee584f890be4
|
|
BLAKE2b-256 checksum How to use checksums |
c459d1ee3c53e2c7c8d40261d7261d2bbbd72ad379ecd3ff848d58703558b2b4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.21
|
Release files / mongoz-0.15.0-py3-none-any.whl
| Download URL | mongoz-0.15.0-py3-none-any.whl |
|---|---|
| Size | 67.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2ef19b350d1cf52a3f560edf8602a969ed053869bf52e66ca8b4f1fb657a7f8d
|
|
BLAKE2b-256 checksum How to use checksums |
bdc77ff285ec7467becde01c77bc2888b85f3deda8ef119dfbd1847d17d3abe2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.21
|
