Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/dymmond/mongoz

ODM with Pydantic made it simple
https://github.com/dymmond/mongoz

async asyncio edgy esmerald esmerald-framework mongodb mongodb-atlas mongodb-database motor pydantic pydantic-v2 pymongo python python3 starlette

Last synced: 4 months ago
JSON representation

ODM with Pydantic made it simple

Awesome Lists containing this project

README 

        
# MongoZ





  mongoz






    🔥 ODM with Pydantic made it simple 🔥








    Test Suite






    Package version






    Supported Python versions






---



**Documentation**: [https://mongoz.dymmond.com][mongoz] 📚



**Source Code**: [https://github.com/dymmond/mongoz](https://github.com/dymmond/mongoz)



---



## Motivation



MongoZ is an async Python ODM (Object Document Mapper) for MongoDB built on top of [Motor][motor] and

[Pydantic][pydantic].



MongoZ is also inspired by the great work of [Aminalee](https://aminalaee.dev/mongox/) from the

MongoX.



So why a MongoZ if there is a MongoX? Well, MongoZ is from the same author of [Esmerald][esmerald],

[Saffier][saffier], [Mongoz][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](https://mongoz.dymmond.com/sinals.md),

for example, are needed, Mongox was not aiming at it and also since the creator of Mongoz is the

same as [Saffier][saffier] and [Saffier][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][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][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:



```shell

$ 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`.



```python

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="[email protected]")

    ```



=== "Alternative"



    ```python

    user = await User(name="Mongoz", email="[email protected]").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](./queries.md) 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!



[mongoz]: https://mongoz.dymmond.com

[motor]: https://github.com/mongodb/motor

[pydantic]: https://pydantic.dev/

[mongoz]: https://mongoz.dymmond.com

[saffier]: https://saffier.tarsild.io

[edgy]: https://edgy.tarsild.io

[esmerald]: https://esmerald.dev