Skip to content

Managers and driver methods ​

Status

The installed Django driver applies a manager's get_queryset() (clause.manager) and its write overrides (create(), bulk_create(), update(), delete(), get_or_create(), update_or_create()); the native PostgreSQL driver applies get_queryset() to reads and writes and refuses a write whose manager or query set overrides the method it would call. Driver methods (call operations) raise NotSupportedError on both.

Django managers and query sets carry logic: a get_queryset() that hides soft-deleted rows, a create() that drops an argument, a delete() that refuses bulk deletion, a create_user() that hashes a password. In adorm the managers and their methods are declared on the adorm model; adorm generate writes the declarations from the Django code.

Where a method runs ​

MethodRunsDeclared by
builds a query (a filter, an ordering, a reusable condition)in the client, on every drivera method of an adorm QuerySet or Manager subclass, written by hand; for a generated model in the class named by @client_base
overrides what adorm runs as an operation: get_queryset(), create(), delete(), update(), get_or_create() …on the driver, through the ORM managernothing: the manager gets its ORM name, and every operation it builds names that manager
does other work on the database (create_user(), archive())on the driver, on the manager's method_manager, as a Call@expose or the ADORM_EXPOSE setting in the Django code; @driver_method on the adorm class

A Django query set method that annotates or aggregates ports the same way; see porting Django code, which also covers model properties that read the database. A query-building method runs in the client and returns a query set that further methods extend. A driver-side method returns data, not a query set, so it ends a chain.

A query with an ORM manager uses the construct clause.manager. Drivers that build their queries from the target ORM's query sets apply it: the Django driver and the native PostgreSQL driver.

  • The native PostgreSQL driver builds the query on the event loop: a manager's get_queryset() must only build a query, and one that accesses the database raises NotSupportedError.
  • It runs no Python code of the manager's other methods. A write whose manager or query set overrides the method it would call raises NotSupportedError before anything is written: create(), bulk_create(), update(), delete(), get_or_create() or update_or_create(); for get_or_create() also get() and create(); for update_or_create() also select_for_update(), get_or_create(), get() and create() (what runs on the driver side).
  • A driver method is a call operation and needs a driver that runs the ORM's code: the Django driver.

A driver without these capabilities raises NotSupportedError before anything runs. The queries of a manager that has only driver methods do not use the ORM manager, so on such a driver only its driver methods are refused.

Managers ​

Every model has objects. A manager declared in the class body is another entry to the model's rows:

python
from adorm import Manager, Model, ModelMeta


class Loan(Model):
    _meta = ModelMeta("library.Loan")
    id: int | None = None
    due: datetime.date
    archived: bool = False

    objects = Manager("objects")      # Django's objects: its get_queryset() and overrides apply
    all_loans = Manager()             # the plain rows, on every driver

Manager(orm_name) names the target ORM's manager. Every query, create(), bulk_create(), update(), delete(), get_or_create() and update_or_create() of Loan.objects carries that name (Query.manager) and the driver starts from that manager: Django's Loan.objects.get_queryset() selects the rows and Django's query set methods run the writes. Manager() without a name reads and writes the rows without manager logic.

method_manager names the target ORM's manager that runs the driver methods; it defaults to orm_name. A manager whose target only adds methods, such as Django's UserManager with create_user(), declares only method_manager: its queries carry no ORM manager and run on every driver.

python
class User(Model):
    ...
    objects = UserManager(method_manager="objects")   # create_user() on Django's User.objects

A manager is accessed like objects, on the model class (bound to the current session) or on a session:

python
await Loan.objects.count()                 # rows Django's manager returns
await Loan.all_loans.count()               # every row
await session.Loan.all_loans.count()       # on another session
session.bind(Loan, "all_loans")            # the same

Query set classes ​

A manager's queryset_class is the class of the query sets it returns. Its public methods are also methods of the manager, as with Django's as_manager():

python
from adorm import Manager, QuerySet


class LoanQuerySet(QuerySet):
    def overdue(self, today):
        return self.filter(due__lt=today)


class LoanManager(Manager):
    queryset_class = LoanQuerySet


class Loan(Model):
    ...
    objects = LoanManager("objects")
    late = LoanQuerySet.as_manager("objects")   # Manager.from_queryset(LoanQuerySet)("objects")


await Loan.objects.overdue(today).filter(reader_id=7).count()

Building methods return the same class, so client-side methods chain in any order. A manager that overrides get_queryset() adds its conditions in the client, on every driver:

python
class OpenLoans(Manager):
    def get_queryset(self):
        return super().get_queryset().filter(archived=False)

A reverse foreign key and a many-to-many relation return their rows from the target model's objects manager, like Django's related managers: the query set has the manager's queryset_class, starts from its get_queryset() and carries its ORM manager. A forward foreign key and a reverse one-to-one load their row without the target's manager, like Django's base manager.

python
await reader.loans.count()                              # Loan.objects: archived loans are left out
await reader.loans.overdue(today).archive("late")       # the query set methods of Loan.objects
await loan.reader                                        # the reader, whatever Reader.objects filters

Driver methods ​

A driver method is declared with @driver_method on an async def whose signature is the target method's; the body does not run:

python
from adorm import driver_method


class LoanQuerySet(QuerySet):
    @driver_method
    async def archive(self, reason: str = "") -> int:
        """Archive the loans with ``reason`` as their note; returns the number of loans."""


class LoanManager(Manager):
    queryset_class = LoanQuerySet

    @driver_method
    async def lend(self, reader_id: int, book_id: str, *, days: int = 14) -> "Loan":
        """Lend a book for ``days`` days."""


loan = await Loan.objects.lend(reader.pk, book.pk, days=7)          # runs LoanManager.lend in Django
count = await Loan.objects.overdue(today).archive("late")           # runs LoanQuerySet.archive on that query
  • A call checks its arguments against the signature and sends one Call operation to the manager's method_manager: a manager method with the manager's plain query, a query set method with the query set's query.
  • The annotations define the arguments' encoding, as field types do for the values of other operations.
  • The driver returns plain data. Every model instance in it, also inside lists, tuples and mapping values, is returned as an instance of the registered adorm model.
  • The driver runs only the methods the registered adorm model declares. A Call naming another method, a private one or one of another manager raises NotSupportedError before it reaches the driver.
  • Arguments are plain values: a model instance raises TypeError; pass its primary key.
  • A driver method is one operation. Outside a transaction it runs in the driver's autocommit mode; a method that writes several rows and must not stop halfway runs inside adorm.atomic() or opens its own transaction in the target ORM.
  • Signals and transaction.on_commit() callbacks of the target ORM run on the driver side.

Generated managers ​

adorm generate writes the managers of every Django model (see generating models). For these Django models:

python
from adorm import client_base, expose


class ReaderQuerySet(models.QuerySet):
    def create(self, **kwargs):
        kwargs.pop("username", None)
        return super().create(**kwargs)


class Reader(models.Model):
    name = models.CharField(max_length=100)
    objects = ReaderQuerySet.as_manager()


class LoanPolicyQuerySet(models.QuerySet):
    def delete(self):
        raise NotSupportedError("loan policies are deleted one at a time")


class LoanPolicy(models.Model):
    name = models.CharField(max_length=40, unique=True)
    objects = LoanPolicyQuerySet.as_manager()


@client_base("library.adorm_bases:LoanQuerySetBase")
class LoanQuerySet(models.QuerySet):
    def overdue(self, today):
        return self.filter(due__lt=today)

    @expose
    def archive(self, reason: str = "") -> int:
        """Archive the loans with ``reason`` as their note; returns the number of loans."""
        return self.update(archived=True, note=reason)


class LoanManager(models.Manager.from_queryset(LoanQuerySet)):
    def get_queryset(self):
        return super().get_queryset().filter(archived=False)

    @expose
    def lend(self, reader_id: int, book_id: str, *, days: int = 14) -> "Loan":
        """Lend a book for ``days`` days."""
        return self.create(reader_id=reader_id, book_id=book_id, due=timezone.localdate() + timedelta(days=days))


class Loan(models.Model):
    ...
    objects = LoanManager()
    all_loans = models.Manager()

and the setting ADORM_EXPOSE = ["auth.User.objects.create_user"], the generated modules contain:

python
class LoanQuerySet(LoanQuerySetBase):
    @driver_method
    async def archive(self, reason: str = "") -> int:
        """Archive the loans with ``reason`` as their note; returns the number of loans."""


class LoanManager(Manager):
    queryset_class = LoanQuerySet

    @driver_method
    async def lend(self, reader_id: int, book_id: str, *, days: int = 14) -> "Loan":
        """Lend a book for ``days`` days."""


class Reader(Model):
    ...
    objects = Manager("objects")


class LoanPolicy(Model):
    ...
    objects = Manager("objects")


class Loan(Model):
    ...
    objects = LoanManager("objects")
    all_loans = Manager()
python
class UserManager(Manager):
    @driver_method
    async def create_user(self, username, email=None, password=None, **extra_fields): ...


class User(Model):
    ...
    objects = UserManager(method_manager="objects")

With them:

python
reader = await Reader.objects.create(name="Ann", username="ann")   # Django's create() drops username
await LoanPolicy.objects.filter(max_days__gt=30).delete()          # NotSupportedError from the query set
await Loan.objects.count()                                         # loans that are not archived
await Loan.all_loans.count()                                       # every loan
user = await User.objects.create_user("ann", password="secret")   # Django hashes the password

create() on a manager with an ORM name also sends values that are not fields, so an override receives such arguments (username above). UserManager overrides no operation, so the queries of User run on every driver; only create_user() needs the Django driver.

A manager gets its ORM name only for an override of a method the driver calls on the Django manager (ROUTED_METHODS) that its client base does not define too; see generating models.

Client-side methods of generated models ​

A generated module is rewritten on every run, so methods ported by hand go into a module of their own. A Django manager or query set class decorated with @client_base("package.module:ClassName") gets a generated class derived from that adorm class:

python
# library/adorm_bases.py
from adorm import QuerySet


class LoanQuerySetBase(QuerySet):
    def overdue(self, today):
        return self.filter(due__lt=today)
python
await Loan.objects.overdue(today).archive("late")   # overdue() in the client, archive() on the driver

A client-base method that the Django class also defines, such as get_queryset(), replaces the Django one: the generator does not route the manager through the ORM manager for it. A public Django method that is neither exposed nor ported is not generated and is reported as a warning. The methods of installed packages are listed together, once per manager; adorm generate --ignore-third-party omits that list.

Released under the MIT License.