Skip to content

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

get(service: type[T], /, qualifier: Hashable | None = None) -> T

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:has is False for the same arguments. A service that is registered but cannot be built raises its own error instead.

has

has(service: type[object], /, qualifier: Hashable | None = None) -> bool

Whether a service of service type (and qualifier, if given) is registered.

get_parameter

get_parameter(name: str) -> object

Return the build-time parameter name, a dotted path into nested configuration.

Raises:

  • LookupError –

    If :meth:has_parameter is False for name.

has_parameter

has_parameter(name: str) -> bool

Whether the parameter name is set.

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

get(name: Hashable) -> T_co

Return the service registered under name, building it on first request.

Raises:

has

has(name: Hashable) -> bool

Whether a service is registered under name.

provided_services

provided_services() -> Mapping[Hashable, type[object]]

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.

unit_began

unit_began() -> object | None

Open this participant's part of a new unit of work.

Returns:

  • What ( object | None ) –

    meth:unit_ended is handed back when the unit ends.

unit_ended

unit_ended(token: object | None) -> None

Close this participant's part of the unit :meth:unit_began returned token for.