xtr-orm 1.5.0__py3-none-any.whl

xtr_orm/__init__.py

@@ -0,0 +1,51 @@
+"""Databases for async applications: engines, sessions and versioned schema migrations.
+
+A :class:`~xtr_orm.migrations.Migrator` runs one database's revisions, a
+:class:`~xtr_orm.database.DatabaseManager` creates and drops the database
+itself, and a :class:`ConnectionRegistry` names every connection an
+application has. The bundle in :mod:`xtr_orm.bundle` builds all of them, and
+the engines and sessions, from one configuration.
+"""
+
+from __future__ import annotations
+
+from .connection_registry import DEFAULT_CONNECTION, ConnectionRegistry
+from .database import DatabaseManager
+from .exception import (
+    InvalidArgumentError,
+    MigrationError,
+    OrmError,
+    SessionUnavailableError,
+    UnknownConnectionError,
+    UnsupportedDatabaseError,
+)
+from .migrations import (
+    AvailableMigration,
+    Direction,
+    ExecutedMigration,
+    ExecutionResult,
+    MigrationPlan,
+    MigrationsConfig,
+    MigrationStatus,
+    Migrator,
+)
+
+__all__ = [
+    "DEFAULT_CONNECTION",
+    "AvailableMigration",
+    "ConnectionRegistry",
+    "DatabaseManager",
+    "Direction",
+    "ExecutedMigration",
+    "ExecutionResult",
+    "InvalidArgumentError",
+    "MigrationError",
+    "MigrationPlan",
+    "MigrationStatus",
+    "MigrationsConfig",
+    "Migrator",
+    "OrmError",
+    "SessionUnavailableError",
+    "UnknownConnectionError",
+    "UnsupportedDatabaseError",
+]

xtr_orm/bundle/__init__.py

@@ -0,0 +1,11 @@
+"""The xtr-dependency-injection bundle for xtr-orm."""
+
+from __future__ import annotations
+
+from xtr_orm.migrations import MigrationsConfig
+
+from .connection_config import ConnectionConfig
+from .orm_bundle import ORM_CHANNEL, OrmBundle
+from .orm_config import OrmConfig
+
+__all__ = ["ORM_CHANNEL", "ConnectionConfig", "MigrationsConfig", "OrmBundle", "OrmConfig"]

xtr_orm/bundle/connection_config.py

@@ -0,0 +1,250 @@
+"""How one database connection is built: its URL, engine, sessions and migrations."""
+
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Final
+
+from advanced_alchemy.config import AsyncSessionConfig, EngineConfig, SQLAlchemyAsyncConfig
+from sqlalchemy import MetaData, make_url
+
+from xtr_orm.exception import InvalidArgumentError
+from xtr_orm.migrations import MigrationsConfig
+
+__all__ = ["ConnectionConfig"]
+
+_SET_BY_THE_BUNDLE: Final = frozenset(
+    {
+        "connection_string",
+        "engine_config",
+        "session_config",
+        "bind_key",
+        "metadata",
+        "engine_instance",
+        "session_maker",
+        "alembic_config",
+        "create_engine_callable",
+        "session_maker_class",
+        "routing_config",
+    },
+)
+"""Options of the database layer's own configuration that other fields here already set."""
+
+
+_NOTHING: Final[frozenset[str]] = frozenset()
+
+
+def _flag(value: str) -> bool:
+    lowered = value.strip().lower()
+    if lowered in {"1", "true", "yes", "on"}:
+        return True
+    if lowered in {"0", "false", "no", "off"}:
+        return False
+    raise ValueError("a flag: true or false")
+
+
+def _echo(value: str) -> bool | str:
+    return "debug" if value.strip().lower() == "debug" else _flag(value)
+
+
+def _number(value: str) -> int:
+    try:
+        return int(value)
+    except ValueError:
+        raise ValueError("a whole number") from None
+
+
+def _seconds(value: str) -> float:
+    try:
+        return float(value)
+    except ValueError:
+        raise ValueError("a number") from None
+
+
+def _text(value: str) -> str:
+    return value
+
+
+_ENGINE_URL_OPTIONS: Final[dict[str, Callable[[str], object]]] = {
+    "echo": _echo,
+    "echo_pool": _echo,
+    "enable_from_linting": _flag,
+    "hide_parameters": _flag,
+    "insertmanyvalues_page_size": _number,
+    "isolation_level": _text,
+    "label_length": _number,
+    "logging_name": _text,
+    "max_identifier_length": _number,
+    "max_overflow": _number,
+    "paramstyle": _text,
+    "pool_logging_name": _text,
+    "pool_pre_ping": _flag,
+    "pool_recycle": _number,
+    "pool_size": _number,
+    "pool_timeout": _seconds,
+    "pool_use_lifo": _flag,
+    "query_cache_size": _number,
+    "use_insertmanyvalues": _flag,
+}
+"""Engine options a URL's query may carry, and how each is read."""
+
+_SESSION_URL_OPTIONS: Final[dict[str, Callable[[str], object]]] = {
+    "autobegin": _flag,
+    "autoflush": _flag,
+    "expire_on_commit": _flag,
+    "join_transaction_mode": _text,
+    "twophase": _flag,
+}
+"""Session options a URL's query may carry, and how each is read."""
+
+
+def _no_options() -> dict[str, object]:
+    return {}
+
+
+def _no_replicas() -> dict[str, str]:
+    return {}
+
+
+@dataclass(frozen=True, slots=True)
+class ConnectionConfig:
+    """One database: where it is, its replicas, its engine and sessions, and its migrations.
+
+    ```python
+    ConnectionConfig(
+        url=env("DATABASE_URL"),
+        replicas={"replica1": env("DATABASE_REPLICA_URL")},
+        engine_options={"pool_size": 10, "pool_pre_ping": True},
+        session_options={"expire_on_commit": False},
+        migrations=MigrationsConfig(render_as_batch=True),
+    )
+    ```
+
+    Options may ride on the URL too, which is how one environment variable
+    configures a whole connection —
+    ``postgresql+asyncpg://app@db/shop?pool_size=20&expire_on_commit=false&ssl=require``.
+    An engine or session option, or ``keep_replica``, is taken out of the
+    URL and merged over the one configured here: the URL wins. Every other
+    option stays on the URL for the driver.
+
+    Attributes:
+        url: The database URL, with an async driver —
+            ``postgresql+asyncpg://…``, ``sqlite+aiosqlite:///…``,
+            ``mysql+asyncmy://…``. Read from ``DATABASE_URL`` by default, when
+            the connection is first used.
+        engine_options: Engine options — ``echo``, ``pool_size``,
+            ``max_overflow``, ``pool_pre_ping``, ``pool_recycle``,
+            ``isolation_level``, ``connect_args``, ``execution_options`` and
+            every other the engine takes.
+        session_options: Session options — ``expire_on_commit``,
+            ``autoflush``, ``info`` and the rest.
+        alchemy_options: Any other option of the database layer's own
+            configuration, such as ``enable_touch_updated_timestamp_listener``.
+        replicas: Read replicas of the database :attr:`url` names, each a URL
+            by name. With any, a session reads from a replica picked at
+            random, and goes to the primary — :attr:`url` — for a write, a
+            transaction's statements, and every read after them. Migrations,
+            and the create and drop commands, always use the primary.
+        keep_replica: Go back to the replicas once a session commits, rather
+            than read from the primary for the rest of its unit of work.
+        bind_key: Which table definitions belong to this database when models
+            declare several; ``None`` for the default ones.
+        metadata: The table definitions a migration diff compares the
+            database with; those registered for :attr:`bind_key` when
+            ``None``.
+        migrations: Where the revisions are and how they are recorded;
+            ``migrations`` in the project directory for the default
+            connection, ``migrations/<name>`` for any other, when ``None``.
+    """
+
+    url: str = "%env(DATABASE_URL)%"
+    engine_options: Mapping[str, object] = field(default_factory=_no_options)
+    session_options: Mapping[str, object] = field(default_factory=_no_options)
+    alchemy_options: Mapping[str, object] = field(default_factory=_no_options)
+    replicas: Mapping[str, str] = field(default_factory=_no_replicas)
+    keep_replica: bool = False
+    bind_key: str | None = None
+    metadata: MetaData | Sequence[MetaData] | None = None
+    migrations: MigrationsConfig | None = None
+
+    def __post_init__(self) -> None:
+        """Refuse an empty URL, or an option the engine, a session or the layer does not take.
+
+        Raises:
+            InvalidArgumentError: When the configuration cannot be used.
+        """
+        # Compared, not tested for truth: the URL may be an environment placeholder,
+        # which refuses to decide anything before the variable is read.
+        if self.url == "":
+            raise InvalidArgumentError("A connection's URL must not be empty.")
+        for name, url in self.replicas.items():
+            if not isinstance(name, str) or not name:  # pyright: ignore[reportUnnecessaryIsInstance] -- configs are written by hand; the annotation is not enforced
+                raise InvalidArgumentError(f"A replica needs a non-empty name, got {name!r}.")
+            if url == "":
+                raise InvalidArgumentError(f'The "{name}" replica\'s URL must not be empty.')
+        _check_options("engine", EngineConfig, self.engine_options)
+        _check_options("session", AsyncSessionConfig, self.session_options)
+        _check_options(
+            "alchemy", SQLAlchemyAsyncConfig, self.alchemy_options, exclude=_SET_BY_THE_BUNDLE
+        )
+
+    def with_url_options(self) -> ConnectionConfig:
+        """Return this connection with the options its URL carries merged into it.
+
+        Called once the URL is read — an environment variable is not until a
+        service needs it — so a mistake in the URL fails that service.
+
+        Raises:
+            InvalidArgumentError: When an option's value cannot be read.
+        """
+        url = make_url(self.url)
+        driver: dict[str, str | tuple[str, ...]] = {}
+        engine = dict(self.engine_options)
+        session = dict(self.session_options)
+        keep_replica = self.keep_replica
+        for name, given in url.query.items():
+            value = given if isinstance(given, str) else given[-1]
+            if name in _ENGINE_URL_OPTIONS:
+                engine[name] = _read(name, value, _ENGINE_URL_OPTIONS[name])
+            elif name in _SESSION_URL_OPTIONS:
+                session[name] = _read(name, value, _SESSION_URL_OPTIONS[name])
+            elif name == "keep_replica":
+                keep_replica = bool(_read(name, value, _flag))
+            else:
+                driver[name] = given
+        if len(driver) == len(url.query):
+            return self
+        return dataclasses.replace(
+            self,
+            url=url.set(query=driver).render_as_string(hide_password=False),
+            engine_options=engine,
+            session_options=session,
+            keep_replica=keep_replica,
+        )
+
+
+def _read(name: str, value: str, reader: Callable[[str], object]) -> object:
+    try:
+        return reader(value)
+    except ValueError as error:
+        raise InvalidArgumentError(
+            f'The URL option "{name}" must be {error}, got "{value}".',
+        ) from error
+
+
+def _check_options(
+    kind: str,
+    target: type[EngineConfig | AsyncSessionConfig | SQLAlchemyAsyncConfig],
+    options: Mapping[str, object],
+    *,
+    exclude: frozenset[str] = _NOTHING,
+) -> None:
+    known = {each.name for each in dataclasses.fields(target) if each.init} - exclude
+    for name in options:
+        if name not in known:
+            listed = ", ".join(sorted(known))
+            raise InvalidArgumentError(
+                f'Unknown {kind} option "{name}"; the {kind} options are: {listed}.',
+            )

xtr_orm/bundle/orm_bundle.py

@@ -0,0 +1,346 @@
+"""The xtr-orm bundle: an engine, sessions and a migrator per configured connection.
+
+An application listing :class:`OrmBundle` gets, for every connection of its
+:class:`OrmConfig`, each qualified by the connection's name:
+
+- the database layer's :class:`~advanced_alchemy.config.SQLAlchemyAsyncConfig`,
+  for its repositories and services;
+- an :class:`~sqlalchemy.ext.asyncio.AsyncEngine` on the primary database;
+- an ``async_sessionmaker[AsyncSession]`` — or, for a connection with
+  replicas, a :class:`~advanced_alchemy.routing.RoutingAsyncSessionMaker`
+  sending reads to them and writes to the primary;
+- an :class:`~sqlalchemy.ext.asyncio.AsyncSession` per unit of work — a
+  request, a message, a command — closed when the unit ends;
+- a :class:`~xtr_orm.migrations.Migrator` and a
+  :class:`~xtr_orm.database.DatabaseManager`, both on the primary;
+
+and the default connection's without a qualifier too. Every engine is
+disposed when the container closes. When the console bundle is active, the
+``orm:*`` commands are registered; when the messenger bundle is, the
+``orm_transaction``, ``orm_close_connection`` and
+``orm_open_transaction_logger`` middleware are, for a bus to list; when the
+logging bundle is, an ``orm`` channel is added and every migrator logs there.
+
+Nothing connects until a service is first used, and a URL given as
+``env(...)`` is read only then.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable
+from typing import Final, TypeVar, cast, final
+
+from advanced_alchemy.base import metadata_registry
+from advanced_alchemy.config import AsyncSessionConfig, EngineConfig, SQLAlchemyAsyncConfig
+from advanced_alchemy.config.routing import EngineConfig as ReplicaEngine
+from advanced_alchemy.config.routing import RoutingConfig, RoutingStrategy
+from advanced_alchemy.routing import RoutingAsyncSessionMaker, stick_to_primary_var
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker
+from typing_extensions import override
+from xtr_dependency_injection import (
+    Bundle,
+    ContainerBuilder,
+    ServiceConfigurator,
+    as_bundle,
+    bundle_active,
+    current_unit_of_work,
+    named_factory,
+    optional_service,
+    required_bundle,
+)
+from xtr_logging_contracts import LoggerInterface
+from xtr_service_contracts import ContainerInterface
+
+from xtr_orm.connection_registry import ConnectionRegistry
+from xtr_orm.database import DatabaseManager
+from xtr_orm.exception import SessionUnavailableError
+from xtr_orm.migrations import MigrationsConfig, Migrator
+
+from .connection_config import ConnectionConfig
+from .orm_config import OrmConfig
+
+__all__ = ["ORM_CHANNEL", "OrmBundle"]
+
+_T = TypeVar("_T")
+
+ORM_CHANNEL: Final = "orm"
+"""The logging channel migrators write to."""
+
+_PER_CONNECTION: Final[tuple[type, ...]] = (
+    SQLAlchemyAsyncConfig,
+    AsyncEngine,
+    AsyncSession,
+    Migrator,
+    DatabaseManager,
+)
+
+
+@final
+@required_bundle("xtr_logging.bundle:LoggingBundle", ignore_on_invalid=True)
+@required_bundle("xtr_console.bundle:ConsoleBundle", ignore_on_invalid=True)
+@as_bundle("orm", config=OrmConfig)
+class OrmBundle(Bundle[OrmConfig]):
+    """Turns an :class:`OrmConfig` into an engine, sessions and a migrator per connection."""
+
+    @override
+    def prepend_extension(self, builder: ContainerBuilder) -> None:
+        """When ``logging`` is active, add the ``orm`` channel to its config."""
+        if not bundle_active(builder, "logging"):
+            return
+        # Logging is an optional peer, importable only once it is active.
+        from xtr_logging.bundle import LoggingConfig  # noqa: PLC0415
+
+        def add_orm_channel(config: LoggingConfig) -> LoggingConfig:
+            return config.with_channels(ORM_CHANNEL)
+
+        builder.prepend_extension_config(LoggingConfig, add_orm_channel)
+
+    @override
+    def load_extension(
+        self,
+        config: OrmConfig,
+        services: ServiceConfigurator,
+        builder: ContainerBuilder,
+    ) -> None:
+        """Register every connection's services under its name, the registry, the commands."""
+        for name, spec in config.connections.items():
+            maker_type: type = (
+                RoutingAsyncSessionMaker if spec.replicas else async_sessionmaker[AsyncSession]
+            )
+            factories = (
+                (_alchemy_factory(name), "alchemy"),
+                (_engine_factory(name), "engine"),
+                (
+                    _routing_maker_factory(name) if spec.replicas else _session_maker_factory(name),
+                    "session_maker",
+                ),
+                (_migrator_factory(name), "migrator"),
+                (_database_factory(name), "database"),
+            )
+            for factory, kind in factories:
+                _ = services.set(named_factory(factory, f"orm_{kind}_{name}"), qualifier=name)
+            _ = services.set(
+                named_factory(_session_factory(name), f"orm_session_{name}"),
+                qualifier=name,
+                lifetime="scoped",
+            )
+            if name == config.default_connection:
+                for service in (*_PER_CONNECTION, maker_type):
+                    services.alias(service, service, target_qualifier=name)
+
+        _ = services.set(_connection_registry)
+
+        if bundle_active(builder, "console"):
+            services.load("xtr_orm.command")
+        if bundle_active(builder, "messenger"):
+            services.load("xtr_orm.messenger")
+
+
+def _alchemy_factory(
+    name: str,
+) -> Callable[[OrmConfig], AsyncIterator[SQLAlchemyAsyncConfig]]:
+    """Build the factory of the connection ``name``'s database layer configuration.
+
+    It owns every engine of the connection — the primary's, and each
+    replica's — and disposes them when the container closes. It injects the
+    configuration rather than closing over it: the container hands it a copy
+    with every environment placeholder resolved.
+    """
+
+    async def alchemy(config: OrmConfig) -> AsyncIterator[SQLAlchemyAsyncConfig]:
+        spec = config.connections[name].with_url_options()
+        # The options are forwarded by name, each checked against the target's
+        # fields by ConnectionConfig; their values are the application's.
+        engine = cast("Callable[..., EngineConfig]", EngineConfig)(**spec.engine_options)
+        session = cast("Callable[..., AsyncSessionConfig]", AsyncSessionConfig)(
+            **spec.session_options
+        )
+        built = cast("Callable[..., SQLAlchemyAsyncConfig]", SQLAlchemyAsyncConfig)(
+            # With replicas, the primary is given through the routing instead.
+            connection_string=None if spec.replicas else spec.url,
+            routing_config=_routing(spec) if spec.replicas else None,
+            engine_config=engine,
+            session_config=session,
+            bind_key=spec.bind_key,
+            **spec.alchemy_options,
+        )
+        routing_maker: RoutingAsyncSessionMaker | None = None
+        if spec.replicas:
+            routing_maker = cast("RoutingAsyncSessionMaker", built.create_session_maker())
+            # One pool on the primary: the routing's, which migrations use too.
+            built.engine_instance = routing_maker.primary_engine
+        try:
+            yield built
+        finally:
+            if routing_maker is not None:
+                await routing_maker.close_all()
+            elif built.engine_instance is not None:
+                await built.engine_instance.dispose()
+
+    return alchemy
+
+
+def _routing(spec: ConnectionConfig) -> RoutingConfig:
+    """Map the connection's replicas onto the database layer's read/write routing.
+
+    Reads go to a replica picked at random; a write, a transaction and every
+    read after them go to the primary, until a commit when ``keep_replica``.
+    Built afresh for each container: that configuration completes itself when
+    built.
+    """
+    return RoutingConfig(
+        primary_connection_string=spec.url,
+        read_replicas=[
+            ReplicaEngine(connection_string=url, name=replica)
+            for replica, url in spec.replicas.items()
+        ],
+        routing_strategy=RoutingStrategy.RANDOM,
+        sticky_after_write=True,
+        reset_stickiness_on_commit=spec.keep_replica,
+    )
+
+
+def _engine_factory(name: str) -> Callable[[ContainerInterface], Awaitable[AsyncEngine]]:
+    """Build the factory of the connection ``name``'s engine, on its primary."""
+
+    async def engine(container: ContainerInterface) -> AsyncEngine:
+        return (await container.get(SQLAlchemyAsyncConfig, name)).get_engine()
+
+    return engine
+
+
+def _session_maker_factory(
+    name: str,
+) -> Callable[[ContainerInterface], Awaitable[async_sessionmaker[AsyncSession]]]:
+    """Build the factory of the connection ``name``'s session maker, on its engine."""
+
+    async def session_maker(container: ContainerInterface) -> async_sessionmaker[AsyncSession]:
+        alchemy = await container.get(SQLAlchemyAsyncConfig, name)
+        return cast("async_sessionmaker[AsyncSession]", alchemy.create_session_maker())
+
+    return session_maker
+
+
+def _routing_maker_factory(
+    name: str,
+) -> Callable[[ContainerInterface], Awaitable[RoutingAsyncSessionMaker]]:
+    """Build the factory of the connection ``name``'s session maker, routing to its replicas."""
+
+    async def routing_session_maker(container: ContainerInterface) -> RoutingAsyncSessionMaker:
+        alchemy = await container.get(SQLAlchemyAsyncConfig, name)
+        return cast("RoutingAsyncSessionMaker", alchemy.create_session_maker())
+
+    return routing_session_maker
+
+
+def _session_factory(
+    name: str,
+) -> Callable[[OrmConfig, ContainerInterface], AsyncIterator[AsyncSession]]:
+    """Build the factory of the connection ``name``'s session, closed when its unit ends.
+
+    Closing rolls back what was not committed: committing is the unit's job.
+    With replicas, a unit starts reading from them whatever the unit before
+    it wrote: sticking to the primary after a write is one unit's state.
+    """
+
+    async def session(
+        config: OrmConfig, container: ContainerInterface
+    ) -> AsyncIterator[AsyncSession]:
+        routed = bool(config.connections[name].replicas)
+        maker = (await container.get(SQLAlchemyAsyncConfig, name)).create_session_maker()
+        if routed:
+            _ = stick_to_primary_var.set(False)
+        try:
+            async with maker() as opened:
+                yield opened
+        finally:
+            if routed:
+                _ = stick_to_primary_var.set(False)
+
+    return session
+
+
+def _migrator_factory(name: str) -> Callable[[OrmConfig, ContainerInterface], Awaitable[Migrator]]:
+    """Build the factory of the connection ``name``'s migrator, logging to ``orm`` when it can."""
+
+    async def migrator(config: OrmConfig, container: ContainerInterface) -> Migrator:
+        spec = config.connections[name].with_url_options()
+        metadata = (
+            spec.metadata if spec.metadata is not None else metadata_registry.get(spec.bind_key)
+        )
+        built = Migrator(
+            await container.get(AsyncEngine, name),
+            spec.migrations or MigrationsConfig(),
+            metadata,
+            name=name,
+        )
+        logger = await optional_service(container, LoggerInterface, ORM_CHANNEL)
+        if logger is not None:
+            built.set_logger(logger)
+        return built
+
+    return migrator
+
+
+def _database_factory(name: str) -> Callable[[OrmConfig], DatabaseManager]:
+    """Build the factory of the connection ``name``'s database manager."""
+
+    def database(config: OrmConfig) -> DatabaseManager:
+        spec: ConnectionConfig = config.connections[name].with_url_options()
+        connect_args = spec.engine_options.get("connect_args")
+        return DatabaseManager(
+            spec.url,
+            connect_args=connect_args if isinstance(connect_args, dict) else None,  # pyright: ignore[reportUnknownArgumentType] -- an option mapping, read as given
+        )
+
+    return database
+
+
+def _connection_registry(config: OrmConfig, container: ContainerInterface) -> ConnectionRegistry:
+    """Name every connection for the commands and middleware, each piece built only when needed.
+
+    A connection's session is the one of the unit of work under way, and
+    closing it disposes every engine it has — its replicas' too.
+    """
+    registry = ConnectionRegistry(config.default_connection)
+    for name, spec in config.connections.items():
+        registry.register(
+            name,
+            engine=_provider(container, AsyncEngine, name),
+            migrator=_provider(container, Migrator, name),
+            database=_provider(container, DatabaseManager, name),
+            session=_unit_session(name),
+            close=_closer(container, name, routed=bool(spec.replicas)),
+        )
+    return registry
+
+
+def _unit_session(name: str) -> Callable[[], Awaitable[AsyncSession]]:
+    async def session() -> AsyncSession:
+        unit = current_unit_of_work()
+        if unit is None:
+            raise SessionUnavailableError(name, "no unit of work is under way")
+        return await unit.get(AsyncSession, name)
+
+    return session
+
+
+def _closer(
+    container: ContainerInterface, name: str, *, routed: bool
+) -> Callable[[], Awaitable[None]]:
+    async def close() -> None:
+        if routed:
+            await (await container.get(RoutingAsyncSessionMaker, name)).close_all()
+        else:
+            await (await container.get(AsyncEngine, name)).dispose()
+
+    return close
+
+
+def _provider(
+    container: ContainerInterface, service: type[_T], name: str
+) -> Callable[[], Awaitable[_T]]:
+    async def provide() -> _T:
+        return await container.get(service, name)
+
+    return provide