AbstractCommandHandler and AbstractQueryHandler Reference

Handlers are where your application logic lives. AbstractCommandHandler processes a single type of Command and optionally returns a result; AbstractQueryHandler reads data and returns a typed result without causing side effects. Both are abstract, generic classes — you parameterise them with the concrete message type and expected return type, and the type system guarantees your handle method matches the bus’s expectations.

from hexcore.domain.cqrs.handlers import AbstractCommandHandler, AbstractQueryHandler

`AbstractCommandHandler`

class AbstractCommandHandler(ABC, Generic[TCommand, TCommandResult]):
    ...

Type parameters

TCommand

TypeVar[Command]

The specific Command subclass this handler processes. Must be bound to Command.

TCommandResult

TypeVar

The return type of handle(). Use None for fire-and-forget commands that produce no result.

Abstract method

`handle`

@abstractmethod
async def handle(self, command: TCommand) -> TCommandResult

Executes the business logic for the given command. Called by the command bus after all middleware in the pipeline has run.

command

TCommand

required

The command instance dispatched by the bus. Guaranteed to be of the handler’s declared TCommand type.

result

TCommandResult

The result of executing the command. Returns None for fire-and-forget commands.

`AbstractQueryHandler`

class AbstractQueryHandler(ABC, Generic[TQuery, TResult]):
    ...

Type parameters

TQuery

TypeVar[Query[Any]]

The specific Query subclass this handler processes. Must be bound to Query[Any].

TResult

TypeVar

The type of data returned by handle(). Should match the TResult generic parameter on the corresponding Query subclass.

Abstract method

`handle`

@abstractmethod
async def handle(self, query: TQuery) -> TResult

Executes the read operation for the given query and returns the result. Must be side-effect free.

query

TQuery

required

The query instance dispatched by the bus.

result

TResult

The query result — a DTO, a list, a primitive value, or any other type declared by TResult.

Backward-compatibility aliases

ICommandHandler = AbstractCommandHandler
IQueryHandler = AbstractQueryHandler

These aliases are importable from the same module and are fully equivalent to their Abstract* counterparts. Existing code that imports ICommandHandler or IQueryHandler continues to work without modification.

Usage examples

from uuid import UUID
from hexcore.domain.cqrs.handlers import AbstractCommandHandler
from hexcore.domain.cqrs.commands import Command
from myapp.dto import UserDTO
from myapp.domain.entities import User

class CreateUserCommand(Command):
    email: str
    name: str

class CreateUserHandler(AbstractCommandHandler[CreateUserCommand, UserDTO]):
    def __init__(self, uow):
        self._uow = uow

    async def handle(self, command: CreateUserCommand) -> UserDTO:
        async with self._uow as uow:
            user = User.create(email=command.email, name=command.name)
            uow.collect_entity(user)
            saved = await uow.users.save(user)
            await uow.commit()
            await uow.dispatch_events()
            return UserDTO.model_validate(saved)

A handler class must be registered with a HandlerRegistry before the bus can resolve and invoke it. See the HandlerRegistry reference for registration patterns.

Domain

CQRS

Infrastructure

AbstractCommandHandler and AbstractQueryHandler Reference