MongoZ¶
🔥 ODM com Pydantic simpificado 🔥
Documentação: https://mongoz.dymmond.com 📚
Código Fonte: https://github.com/dymmond/mongoz
Motivação¶
MongoZ é um ODM (Object Document Mapper) assíncrono para MongoDB em Python, construído sobre o Motor e o Pydantic.
MongoZ também é inspirado no excelente trabalho do Aminalee com o MongoX.
Então, o porquê de um MongoZ se já existe o MongoX? Bem, o MongoZ é do mesmo autor do Esmerald, Saffier, e muitas outras ferramentas, e todas elas seguem uma necessidade e padrão específicos de desenvolvimento.
O Mongox implementa muito bem algumas operações com o MongoDB, mas para casos de uso onde são necessários Signals, por exemplo, o Mongox não foi desenhado para tal. Além disso, como o criador do Mongoz é o mesmo do Saffier e do Edgy, a interface amigável para interação com o ODM também é essencial.
No final, havia a necessidade de adicionar o Pydantic 2+ com alguns extras que não estavam presentes no Mongox.
MongoZ¶
Este é uma espécie de fork do Mongox com um core reescrito, mas reutilizando algumas das suas melhores funcionalidades, ao mesmo tempo em que adiciona recursos adicionais e uma interface comum e amigável, para além de intuitiva.
Este ODM é desenhado para ser assíncrono, o que significa flexibilidade e compatibilidade com várias frameworks disponíveis, como Esmerald, FastAPI, Sanic, Starlette, Lilya e muitas outras, tornando o MongoZ independente de qualquer framework.
Funcionalidades¶
Ao adoptar uma interface mais familiar, este também oferece recursos interessantes e poderosos usando o Pydantic e o Motor.
Sintaxe¶
Mongoz permite o uso de dois tipos diferentes de sintaxe.
- Com uma interface familiar inspirada no Edgy.
- Com uma interface familiar inspirada no Mongox.
A documentação segue uma interface mais familiar inspirada no Edgy, mas também mostrará como pode usar a outra sintaxe também permitida.
Principais recursos¶
- Herança de documentos - Para casos em que não quer repetir informações, mantendo a integridade dos documentos.
- Classes abstratas - Isso mesmo! Às vezes só quer um documento que contenha campos comuns e que não precise ser criado como um documento na base de dados.
- Classes Meta - Se está familiarizado com o Django, isto não é novidade e o Mongoz oferece isso da mesma forma.
- Filtros - Filtrar por qualquer campo que queira e precise.
- Operadores de modelo - Operações clássicas como
update,get,get_or_nonee muitas outras. - Índices - Índices únicos através dos meta campos.
- Sinais - Recurso bastante útil se você quiser "ouvir" o que está a acontecer com os documentos.
E muito mais pode-se fazer aqui.
Instalação¶
Para instalar o Mongoz, execute:
$ pip install mongoz
Início Rápido¶
O seguinte é um exemplo de como começar com o Mongoz e mais detalhes e exemplos podem ser encontrados ao longo da documentação.
Utilize o ipython para executar o seguinte a partir da consola, uma vez que suporta await.
import mongoz
database_uri = "mongodb://localhost:27017"
registry = mongoz.Registry(database_uri)
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"
Agora pode gerar alguns documentos e inseri-los na base de dados.
user = await User.objects.create(name="Mongoz", email="mongoz@mongoz.com")
user = await User(name="Mongoz", email="mongoz@mongoz.com").create()
Isso retornará uma instância de um User num modelo Pydantic e o mypy entenderá automaticamente que esta é uma instância de User, o que significa que os tipos e validações funcionarão em todo o lado.
Pesquisar¶
Como o Mongoz foi construído em cima do Motor, significa que também pode utilizar o mesmo padrão de consulta utilizado no PyMongo/Motor.
user = await User.objects.get(name="Mongoz")
user = await User.query({"name": "Mongoz"}).get()
Ou pode usar os campos do User em vez de dicionários (seleccione a opção "Alternativa" para esta opção).
user = await User.objects.get(name="Mongoz")
user = await User.query({User.name: "Mongoz"}).get()
Ou uma abordagem mais semelhante ao Python (seleccione a opção "Alternativa" para esta opção).
user = await User.objects.get(name="Mongoz")
user = await User.query(User.name == "Mongoz").get()
Existem muitas operações que pode fazer com o Mongoz e pode vê-las todas ao longo da documentação ou na secção Queries.
Mongoz valoriza a simplicidade e não há preferência na sintaxe usada nas pesquisas. Pode usar o que chamamos de opção "Mongoz" e a opção "Alternativa" ao mesmo tempo, pois ambas funcionam muito bem em comum.
Ambas são sintaxes do Mongoz, mas para fins de representação, classificamos com nomes diferentes na documentação.
Observação¶
A declaração de documentos do Mongoz com tipagem é meramente visual. As validações dos campos não são feitas pela tipagem do atributo dos documentos, mas sim pelos campos do Mongoz.
Isso significa que não precisa se preocupar com a tipagem errada, desde que declare o tipo de campo correcto.
Então isso significa que o Pydantic não funcionará se não declarar o tipo? Claramente que não. Internamente, o Mongoz executa essas validações por meio dos campos declarados e as validações do Pydantic são feitas exatamente da mesma forma que faria num modelo Pydantic normal.
Nada com que se preocupar!