mongoz

MongoZ

🔥 ODM with Pydantic made it simple 🔥

---

Documentation: https://mongoz.dymmond.com 📚

Source Code: https://github.com/dymmond/mongoz

---

Motivation

MongoZ is an async Python ODM (Object Document Mapper) for MongoDB built on top of Motor and Pydantic.

MongoZ is also inspired by the great work of Aminalee from the MongoX.

So why a MongoZ if there is a MongoX? Well, MongoZ is from the same author of Esmerald, Saffier, Mongoz and many other tools out there and they all follow a specific need and pattern of development.

Mongox implements really well some operations with MongoDB but for use cases where Signals, for example, are needed, Mongox was not aiming at it and also since the creator of Mongoz is the same as Saffier and Saffier, the friendly interface to interact is also a must.

In the end, there was a need to add Pydantic 2+ with some more extras that was not coming in the Mongox.

Mongoz

This is some sort of a fork of Mongox with a rewritten core but reusing some of its best features while adding additional ones and a common and friendly interface as well as intuitive.

This ODM is designed for async which means flexibility and compatibility with various frameworks out there such as Esmerald, FastAPI, Sanic, Starlette and many others making MongoZ framework agnostic.

Features

While adopting a familiar interface, it offers some cool and powerful features using Pydantic and Motor.

Syntax

Mongoz allows two different types of syntax to be used.

• With a familiar interface inspired by Django.
• With a familiar interface inspired by Mongox.

The documentation follows a more familiar interface inspired by Edgy but will also show how you could also use the other allowed syntax as well

Key features

• Document inheritance - For those cases where you don't want to repeat yourself while maintaining integrity of the documents.
• Abstract classes - That's right! Sometimes you simply want a document that holds common fields that doesn't need to created as a document in the database.
• Meta classes - If you are familiar with Django, this is not new to you and Mongoz offers this in the same fashion.
• Filters - Filter by any field you want and need.
• Model operators - Classic operations such as update, get, get_or_none and many others.
• Indexes - Unique indexes through meta fields.
• Signals - Quite useful feature if you want to "listen" to what is happening with your documents.

And a lot more you can do here.

Installation

To install Mongoz, run:

$ pip install mongoz

Quickstart

The following is an example how to start with Mongoz and more details and examples can be found throughout the documentation.

Use ipython to run the following from the console, since it supports await.

import asyncio

import mongoz

database_uri = "mongodb://localhost:27017"
registry = mongoz.Registry(database_uri, event_loop=asyncio.get_running_loop)


class User(mongoz.Document):
    name: str = mongoz.String(max_length=255)
    email: str = mongoz.Email(max_length=255)
    is_verified: bool = mongoz.Boolean(default=False)

    class Meta:
        registry = registry
        database = "my_db"

Now you can generate some documents and insert them into the database.

=== "Simple"

```python
user = await User.objects.create(name="Mongoz", email="[e-mail]")
```

=== "Alternative"

```python
user = await User(name="Mongoz", email="[e-mail]").create()
```

This will return an instance of a User in a Pydantic model and mypy will understand this is a User instance automatically which meand the type hints and validations will work everywhere.

Fetching

Since Mongoz was built on the top of Motor, means you can also use the same pattern to query as used in PyMongo/Motor.

=== "Simple"

```python
user = await User.objects.get(name="Mongoz")
```

=== "Alternative"

```python
user = await User.query({"name": "Mongoz"}).get()
```

Or you can use the User fields instead of dictionaries (check the "Alternative" for this option).

=== "Simple"

```python
user = await User.objects.get(name="Mongoz")
```

=== "Alternative"

```python
user = await User.query({User.name: "Mongoz"}).get()
```

Or a more python similar approach (check the "Alternative" for this option).

=== "Simple"

```python
user = await User.objects.get(name="Mongoz")
```

=== "Alternative"

```python
user = await User.query(User.name == "Mongoz").get()
```

There are plenty of operations you can do with Mongoz and you can see them all throughout the documentation or in the Queries section.

Mongoz praises simplicity and there is no preference in the syntax used within the queries. You can use what we called "Mongoz" option and the "Alternative" at the same time as both work really well combined.

Both are Mongoz syntaxes but for the sake of the documentation, we classify them with different names for representation purposes only.

Note

Mongoz document declaration with typing is merely visual. The validations of the fields are not done by the typing of the attribute of the documents but from the mongoz fields.

Which means you don't need to worry about the wrong typing as long as you declare the correct field type.

So does that mean Pydantic won't work if you don't declare the type? Absolutely not. Internally Mongoz runs those validations through the declared fields and the Pydantic validations are done exactly in the same way you do a normal Pydantic model.

Nothing to worry about!