xtr_service_contracts ¶
Contracts for the lifecycle of a service: what a container drives, not what a service does.
A service's own contract says what it is for — a logger logs, a lock locks. This package holds the other kind: what something built by a container must answer to so the container can manage it, whatever it is for.
Deliberately a leaf. It has no dependencies and should never acquire any, because every other contract package in this ecosystem is free to depend on this one, and that only stays true while nothing here can drag anything in.
ContainerInterface ¶
Bases: Protocol
Builds and hands out services, and reads the parameters fixed while building.
A service is identified by its type plus an optional qualifier that
chooses between several services registered for that same type.
runtime_checkable verifies method presence only, never signatures, so an
implementation inherits this Protocol explicitly to have a type checker
confirm it against the contract.
get
async
¶
Return the service of service type, the one named by qualifier if given.
Raises:
-
LookupError–If no such service is registered — that is, when :meth:
hasisFalsefor the same arguments. A service that is registered but cannot be built raises its own error instead.
has ¶
Whether a service of service type (and qualifier, if given) is registered.
get_parameter ¶
Return the build-time parameter name, a dotted path into nested configuration.
Raises:
-
LookupError–If :meth:
has_parameterisFalseforname.
ResetInterface ¶
Bases: Protocol
Returns to a clean state between units of work.
A long-running process — a worker consuming messages, a server answering
requests — builds its services once and uses them many times. Buffers,
caches, accumulated state and generated ids belong to one unit of work
rather than to the service that holds them; :meth:reset ends that unit,
so the next starts clean while configuration survives.
A container is the usual caller. It knows what it built, so it can reset whatever asks for it between units of work, and neither side has to know anything else about the other.
:meth:reset is awaited, because clearing state is not always a local
assignment: a rate limiter's count or a cache's entries may live in
another process entirely, and reaching them is I/O. A service whose state
is its own awaits nothing and returns at once; one whose state lives
elsewhere awaits the trip, and the caller — a worker between messages —
is already somewhere it can wait.
A container resets singletons only. A service built for one unit of work
— scoped or transient — lives and dies with that unit, so it has nothing
to reset. Units overlap — a worker handling several messages at once,
requests answered together — so a singleton is reset while other units
are still running: its :meth:reset must be safe then, clearing only
what it can work out again, never state a running unit reads. A service
that holds state for one unit keeps it in that unit — a scoped service,
or state kept per unit of work — rather than waiting for a reset.
Being @runtime_checkable costs precision: :func:isinstance confirms a
reset attribute is present, not that it is callable, so an object whose
reset is a plain value passes the check and then fails when called.
Guard the call — callable(getattr(service, "reset", None)) — rather
than trust the check alone.
A container's autoconfiguration keys on inheritance, so a service that
means to be reset inherits this interface; a structural reset alone
matches :func:isinstance but the container never sees it.
ServiceCollectionInterface ¶
Bases: ServiceProviderInterface[T_co], Protocol
A :class:ServiceProviderInterface that also reports its size and iterates.
Iterating yields (name, service) pairs, each service built lazily as it
is reached, in the order :meth:~ServiceProviderInterface.provided_services
lists them.
runtime_checkable verifies method presence only, never signatures, so an
implementation inherits this Protocol explicitly to have a type checker
confirm it against the contract.
ServiceProviderInterface ¶
Bases: Protocol
Provides a fixed set of services, each reachable by its name.
Unlike a :class:ContainerInterface, which is keyed by type, a provider is
keyed by name: it knows every name it can answer to, and the type each of
those services has, without building any of them.
runtime_checkable verifies method presence only, never signatures, so an
implementation inherits this Protocol explicitly to have a type checker
confirm it against the contract.
get
async
¶
Return the service registered under name, building it on first request.
Raises:
-
LookupError–If :meth:
hasisFalseforname.
provided_services ¶
Return every provided name mapped to the type of the service it yields.
UnitParticipantInterface ¶
Bases: Protocol
Is told when each unit of work begins and when it ends.
A unit of work — a request, a message, a command — is opened by a container; a service that keeps state per unit opens its own part of it here, and closes it when the unit ends, however the unit ends. A unit joined by work started inside it is not a new one: only the unit that was opened begins and ends.
:meth:unit_began runs before the unit's scope exists, so it cannot read
the unit; :meth:unit_ended runs after the unit's scoped services were
torn down, so what their teardown did still happened inside the unit.
Keep nothing per unit on the participant itself, nor in a stack in a
context variable: return from :meth:unit_began whatever
:meth:unit_ended needs back — a context variable's token, say — and the
container hands exactly that to :meth:unit_ended for the same unit.
:meth:unit_ended may run in another context than :meth:unit_began
did, when the unit is exited from another task, so a token it is handed
is reset under contextlib.suppress(ValueError).
Both hooks are synchronous: they run at every unit's edges, where nothing may be awaited.