Execute Commands on Aggregates
AggregateRepository.execute and TenantAwareRepository.execute collapse the standard load-decide-save cycle into a single async call for both:
- Command-driven aggregates (
DeciderAggregateor any aggregate definingexecute(command)/apply_command(command)), and - Imperative (
AggregateRoot) and declarative (DeclarativeAggregate) aggregates via callable commands (lambda order: order.ship("TRACK-123")).
Instead of manually calling load_or_create, invoking aggregate.execute(command) or a mutating aggregate method, and awaiting save(aggregate), call await repo.execute(aggregate_id, command).
For wiring AggregateRepository and inferring aggregate_type, see Wire an AggregateRepository. For choosing between imperative, declarative, and decider aggregate styles, see Aggregate Styles and The Decider Pattern.
Single-round-trip command execution with `AggregateRepository.execute`
Define your state, commands (DomainCommand), events (DomainEvent), and a DeciderAggregate subclass:
from uuid import UUID, uuid4
from pydantic import BaseModel
from eventsource import (
AggregateRepository,
CommandRejectedError,
DeciderAggregate,
DomainCommand,
DomainEvent,
InMemoryEventStore,
)
class AccountState(BaseModel):
owner: str = ""
balance: float = 0.0
is_open: bool = False
class OpenAccount(DomainCommand):
account_id: UUID
owner: str
class DepositMoney(DomainCommand):
account_id: UUID
amount: float
class AccountOpened(DomainEvent):
aggregate_type: str = "Account"
owner: str
class MoneyDeposited(DomainEvent):
aggregate_type: str = "Account"
amount: float
class Account(DeciderAggregate[AccountState, OpenAccount | DepositMoney]):
aggregate_type = "Account"
@staticmethod
def initial_state() -> AccountState:
return AccountState()
@staticmethod
def decide(
command: OpenAccount | DepositMoney,
state: AccountState,
) -> list[DomainEvent]:
match command:
case OpenAccount(account_id=aid, owner=owner):
if state.is_open:
raise CommandRejectedError("account already open")
return [AccountOpened(aggregate_id=aid, owner=owner)]
case DepositMoney(account_id=aid, amount=amount):
if not state.is_open:
raise CommandRejectedError("account not open")
return [MoneyDeposited(aggregate_id=aid, amount=amount)]
@staticmethod
def evolve(state: AccountState, event: DomainEvent) -> AccountState:
match event:
case AccountOpened(owner=owner):
return state.model_copy(update={"owner": owner, "is_open": True})
case MoneyDeposited(amount=amount):
return state.model_copy(update={"balance": state.balance + amount})
case _:
return state
Execute commands directly through the repository:
async def handle_commands() -> None:
async with InMemoryEventStore() as store:
repo = AggregateRepository(event_store=store, aggregate_factory=Account)
account_id = uuid4()
# Creates the aggregate if missing, executes OpenAccount, and saves
account = await repo.execute(
account_id,
OpenAccount(account_id=account_id, owner="alice"),
)
assert account.state.is_open is True
assert account.version == 1
# Loads existing aggregate at version 1, executes DepositMoney, and saves
account = await repo.execute(
account_id,
DepositMoney(account_id=account_id, amount=75.0),
)
assert account.state.balance == 75.0
assert account.version == 2
Callable commands for `AggregateRoot` and `DeclarativeAggregate`
When working with imperative (AggregateRoot) or declarative (DeclarativeAggregate) aggregates that expose domain methods rather than a single execute(command) dispatcher, pass a callable Callable[[TAggregate], Any] (such as lambda order: order.ship("TRACK-123")) to repo.execute():
from uuid import UUID, uuid4
from pydantic import BaseModel
from eventsource import (
AggregateRepository,
DeclarativeAggregate,
DomainEvent,
InMemoryEventStore,
handles,
)
class OrderState(BaseModel):
customer_id: UUID | None = None
tracking_number: str | None = None
status: str = "draft"
class OrderCreated(DomainEvent):
aggregate_type: str = "Order"
customer_id: UUID
class OrderShipped(DomainEvent):
aggregate_type: str = "Order"
tracking_number: str
class OrderAggregate(DeclarativeAggregate[OrderState]):
aggregate_type = "Order"
def _get_initial_state(self) -> OrderState:
return OrderState()
def create(self, customer_id: UUID) -> None:
self.apply_event(
OrderCreated(
aggregate_id=self.aggregate_id,
aggregate_version=self.get_next_version(),
customer_id=customer_id,
)
)
def ship(self, tracking_number: str) -> None:
self.apply_event(
OrderShipped(
aggregate_id=self.aggregate_id,
aggregate_version=self.get_next_version(),
tracking_number=tracking_number,
)
)
@handles(OrderCreated)
def _on_created(self, event: OrderCreated) -> None:
self._state = self._state.model_copy(
update={"customer_id": event.customer_id, "status": "created"}
)
@handles(OrderShipped)
def _on_shipped(self, event: OrderShipped) -> None:
self._state = self._state.model_copy(
update={"tracking_number": event.tracking_number, "status": "shipped"}
)
async def handle_declarative_commands() -> None:
async with InMemoryEventStore() as store:
repo = AggregateRepository(event_store=store, aggregate_factory=OrderAggregate)
order_id = uuid4()
customer_id = uuid4()
# Creates the aggregate if missing, invokes the callable, and saves
order = await repo.execute(
order_id,
lambda order: order.create(customer_id=customer_id),
)
assert order.state.status == "created"
assert order.version == 1
# Loads existing aggregate, invokes order.ship(...), and saves
order = await repo.execute(
order_id,
lambda order: order.ship("TRACK-123"),
create_if_missing=False,
)
assert order.state.tracking_number == "TRACK-123"
assert order.version == 2
Controlling creation with `create_if_missing`
By default, execute() calls load_or_create(aggregate_id) (create_if_missing=True), so commands that initialize a new stream work without a separate creation method.
When executing a command that must target an existing aggregate, pass create_if_missing=False. The repository uses load(aggregate_id) and raises AggregateNotFoundError before running the command if the stream does not exist:
from eventsource import AggregateNotFoundError
try:
await repo.execute(
unknown_id,
DepositMoney(account_id=unknown_id, amount=25.0),
create_if_missing=False,
)
except AggregateNotFoundError:
...
Supported aggregate types and command dispatch
execute(aggregate_id, command) dispatches command in two ways:
- Callable commands (
Callable[[TAggregate], Any]): Ifcommandis a callable (and not a class type),execute()invokescommand(aggregate)directly with the loaded or created aggregate instance. This works with anyAggregateRoot,DeclarativeAggregate, orDeciderAggregate. - Command objects: Otherwise,
execute()looks upaggregate.execute(command)first, falling back toaggregate.apply_command(command).DeciderAggregateprovidesexecute(command)out of the box.
If you pass a non-callable command object to an AggregateRoot or DeclarativeAggregate that defines neither execute nor apply_command, execute() raises TypeError:
TypeError: CounterAggregate does not support execute(); pass a callable (e.g.
lambda agg: agg.do_something()) or use an aggregate supporting execute(command)
or apply_command(command), such as DeciderAggregate.
Querying aggregates with `get_or_none` and `exists`
When looking up an aggregate that may not have been created yet, use await repo.get_or_none(aggregate_id) to return TAggregate | None instead of catching AggregateNotFoundError from load(), or await repo.exists(aggregate_id) to check whether its stream has at least one persisted event without replaying history:
async def check_and_load_account(repo: AggregateRepository[Account]) -> None:
account_id = uuid4()
assert await repo.exists(account_id) is False
assert await repo.get_or_none(account_id) is None
await repo.execute(
account_id,
OpenAccount(account_id=account_id, owner="alice"),
)
assert await repo.exists(account_id) is True
account = await repo.get_or_none(account_id)
assert account is not None
assert account.state.owner == "alice"
Batch saving and loading with `save_all` and `load_many`
When a workflow mutates or inspects multiple aggregates of the same type, use await repo.save_all(aggregates) and await repo.load_many(aggregate_ids, , ignore_missing=False) -> dict[UUID, TAggregate]:
- *
await repo.save_all(aggregates)**: accepts either variadic aggregate arguments (await repo.save_all(order1, order2)) or a single iterable of aggregates (await repo.save_all([order1, order2])), persisting each aggregate in sequence viasave(). - *
await repo.load_many(aggregate_ids,, ignore_missing=False) -> dict[UUID, TAggregate]**: loads multiple aggregates by ID and returns a dictionary mapping eachaggregate_id(UUID) to its reconstructedTAggregateinstance. By default (ignore_missing=False), raisesAggregateNotFoundErrorif any requested aggregate stream does not exist; passignore_missing=Trueto omit missing aggregates from the returned mapping.
async def batch_save_and_load_orders(
repo: AggregateRepository[OrderAggregate],
) -> None:
order1_id, order2_id, missing_id = uuid4(), uuid4(), uuid4()
customer_id = uuid4()
order1 = repo.create_new(order1_id)
order1.create(customer_id=customer_id)
order2 = repo.create_new(order2_id)
order2.create(customer_id=customer_id)
order2.ship("TRACK-200")
# Pass variadic arguments or an iterable: await repo.save_all([order1, order2])
await repo.save_all(order1, order2)
# Load multiple aggregates by ID -> dict[UUID, OrderAggregate]
loaded = await repo.load_many([order1_id, order2_id])
assert loaded[order1_id].version == 1
assert loaded[order2_id].state.tracking_number == "TRACK-200"
# Skip non-existent aggregate IDs with ignore_missing=True
partial = await repo.load_many(
[order1_id, missing_id],
ignore_missing=True,
)
assert list(partial.keys()) == [order1_id]
Multi-tenant command execution with `TenantAwareRepository.execute`
TenantAwareRepository exposes the same execute(aggregate_id, command, , create_if_missing=True) (accepting both DeciderAggregate command objects and lambda agg: ... callables), get_or_none(aggregate_id), exists(aggregate_id), save_all(aggregates), and load_many(aggregate_ids, *, ignore_missing=False) -> dict[UUID, TAggregate] methods while enforcing your configured tenant policies:
- When
require_tenant_context=True,execute(),get_or_none(),exists(),save_all(), andload_many()verify that an activetenant_scopeis set before accessing the underlying repository. - When
validate_on_save=True(the default),execute()andsave_all()validate that every uncommitted event on each aggregate matches the active tenant context before delegating tosave(), raisingTenantMismatchErroron a mismatch. - A command whose
tenant_iddiffers from the active tenant scope makesexecute()raiseTenantMismatchErrorbefore any event is applied. When no tenant scope is active, the command'stenant_idis used as is.
from uuid import UUID, uuid4
from eventsource import (
AggregateRepository,
TenantAwareRepository,
TenantDomainEvent,
tenant_scope,
)
class TenantAccountOpened(TenantDomainEvent):
aggregate_type: str = "TenantAccount"
owner: str
class OpenTenantAccount(DomainCommand):
account_id: UUID
owner: str
class TenantAccount(DeciderAggregate[AccountState, OpenTenantAccount]):
aggregate_type = "TenantAccount"
@staticmethod
def initial_state() -> AccountState:
return AccountState()
@staticmethod
def decide(command: OpenTenantAccount, state: AccountState) -> list[DomainEvent]:
return [
TenantAccountOpened.with_tenant_context(
aggregate_id=command.account_id,
owner=command.owner,
)
]
@staticmethod
def evolve(state: AccountState, event: DomainEvent) -> AccountState:
if isinstance(event, TenantAccountOpened):
return state.model_copy(update={"owner": event.owner, "is_open": True})
return state
async def run_tenant_command() -> None:
async with InMemoryEventStore() as store:
base_repo = AggregateRepository(
event_store=store,
aggregate_factory=TenantAccount,
)
tenant_repo = TenantAwareRepository(
base_repo,
require_tenant_context=True,
validate_on_save=True,
)
tenant_id = uuid4()
account_id = uuid4()
second_id = uuid4()
async with tenant_scope(tenant_id):
assert await tenant_repo.exists(account_id) is False
assert await tenant_repo.get_or_none(account_id) is None
account = await tenant_repo.execute(
account_id,
OpenTenantAccount(account_id=account_id, owner="alice"),
)
assert account.version == 1
assert await tenant_repo.exists(account_id) is True
second = TenantAccount(second_id)
second.execute(OpenTenantAccount(account_id=second_id, owner="bob"))
await tenant_repo.save_all(second)
accounts = await tenant_repo.load_many(
[account_id, second_id],
ignore_missing=False,
)
assert accounts[account_id].state.owner == "alice"
assert accounts[second_id].state.owner == "bob"
See Multi-Tenancy for full details on tenant_scope, TenantDomainEvent, and storage-layer read isolation.