Sessions
Sessions, the current session, bound models and the runner of operations outside a transaction, importable from adorm.executor. Session, BoundModel, create_session and current_session are also importable from adorm. The sessions topic explains how they fit together; transactions and the active transactions of a context are on the transactions page.
from adorm import BoundModel, create_session, current_session, Session
from adorm.executor import get_runner, Runner, set_runner, TransactionRunnerSessions
adorm.create_session(using="default", session_name="default")
The session (using, session_name). While a session is referenced, every call for its pair returns that object; a session nothing references is freed and the next call creates a new one. Both names are non-empty strings (ValueError otherwise). Thread-safe: concurrent first calls for one pair return one session.
reports = create_session(using="reports", session_name="nightly")
assert create_session("reports", "nightly") is reportsadorm.current_session()
The current session of the context: the session of the innermost Session.activate() block, else create_session("default", "default").
current_session() # Session('default', 'default')adorm.Session
A logical session, the pair (using, session_name). Session(using="default", session_name="default") returns create_session(using, session_name); one object per pair, immutable. A copy, a deep copy and an unpickled session are the same object.
| Member | Meaning |
|---|---|
using | the connection profile name |
session_name | the session name |
key | the pair (using, session_name) |
reports.key # ("reports", "nightly")
reports.Member # <BoundModel club.Member on Session('reports', 'nightly')>bind(model, manager="objects")
The manager manager of model (a model class or the label of a registered model) bound to this session, as a BoundModel. A label that is not registered raises LookupError; an abstract model and a model that is not a model class raise TypeError; a model without that manager raises AttributeError.
reports.bind(Member)
reports.bind("club.Member")
reports.bind(Loan, "all_loans")session.<ModelName>
The registered model with that class name, bound to this session: bind(model). No such model raises AttributeError; so do two registered models with that class name (bind one of them by label instead).
await reports.Member.objects.filter(active=True).count()activate()
A synchronous context manager that makes this session the current session for its block and restores the previous one on exit, also on an exception. Tasks created inside the block inherit the session.
with reports.activate():
await Member.objects.count() # runs on reportsatomic()
An Atomic block on this session: a transaction, or a savepoint when the session has an active Atomic transaction in the context.
async with reports.atomic() as tx:
await reports.Member.filter(active=False).update(fee=0)set_options(**options)
Replaces the session's connection options, the layer between the profile's options and connection_options() blocks; without arguments it removes them. They belong to the pair (using, session_name): a session object created again for the pair has them. Returns the checked options as a read-only mapping. Values are checked as in connection_options() (ValueError); a name the session's driver does not declare raises NotSupportedError when an operation runs. Thread-safe.
reports.set_options(statement_timeout=300, acquire_timeout=60)
reports.options # {'statement_timeout': 300, 'acquire_timeout': 60.0}
reports.set_options() # removes themoptions
The connection options set on the session with set_options(), a read-only mapping; empty when none are set.
async execute(operation)
Runs operation and returns its result: in this session's transaction active in the current context (active_transaction()), else on the runner. Errors of the transaction or the runner propagate unchanged. Without a transaction:
- without a runner it raises
InterfaceError; - a read of rows (
select,get,first,last,in_bulk) whose query hasselect_for_update()raisesTransactionManagementErrorbefore it reaches the runner.
from adorm.operations import Count
from adorm.query import Query
await reports.execute(Count(Query("club.Member")))Bound models
adorm.BoundModel
A model class bound to a session: what Model.objects, another manager of the model and session.<ModelName> return.
- A declared
Manageris an unboundBoundModel. Reading it on a model class gives a bound copy of the same class, so the methods of aManagersubclass are methods of the bound model. - Immutable. Equal when class, model, session, manager name and ORM names are the same. A copy and a deep copy are the same object; it pickles by model class, manager name and session.
BoundModel(model, session)is a manager without manager logic (no ORM names, plainQuerySetquery sets) and takes a concrete model class and aSession(TypeErrorotherwise). The declared managers come fromModel.<manager>,session.<ModelName>andbind().- Binding takes no slot and holds no transaction: every operation looks up the session's active transaction when it runs.
| Member | Meaning |
|---|---|
model | the model class |
session | the Session |
name | the manager's attribute name on the model ("objects") |
orm_name | the target ORM's manager the driver applies (Query.manager), None for none |
method_manager | the target ORM's manager the driver methods run on, None for none |
queryset_class | class attribute: the class of the query sets, QuerySet unless a subclass sets another |
objects | the model's objects manager on the same session; the bound model itself when it is that manager |
<manager name> | another manager of the model, on the same session (session.Loan.all_loans) |
get_queryset() | a queryset_class query set of every row, on session, whose query carries orm_name; a subclass overrides it to add conditions |
all() | get_queryset() |
async execute(operation) | session.execute(operation) |
The query methods of QuerySet are also methods of the bound model, applied to all(): filter, exclude, annotate, alias, order_by, values, values_list, only, defer, select_related, prefetch_related, distinct, none, select_for_update, union, intersection, difference, and the coroutines get, first, last, count, exists, in_bulk, aggregate, create, bulk_create, create_from_parent, get_or_create, update_or_create, update and delete. async for iterates over every row. A public method of queryset_class that QuerySet does not define is a method of the bound model too, applied to get_queryset(), unless it is a driver method declared queryset_only or a function with a true queryset_only attribute.
members = Member.objects
await members.get(pk=1)
await members.filter(active=False).delete()
async for member in members:
...
await Loan.objects.overdue(today).count() # a method of Loan's queryset_class
await Loan.objects.all_loans.count() # another manager, same sessionRunner
adorm.executor.Runner
The protocol of what runs an operation of a session outside a transaction: await runner.run(session, operation) acquires a slot for session, executes the operation, releases the slot and returns the result. Router is one.
class Direct:
def __init__(self, connection):
self.connection = connection
async def run(self, session, operation):
return await self.connection.execute(operation)adorm.executor.TransactionRunner
The protocol of a Runner that also holds a slot for a transaction: runner.slot(session) returns an async context manager that acquires a slot for session on entry, raising SessionTimeout or DeadlockError, yields its SlotLease and releases it on exit. Router is one. atomic() needs one as the runner.
assert isinstance(router, TransactionRunner)
async with router.slot(session) as lease:
await lease.call("execute", operation)adorm.executor.set_runner(runner)
Sets the Runner that Session.execute() uses outside a transaction. Returns the previous runner; None removes it. An object without an async run(session, operation) raises TypeError.
previous = set_runner(Direct(connection))adorm.executor.get_runner()
The Runner set with set_runner(). When none is set, inside a running event loop, and when the settings have a connection profile or a provider, the loop's default router (default_router()); None otherwise. atomic() takes its slots from it when it is a TransactionRunner.
adorm.configure(profiles={"default": {"driver": DjangoDriver}})
get_runner() # inside a coroutine: the event loop's default routerInstances
Importing adorm installs an executor resolver that returns the current session: an instance without its own executor (one the application built) runs save() and relation loads on the session current when they run. Instances a query set returns keep that query set's session.