Service Composition#
ServiceGroup coordinates multiple services on one shared SQLAlchemy session so multi-model workflows commit or roll back as a single unit of work.
Defining a ServiceGroup#
Declare a subclass of ServiceGroup with type annotations for each member service:
import asyncio
from sqlalchemy import ForeignKey, String
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
from advanced_alchemy.config import SQLAlchemyAsyncConfig
from advanced_alchemy.repository import SQLAlchemyAsyncRepository
from advanced_alchemy.service import ServiceGroup, SQLAlchemyAsyncRepositoryService
class Base(DeclarativeBase):
pass
class Role(Base):
__tablename__ = "comp_role"
id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
name: Mapped[str] = mapped_column(String(50))
class User(Base):
__tablename__ = "comp_user"
id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
name: Mapped[str] = mapped_column(String(50))
role_id: Mapped[int] = mapped_column(ForeignKey("comp_role.id"))
class RoleRepo(SQLAlchemyAsyncRepository[Role]):
model_type = Role
class UserRepo(SQLAlchemyAsyncRepository[User]):
model_type = User
class RoleService(SQLAlchemyAsyncRepositoryService[Role, RoleRepo]):
repository_type = RoleRepo
class UserService(SQLAlchemyAsyncRepositoryService[User, UserRepo]):
repository_type = UserRepo
class AuthServices(ServiceGroup):
session: AsyncSession
roles: RoleService
users: UserService
async def provision_member(self, role_name: str, user_name: str) -> User:
role = await self.roles.create({"name": role_name})
return await self.users.create({"name": user_name, "role_id": role.id})
async def main() -> None:
config = SQLAlchemyAsyncConfig(connection_string="sqlite+aiosqlite:///:memory:")
async with config.get_engine().begin() as conn:
await conn.run_sync(Base.metadata.create_all)
async with AuthServices.new(config=config) as services:
await services.provision_member("admin", "ada")
await services.session.commit()
assert services.roles.repository.session is services.users.repository.session
await config.get_engine().dispose()
asyncio.run(main())
Every group must declare either asynchronous or synchronous services consistently. Non-service class attributes should use typing.ClassVar. Annotating session refines editor typing without registering a service attribute.
Binding an Existing Session#
When calling code already owns a session, instantiate AuthServices(session) or use AuthServices.new(session=session):
from sqlalchemy import String
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
from advanced_alchemy.config import SQLAlchemySyncConfig
from advanced_alchemy.repository import SQLAlchemySyncRepository
from advanced_alchemy.service import ServiceGroup, SQLAlchemySyncRepositoryService
class SyncBase(DeclarativeBase):
pass
class Account(SyncBase):
__tablename__ = "comp_account"
id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
name: Mapped[str] = mapped_column(String(50))
class AccountRepo(SQLAlchemySyncRepository[Account]):
model_type = Account
class AccountService(SQLAlchemySyncRepositoryService[Account, AccountRepo]):
repository_type = AccountRepo
class BillingServices(ServiceGroup):
accounts: AccountService
sync_config = SQLAlchemySyncConfig(connection_string="sqlite:///:memory:")
with sync_config.get_engine().begin() as conn:
SyncBase.metadata.create_all(conn)
with sync_config.get_session() as session:
billing = BillingServices(session)
billing.accounts.create({"name": "acme"}, auto_commit=True)
assert billing.accounts.repository.session is billing.session
sync_config.get_engine().dispose()
Managed Member Lifetimes#
Group.new(...) enters custom member .new() contexts and nested groups on the same session. Group options are forwarded when the factory accepts them, including explicit False values. Members close in reverse acquisition order; acquisition failures and cancellation reach previously entered contexts before propagating.
Direct Group(session, ...) construction calls member constructors only. Use .new() when members require managed setup or cleanup. A supplied session remains owned by the caller. Group acquisition shares a session but does not commit it automatically; commit explicitly or configure the session owner to manage transactions.
Litestar Integration#
Pass a ServiceGroup subclass to create_service_dependencies() or create_service_provider(), with optional per-attribute filters={attr_name: FilterConfig(...)}:
from litestar import Controller, get
from litestar.di import NamedDependency
from litestar.params import SkipValidation
from advanced_alchemy.extensions.litestar.providers import FilterConfig, create_service_dependencies
from advanced_alchemy.filters import FilterTypes
class AuthController(Controller):
path = "/auth"
dependencies = create_service_dependencies(
AuthServices,
key="auth",
filters={"roles": FilterConfig(search="name"), "users": FilterConfig(search="name")},
)
@get("/")
async def search(
self,
auth: AuthServices,
roles_filters: NamedDependency[SkipValidation[list[FilterTypes]]],
users_filters: NamedDependency[SkipValidation[list[FilterTypes]]],
) -> dict[str, int]:
return {
"roles": await auth.roles.count(*roles_filters),
"users": await auth.users.count(*users_filters),
}
FastAPI Integration#
Pass any ServiceGroup subclass directly to provide_service():
from typing import Annotated
from fastapi import Depends, FastAPI
from advanced_alchemy.extensions.fastapi import AdvancedAlchemy, SQLAlchemyAsyncConfig
fastapi_app = FastAPI()
async_cfg = SQLAlchemyAsyncConfig(connection_string="sqlite+aiosqlite:///:memory:", commit_mode="autocommit")
alchemy = AdvancedAlchemy(config=async_cfg, app=fastapi_app)
AuthDep = Annotated[AuthServices, Depends(alchemy.provide_service(AuthServices))]
@fastapi_app.get("/users/count")
async def user_count(auth: AuthDep) -> int:
return await auth.users.count()