Skip to main content

Aggify

Async-first MongoDB ODM with a Django-style API - for Django, FastAPI, gRPC and plain Python

Package version Downloads Supported Python versions Coverage License Telegram

Aggify 1.0 is a complete rewrite: no MongoEngine, native async/await on pymongo's AsyncMongoClient, an API you already know from the Django ORM, and aggregation pipelines that fit on one line.

import aggify
from aggify import Document, StringField, DecimalField, ReferenceField, Sum, Count

aggify.connect("mongodb://localhost:27017/shop")

class Customer(Document):
    name = StringField(required=True)
    country = StringField(max_length=2)

class Order(Document):
    customer = ReferenceField(Customer)
    status = StringField(choices=["new", "paid"], default="new")
    total = DecimalField()

best = await (
    Order.objects.filter(status="paid", customer__country="DE")      # $lookup + $unwind + $match
    .values("customer__name")
    .annotate(revenue=Sum("total"), orders=Count())                  # $group
    .filter(orders__gte=3)                                           # HAVING
    .order_by("-revenue")[:10]                                       # $sort + $limit
    .alist()
)

Highlights

  • Sync and async - every I/O method has an a-twin (aget, alist, asave, acount, aupdate, ...); one async client per event loop, so it is safe in FastAPI, grpc.aio, Django's async_to_sync and pytest-asyncio.
  • Django-style - Model.objects, Q, F, annotate, aggregate, values, select_related, get_or_create, signals, managers, DoesNotExist, pagination-ready querysets.
  • Complex queries, short - automatic joins (owner__country="DE"), values().annotate() grouping, conditional aggregates (Sum("x", filter=Q(...))), window functions, $facet, $bucket, $graphLookup, sub-pipeline $lookup, array operators, atomic expression updates. See the cookbook.
  • Framework-agnostic integrations - pip install "aggify[fastapi|grpc|django|pydantic]". Pydantic schemas from documents, FastAPI lifespan/errors/pagination, gRPC status mapping, Django app/forms/shortcuts/middleware, and an ObjectIdField to link Django ORM models to Mongo documents.
  • Secure by default - typed fields stop operator injection ({"$ne": ""}), regex lookups are escaped, server-side JavaScript is blocked, field names validated, strict constructors, resource limits, masked credentials.
  • Efficient - save() sends only changed fields, optional optimistic locking, only()/defer()/values(), streaming iterators, bulk operations.
  • Well tested - 470+ tests: unit, integration against a real replica set, differential property tests (random Q trees vs. a Python reference), FastAPI/gRPC/Django end-to-end tests, Python 3.9-3.13.

Install

pip install aggify                       # core (pymongo >= 4.13)
pip install "aggify[fastapi]"            # + pydantic / fastapi helpers
pip install "aggify[django]" "aggify[grpc]" "aggify[all]"

A tour

# models: typed fields, embedded documents, references, indexes
class Account(Document):
    username = StringField(required=True, unique=True)
    tags = ListField(StringField())
    address = EmbeddedField(Address)
    created_at = DateTimeField(auto_now_add=True)
    class Meta:
        ordering = ["username"]
        indexes = [Index("tags")]

# CRUD - only changed fields are written
acc = await Account.objects.acreate(username="ali", tags=["vip"])
acc.address = Address(city="Tehran")
await acc.asave()                               # {"$set": {"address": {...}}}

# querying
Account.objects.filter(Q(tags="vip") | Q(address__city__istartswith="te"), ~Q(banned=True))
Account.objects.filter(age__gt=F("score") * 10).only("username")[:20]

# atomic updates, including server-side expressions
Account.objects.filter(pk=acc.pk).update(inc__logins=1, push__tags="beta")
Product.objects.update(price=Round(F("price") * Value(1.1), 2))

# transactions (replica set)
async with aggify.atransaction():
    await Order.objects.acreate(...)
    await Product.objects.filter(pk=pid).aupdate(inc__stock=-1)

# the compiled query is always inspectable
Account.objects.filter(address__city="Tehran").query

Need a stage a queryset does not have? The immutable pipeline builder is one call away:

from aggify import Aggify
Aggify(Order).filter(status="paid").facet(
    by_country=Aggify(Order).group("customer__country", n=Count()),
    page=[{"$limit": 20}],
).execute()

Documentation

Full documentation lives in docs/ (build with make docs): quickstart - models - querying - pipelines - cookbook - security - testing - Django - FastAPI - gRPC - MongoEngine migration - upgrading from 0.x - فارسی.

Development

make install && make mongo && make test      # needs Docker for the throw-away MongoDB replica set

See CONTRIBUTING.md. Security reports: SECURITY.md.

Metadata

Release files for aggify 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aggify 1.0.0
File Size Uploaded Provenance Actions
aggify-1.0.0.tar.gz 154.3 kB Without provenance Details for aggify-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aggify 1.0.0
File Interpreter ABI Platform Actions
aggify-1.0.0-py3-none-any.whl Python 3 none any Details for aggify-1.0.0-py3-none-any.whl

Total release size: 237.9 kB

Release files / aggify-1.0.0.tar.gz

Download URL aggify-1.0.0.tar.gz
Size 154.3 kB
Tags Source
SHA-256 checksum
How to use checksums
9052519088885b827c44b5f3f8a8ec292ac517c38a5f90ad2f6fd1256411f54a
BLAKE2b-256 checksum
How to use checksums
8b5b6d8c004f0e8cc3888d0c78cf43e86b17545a668b1554a67f03b00388ff41
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Release files / aggify-1.0.0-py3-none-any.whl

Download URL aggify-1.0.0-py3-none-any.whl
Size 83.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a198e72aa38d938ae8264199b3287133bf3a514158a0f8d42bb88f4c96b25531
BLAKE2b-256 checksum
How to use checksums
10d632e2e2c1f3730d83ead7855019fe8e4a60eafae0d8df75117844276a5a7a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Security for aggify 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page