| Name | mongoz JSON |
| Version |
0.7.0
JSON |
| download |
| home_page | None |
| Summary | ODM with pydantic made it simple |
| upload_time | 2024-04-26 18:37:35 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
mongodb
mongoz
nosql
odm
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# MongoZ
<p align="center">
<a href="https://mongoz.tarsild.io"><img src="https://res.cloudinary.com/tarsild/image/upload/v1695724284/packages/mongoz/nwtcudxmncgoyw4em0th.png" alt='mongoz'></a>
</p>
<p align="center">
<em>🔥 ODM with Pydantic made it simple 🔥</em>
</p>
<p align="center">
<a href="https://github.com/tarsil/mongoz/workflows/Test%20Suite/badge.svg?event=push&branch=main" target="_blank">
<img src="https://github.com/tarsil/mongoz/workflows/Test%20Suite/badge.svg?event=push&branch=main" alt="Test Suite">
</a>
<a href="https://pypi.org/project/mongoz" target="_blank">
<img src="https://img.shields.io/pypi/v/mongoz?color=%2334D058&label=pypi%20package" alt="Package version">
</a>
<a href="https://pypi.org/project/mongoz" target="_blank">
<img src="https://img.shields.io/pypi/pyversions/mongoz.svg?color=%2334D058" alt="Supported Python versions">
</a>
</p>
---
**Documentation**: [https://mongoz.tarsild.io][mongoz] 📚
**Source Code**: [https://github.com/tarsil/mongoz](https://github.com/tarsil/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.tarsild.io/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="mongoz@mongoz.com")
```
=== "Alternative"
```python
user = await User(name="Mongoz", email="mongoz@mongoz.com").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.tarsild.io
[motor]: https://github.com/mongodb/motor
[pydantic]: https://pydantic.dev/
[mongoz]: https://mongoz.tarsild.io
[saffier]: https://saffier.tarsild.io
[edgy]: https://edgy.tarsild.io
[esmerald]: https://esmerald.dev
Raw data
{
"_id": null,
"home_page": null,
"name": "mongoz",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "mongodb, mongoz, nosql, odm",
"author": null,
"author_email": "Tiago Silva <tiago.arasivla@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/20/df/8bd7ecd6c75f9497d8cee9e45355d0d26c0f03da226105200ff45e9b2fd4/mongoz-0.7.0.tar.gz",
"platform": null,
"description": "# MongoZ\n\n<p align=\"center\">\n <a href=\"https://mongoz.tarsild.io\"><img src=\"https://res.cloudinary.com/tarsild/image/upload/v1695724284/packages/mongoz/nwtcudxmncgoyw4em0th.png\" alt='mongoz'></a>\n</p>\n\n<p align=\"center\">\n <em>\ud83d\udd25 ODM with Pydantic made it simple \ud83d\udd25</em>\n</p>\n\n<p align=\"center\">\n<a href=\"https://github.com/tarsil/mongoz/workflows/Test%20Suite/badge.svg?event=push&branch=main\" target=\"_blank\">\n <img src=\"https://github.com/tarsil/mongoz/workflows/Test%20Suite/badge.svg?event=push&branch=main\" alt=\"Test Suite\">\n</a>\n\n<a href=\"https://pypi.org/project/mongoz\" target=\"_blank\">\n <img src=\"https://img.shields.io/pypi/v/mongoz?color=%2334D058&label=pypi%20package\" alt=\"Package version\">\n</a>\n\n<a href=\"https://pypi.org/project/mongoz\" target=\"_blank\">\n <img src=\"https://img.shields.io/pypi/pyversions/mongoz.svg?color=%2334D058\" alt=\"Supported Python versions\">\n</a>\n</p>\n\n---\n\n**Documentation**: [https://mongoz.tarsild.io][mongoz] \ud83d\udcda\n\n**Source Code**: [https://github.com/tarsil/mongoz](https://github.com/tarsil/mongoz)\n\n---\n\n## Motivation\n\nMongoZ is an async Python ODM (Object Document Mapper) for MongoDB built on top of [Motor][motor] and\n[Pydantic][pydantic].\n\nMongoZ is also inspired by the great work of [Aminalee](https://aminalaee.dev/mongox/) from the\nMongoX.\n\nSo why a MongoZ if there is a MongoX? Well, MongoZ is from the same author of [Esmerald][esmerald],\n[Saffier][saffier], [Mongoz][mongoz] and many other tools out there and they all follow a specific need\nand pattern of development.\n\nMongox implements really well some operations with MongoDB but for use cases where [Signals](https://mongoz.tarsild.io/sinals.md),\nfor example, are needed, Mongox was not aiming at it and also since the creator of Mongoz is the\nsame as [Saffier][saffier] and [Saffier][saffier], the friendly interface to interact is also a must.\n\nIn the end, there was a need to add Pydantic 2+ with some more extras that was not coming in the\nMongox.\n\n## Mongoz\n\nThis is some sort of a fork of Mongox with a rewritten core but reusing some of its best features\nwhile adding additional ones and a common and friendly interface as well as intuitive.\n\nThis ODM is designed for **async** which means flexibility and compatibility with various frameworks\nout there such as [Esmerald][esmerald], FastAPI, Sanic, Starlette and many others making MongoZ\n**framework agnostic**.\n\n## Features\n\nWhile adopting a familiar interface, it offers some cool and powerful features using Pydantic and\nMotor.\n\n### Syntax\n\n**Mongoz allows two different types of syntax to be used**.\n\n* With a familiar interface inspired by Django.\n* With a familiar interface inspired by Mongox.\n\n**The documentation follows a more familiar interface inspired by [Edgy][edgy] but will also show**\n**how you could also use the other allowed syntax as well**\n\n### Key features\n\n* **Document inheritance** - For those cases where you don't want to repeat yourself while maintaining integrity of the documents.\n* **Abstract classes** - That's right! Sometimes you simply want a document that holds common fields that doesn't need to created as\na document in the database.\n* **Meta classes** - If you are familiar with Django, this is not new to you and Mongoz offers this in the same fashion.\n* **Filters** - Filter by any field you want and need.\n* **Model operators** - Classic operations such as `update`, `get`, `get_or_none` and many others.\n* **Indexes** - Unique indexes through meta fields.\n* **Signals** - Quite useful feature if you want to \"listen\" to what is happening with your documents.\n\nAnd a lot more you can do here.\n\n## Installation\n\nTo install Mongoz, run:\n\n```shell\n$ pip install mongoz\n```\n\n## Quickstart\n\nThe following is an example how to start with Mongoz and more details and examples can be found throughout the documentation.\n\nUse `ipython` to run the following from the console, since it supports `await`.\n\n```python\nimport asyncio\n\nimport mongoz\n\ndatabase_uri = \"mongodb://localhost:27017\"\nregistry = mongoz.Registry(database_uri, event_loop=asyncio.get_running_loop)\n\n\nclass User(mongoz.Document):\n name: str = mongoz.String(max_length=255)\n email: str = mongoz.Email(max_length=255)\n is_verified: bool = mongoz.Boolean(default=False)\n\n class Meta:\n registry = registry\n database = \"my_db\"\n```\n\nNow you can generate some documents and insert them into the database.\n\n=== \"Simple\"\n\n ```python\n user = await User.objects.create(name=\"Mongoz\", email=\"mongoz@mongoz.com\")\n ```\n\n=== \"Alternative\"\n\n ```python\n user = await User(name=\"Mongoz\", email=\"mongoz@mongoz.com\").create()\n ```\n\nThis will return an instance of a `User` in a Pydantic model and `mypy` will understand this is a\n`User` instance automatically which meand the type hints and validations will work everywhere.\n\n### Fetching\n\nSince Mongoz was built on the top of Motor, means you can also use the same pattern to query as used\nin PyMongo/Motor.\n\n=== \"Simple\"\n\n ```python\n user = await User.objects.get(name=\"Mongoz\")\n ```\n\n=== \"Alternative\"\n\n ```python\n user = await User.query({\"name\": \"Mongoz\"}).get()\n ```\n\nOr you can use the `User` fields instead of dictionaries (check the \"Alternative\" for this option).\n\n=== \"Simple\"\n\n ```python\n user = await User.objects.get(name=\"Mongoz\")\n ```\n\n=== \"Alternative\"\n\n ```python\n user = await User.query({User.name: \"Mongoz\"}).get()\n ```\n\nOr a more python similar approach (check the \"Alternative\" for this option).\n\n=== \"Simple\"\n\n ```python\n user = await User.objects.get(name=\"Mongoz\")\n ```\n\n=== \"Alternative\"\n\n ```python\n user = await User.query(User.name == \"Mongoz\").get()\n ```\n\nThere are plenty of operations you can do with Mongoz and you can see them all throughout the\ndocumentation or in the [Queries](./queries.md) section.\n\n**Mongoz** praises simplicity and there is no preference in the syntax used within the queries.\nYou can use what we called \"Mongoz\" option and the \"Alternative\" at the same time as both work\nreally well combined.\n\n**Both are Mongoz syntaxes but for the sake of the documentation, we classify them with different names for representation purposes only**.\n\n## Note\n\nMongoz document declaration with typing is merely visual. The validations of the fields are not done by the typing of\nthe attribute of the documents but from the mongoz fields.\n\nWhich means you don't need to worry about the wrong typing as long as you declare the correct field type.\n\nSo does that mean Pydantic won't work if you don't declare the type? Absolutely not.\nInternally Mongoz runs those validations through the declared fields and the Pydantic validations\nare done exactly in the same way you do a normal Pydantic model.\n\nNothing to worry about!\n\n\n[mongoz]: https://mongoz.tarsild.io\n[motor]: https://github.com/mongodb/motor\n[pydantic]: https://pydantic.dev/\n[mongoz]: https://mongoz.tarsild.io\n[saffier]: https://saffier.tarsild.io\n[edgy]: https://edgy.tarsild.io\n[esmerald]: https://esmerald.dev\n",
"bugtrack_url": null,
"license": null,
"summary": "ODM with pydantic made it simple",
"version": "0.7.0",
"project_urls": {
"Changelog": "https://mongoz.tarsild.io/release-notes/",
"Documentation": "https://mongoz.tarsild.io",
"Funding": "https://github.com/sponsors/tarsil",
"Homepage": "https://github.com/tarsil/mongoz",
"Source": "https://github.com/tarsil/mongoz"
},
"split_keywords": [
"mongodb",
" mongoz",
" nosql",
" odm"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ee95680584e931a3b96f8412a02ffdbf8d1bedbe024c96b40a262e15c80d5149",
"md5": "54662ba5701627f781e13db150eac897",
"sha256": "3db1072baed32a0b9f6b82adbefcd941a46048e32c44223dd6de6f264489f809"
},
"downloads": -1,
"filename": "mongoz-0.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "54662ba5701627f781e13db150eac897",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 48050,
"upload_time": "2024-04-26T18:37:33",
"upload_time_iso_8601": "2024-04-26T18:37:33.793558Z",
"url": "https://files.pythonhosted.org/packages/ee/95/680584e931a3b96f8412a02ffdbf8d1bedbe024c96b40a262e15c80d5149/mongoz-0.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "20df8bd7ecd6c75f9497d8cee9e45355d0d26c0f03da226105200ff45e9b2fd4",
"md5": "7cd6afa6dfeace90dc4d6967171ff295",
"sha256": "eccf7dbaa260dda3b14e9be55c0cffa1540bbc73477aa88b9a07851b20dc4a00"
},
"downloads": -1,
"filename": "mongoz-0.7.0.tar.gz",
"has_sig": false,
"md5_digest": "7cd6afa6dfeace90dc4d6967171ff295",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 31567,
"upload_time": "2024-04-26T18:37:35",
"upload_time_iso_8601": "2024-04-26T18:37:35.689164Z",
"url": "https://files.pythonhosted.org/packages/20/df/8bd7ecd6c75f9497d8cee9e45355d0d26c0f03da226105200ff45e9b2fd4/mongoz-0.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-26 18:37:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sponsors",
"github_project": "tarsil",
"github_not_found": true,
"lcname": "mongoz"
}
