python-cqrs 5.0.0__py3-none-any.whl → 5.2.0__py3-none-any.whl

cqrs/__init__.py

@@ -1,3 +1,74 @@
+"""
+python-cqrs.
+
+[AI Instruction]
+Import the library as ``cqrs``. Names listed in ``__all__`` below are the
+stable surface. Commands and queries are both ``cqrs.Request``. Wire a
+request with ``RequestMap.bind``, an event with ``EventMap.bind``, and a
+saga with ``SagaMap.bind``. There is no ``Command``, ``Query``, or
+``CommandBus`` type, and no ``register_handler`` decorator.
+
+Startup is not on this package. Import the submodule:
+
+- ``cqrs.bootstrap.requests.bootstrap`` builds ``RequestMediator``.
+- ``cqrs.bootstrap.requests.bootstrap_streaming`` builds
+  ``StreamingRequestMediator``.
+- ``cqrs.bootstrap.events.bootstrap`` builds ``EventMediator``.
+- ``cqrs.bootstrap.saga.bootstrap`` builds ``SagaMediator``.
+
+Requests and handlers on ``cqrs``: ``Request``, ``DCRequest``, ``Response``,
+``RequestHandler``, ``StreamingRequestHandler``, ``RequestMediator``,
+``StreamingRequestMediator``, ``RequestMap``, ``RequestHandlerFallback``.
+``PydanticRequest`` and ``PydanticResponse`` are lazy and need the
+``pydantic`` extra. A chain of handlers is ``cqrs.handlers.CORRequestHandler``.
+``build_chain`` is ``cqrs.handlers.cor.build_chain``.
+
+Events on ``cqrs``: ``DomainEvent`` for this process, ``NotificationEvent``
+for another service, plus ``EventHandler``, ``EventMap``, ``EventMediator``,
+``EventEmitter``, ``EventHandlerFallback``. Pydantic event classes are lazy
+and need the ``pydantic`` extra.
+
+Sagas on ``cqrs``: ``Saga``, ``SagaStepHandler``, ``SagaStepResult``,
+``SagaMediator``, ``SagaMap``. Import the rest from their modules.
+``SagaContext`` is ``cqrs.saga.models.SagaContext``. A fallback step is
+``cqrs.saga.fallback.Fallback``. Resume a run with
+``cqrs.saga.recovery.recover_saga``. The storage protocol is
+``cqrs.saga.storage.ISagaStorage``. Implementations are
+``cqrs.saga.storage.memory.MemorySagaStorage``,
+``cqrs.saga.storage.sqlalchemy.SqlAlchemySagaStorage`` (extra
+``sqlalchemy``), and ``cqrs.saga.storage.sqlmodel.SqlModelSagaStorage``
+(extra ``sqlmodel``). Those storage classes are not attributes of ``cqrs``.
+
+Outbox on ``cqrs``: ``OutboxedEventRepository``, ``OutboxedEventMap``,
+``EventProducer``, ``EventStatus``. ``SqlAlchemyOutboxedEventRepository``,
+``rebind_outbox_model``, and the dialect types are lazy and need the
+``sqlalchemy`` extra. ``SqlModelOutboxedEventRepository`` is lazy and needs
+the ``sqlmodel`` extra. Codecs on ``cqrs``: ``JsonEventSerializer``,
+``ProtobufEventSerializer`` (extra ``protobuf``).
+
+Brokers are not on ``cqrs``. Kafka is
+``cqrs.adapters.kafka.kafka_producer_factory`` plus
+``cqrs.message_brokers.kafka.KafkaMessageBroker`` (extra ``kafka``). AMQP is
+``cqrs.message_brokers.amqp.AMQPMessageBroker`` (extra ``rabbit``).
+
+Containers: pass one into bootstrap. ``cqrs.DIContainer`` wraps the ``di``
+package, and bootstrap wraps a raw ``di.Container`` itself.
+``cqrs.container.dependency_injector.DependencyInjectorCQRSContainer`` wraps
+dependency-injector. ``cqrs.container.dishka.DishkaCQRSContainer`` needs the
+``dishka`` extra. Scope helpers on ``cqrs`` are ``ScopeStrategy``,
+``bind_scope``, ``enter_scope``, and ``current_container``.
+
+Middleware is ``cqrs.middlewares.Middleware``. Logging is
+``cqrs.middlewares.logging.LoggingMiddleware``; bootstrap adds it when the
+list does not already contain it. A circuit breaker adapter is
+``cqrs.adapters.circuit_breaker.AioBreakerAdapter`` (extra ``aiobreaker``).
+Diagrams on ``cqrs`` are ``CoRMermaid`` and ``SagaMermaid``.
+
+Do not import ``cqrs.dispatcher`` from application code. Mediators call it.
+Optional integrations are extras in ``pyproject.toml``. Reading a lazy name
+without its extra raises ``ImportError``.
+"""
+
 import typing
 
 if typing.TYPE_CHECKING:
@@ -12,6 +83,7 @@ if typing.TYPE_CHECKING:
         SqlAlchemyOutboxedEventRepository,
         rebind_outbox_model,
     )
+    from cqrs.outbox.sqlmodel import SqlModelOutboxedEventRepository
     from cqrs.sqlalchemy_types import (
         Binary16,
         DialectAwareType,
@@ -129,6 +201,7 @@ __all__ = (
     "PydanticResponse",
     "OutboxedEventRepository",
     "SqlAlchemyOutboxedEventRepository",
+    "SqlModelOutboxedEventRepository",
     "EventProducer",
     "EventSerializer",
     "EventCodec",
@@ -187,6 +260,13 @@ _LAZY_SQLALCHEMY = {
     "PayloadBinary": ("cqrs.sqlalchemy_types", "PayloadBinary"),
 }
 
+_LAZY_SQLMODEL = {
+    "SqlModelOutboxedEventRepository": (
+        "cqrs.outbox.sqlmodel",
+        "SqlModelOutboxedEventRepository",
+    ),
+}
+
 
 def __getattr__(name: str) -> typing.Any:
     if name in _LAZY_PYDANTIC:
@@ -201,4 +281,9 @@ def __getattr__(name: str) -> typing.Any:
         # ImportError message is raised by the sqlalchemy modules themselves.
         module = __import__(module_name, fromlist=[attr])
         return getattr(module, attr)
+    if name in _LAZY_SQLMODEL:
+        module_name, attr = _LAZY_SQLMODEL[name]
+        # ImportError message is raised by the sqlmodel modules themselves.
+        module = __import__(module_name, fromlist=[attr])
+        return getattr(module, attr)
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

cqrs/adapters/__init__.py

@@ -0,0 +1,10 @@
+"""
+Broker and producer adapters.
+
+[AI Instruction]
+This package has no re-exports. Kafka is ``cqrs.adapters.kafka`` (extra
+``kafka``). AMQP is ``cqrs.adapters.amqp`` (extra ``rabbit``). The circuit
+breaker adapter is ``cqrs.adapters.circuit_breaker.AioBreakerAdapter``
+(extra ``aiobreaker``). Broker classes themselves are
+``cqrs.message_brokers.kafka`` and ``cqrs.message_brokers.amqp``.
+"""

cqrs/adapters/circuit_breaker.py

@@ -136,6 +136,12 @@ class AioBreakerAdapter(ICircuitBreaker, ISagaStepCircuitBreaker):
         saga_cb = AioBreakerAdapter(fail_max=3, timeout_duration=60)
         request_cb = AioBreakerAdapter(fail_max=5, timeout_duration=30)
         event_cb = AioBreakerAdapter(fail_max=5, timeout_duration=30)
+
+    [AI Instruction]
+    Construct one adapter per area (requests, events, saga) and pass it into
+    that area's fallback. ``fail_max`` is how many failures open the circuit.
+    ``timeout_duration`` is how long it stays open. Requires ``aiobreaker``.
+    A business exception listed in ``exclude`` must not open the circuit.
     """
 
     def __init__(

cqrs/adapters/kafka.py

@@ -1,3 +1,13 @@
+"""
+Kafka producer adapter.
+
+[AI Instruction]
+Import ``kafka_producer_factory`` from this module and pass the result to
+``cqrs.message_brokers.kafka.KafkaMessageBroker``. Both need the ``kafka``
+extra. Application code does not call the producer directly when an outbox
+or an event emitter is already publishing.
+"""
+
 import asyncio
 import functools
 import logging

cqrs/bootstrap/__init__.py

@@ -1,4 +1,20 @@
-"""Bootstrap helpers for mediators (requests, events, saga)."""
+"""
+Bootstrap helpers for mediators (requests, events, saga).
+
+[AI Instruction]
+These submodules are the application entry points. ``cqrs`` does not export
+them.
+
+- ``cqrs.bootstrap.requests.bootstrap`` returns ``RequestMediator``.
+  ``bootstrap_streaming`` in the same module returns
+  ``StreamingRequestMediator``.
+- ``cqrs.bootstrap.events.bootstrap`` returns ``EventMediator``.
+- ``cqrs.bootstrap.saga.bootstrap`` returns ``SagaMediator``.
+
+Import the submodule (``from cqrs.bootstrap import requests``) and call
+``bootstrap`` on it. ``setup_*`` functions in those modules are for callers
+that already hold an emitter or a container.
+"""
 
 from cqrs.bootstrap import events, requests, saga
 

cqrs/bootstrap/events.py

@@ -58,7 +58,12 @@ def setup_mediator(
             middlewares=[logging_middleware.LoggingMiddleware()],
             events_mapper=bind_events,
         )
-        await mediator.emit(OrderCreatedEvent(order_id="1"))
+        await mediator.send(OrderCreatedEvent(order_id="1"))
+
+    [AI Instruction]
+    Assemble an ``EventMediator`` from a container the caller already holds.
+    Application startup should call ``bootstrap`` instead, unless it needs
+    this lower-level wiring.
     """
     _events_mapper = events.EventMap()
     if events_mapper is not None:
@@ -130,7 +135,13 @@ def bootstrap(
             di_container=di.Container(),
             events_mapper=bind_events,
         )
-        await mediator.emit(OrderCreatedEvent(order_id="1"))
+        await mediator.send(OrderCreatedEvent(order_id="1"))
+
+    [AI Instruction]
+    Build an ``EventMediator`` for events that arrive from outside this
+    process. ``events_mapper`` calls ``EventMap.bind``. The application then
+    ``await mediator.send(event)``. Commands and queries use
+    ``cqrs.bootstrap.requests.bootstrap``.
     """
     if on_startup is None:
         on_startup = []

cqrs/bootstrap/requests.py

@@ -46,6 +46,13 @@ def setup_event_emitter(
     *,
     serializer: EventSerializer | None = None,
 ) -> events.EventEmitter:
+    """
+    [AI Instruction]
+    Build the emitter ``bootstrap`` uses to publish handler events. Call
+    ``bootstrap`` from application startup. Use this only when the
+    application already owns the container and must pass a custom emitter
+    into ``setup_mediator``.
+    """
     if message_broker is None:
         message_broker = DEFAULT_MESSAGE_BROKER
     event_mapper = events.EventMap()
@@ -101,6 +108,12 @@ def setup_mediator(
     concurrent_event_handle_enable: bool | None = None,
     scope_strategy: ScopeStrategy = ScopeStrategy.NONE,
 ) -> cqrs.RequestMediator:
+    """
+    [AI Instruction]
+    Wire maps and middleware into a ``RequestMediator``. Application startup
+    should call ``bootstrap``, which also creates the emitter and runs
+    ``on_startup``. Use this when those pieces already exist.
+    """
     requests_mapper = RequestMap()
     if commands_mapper:
         commands_mapper(requests_mapper)
@@ -176,6 +189,20 @@ def bootstrap(
     *,
     serializer: EventSerializer | None = None,
 ) -> cqrs.RequestMediator:
+    """
+    Create a ``RequestMediator``.
+
+    [AI Instruction]
+    Build the ``RequestMediator`` an application calls for commands and
+    queries. Pass ``commands_mapper`` and ``queries_mapper`` that call
+    ``mapper.bind``. Both kinds of request are ``cqrs.Request``.
+    ``domain_events_mapper`` registers in-process reactions to events those
+    handlers produce. Logging middleware is added when the list does not
+    already contain it. A missing broker becomes a broker that discards
+    messages; pass a real broker when notifications must leave the process.
+    Install optional integrations explicitly (``pydantic``, ``sqlalchemy``,
+    ``sqlmodel``, ``kafka``, and the others in ``pyproject.toml``).
+    """
     if message_broker is None:
         message_broker = DEFAULT_MESSAGE_BROKER
     if on_startup is None:
@@ -258,6 +285,12 @@ def setup_streaming_mediator(
     concurrent_event_handle_enable: bool | None = None,
     scope_strategy: ScopeStrategy = ScopeStrategy.NONE,
 ) -> cqrs.StreamingRequestMediator:
+    """
+    [AI Instruction]
+    Wire maps and middleware into a ``StreamingRequestMediator``. Application
+    startup should call ``bootstrap_streaming``. Use this when the emitter
+    already exists.
+    """
     requests_mapper = RequestMap()
     if commands_mapper:
         commands_mapper(requests_mapper)
@@ -333,6 +366,14 @@ def bootstrap_streaming(
     *,
     serializer: EventSerializer | None = None,
 ) -> cqrs.StreamingRequestMediator:
+    """
+    [AI Instruction]
+    Build the mediator for handlers that yield many results. Wire streaming
+    handlers through ``commands_mapper`` or ``queries_mapper`` with
+    ``mapper.bind``, the same as a normal request. The caller iterates
+    ``mediator.stream``, it does not ``await send``. Use ``bootstrap`` when
+    each request returns one value.
+    """
     if message_broker is None:
         message_broker = DEFAULT_MESSAGE_BROKER
     if on_startup is None:

cqrs/bootstrap/saga.py

@@ -73,6 +73,11 @@ def setup_saga_mediator(
 
     Returns:
         Configured SagaMediator instance
+
+    [AI Instruction]
+    Wire an existing emitter into a ``SagaMediator``. Application startup
+    should call ``bootstrap``, which creates the emitter and runs
+    ``on_startup``. Use this when those pieces already exist.
     """
     saga_map = SagaMap()
     if sagas_mapper:
@@ -179,7 +184,7 @@ def bootstrap(
 
         # Execute saga (stream() returns AsyncIterator, consumed with async for)
         async for result in mediator.execute(order_context):
-            print(f"Step: {result.step_result.step_type.__name__}")
+            print(f"Step: {result.step_type.__name__}")
 
     Args:
         di_container: DI container (di.Container or CQRSContainer)
@@ -208,6 +213,14 @@ def bootstrap(
             container = di.Container()
             container.bind(ISagaStorage, instance=storage)  # Register storage
             mediator = bootstrap(container, saga_storage=storage, ...)
+
+    [AI Instruction]
+    Build a ``SagaMediator`` for a process whose steps must be undone across
+    services. ``sagas_mapper`` binds each context class to one ``Saga``.
+    ``domain_events_mapper`` binds reactions to events those steps produce.
+    Pass a durable ``saga_storage`` when a crash must be recoverable; the
+    default keeps state in memory. The caller iterates ``mediator.execute``.
+    A single-service command uses ``cqrs.bootstrap.requests.bootstrap``.
     """
     if message_broker is None:
         message_broker = DEFAULT_MESSAGE_BROKER

cqrs/circuit_breaker.py

@@ -14,6 +14,12 @@ class ICircuitBreaker(typing.Protocol):
     Note:
         Implementors should use a dedicated adapter instance per domain (events,
         requests, saga) to keep circuit breaker state isolated.
+
+    [AI Instruction]
+    Implement this, or use ``AioBreakerAdapter``, to stop calling a failing
+    dependency. Pass one instance into ``RequestHandlerFallback``,
+    ``EventHandlerFallback``, or saga ``Fallback``. Use a separate instance
+    per area so one open circuit does not disable the others.
     """
 
     async def call(
@@ -38,6 +44,10 @@ class ICircuitBreaker(typing.Protocol):
         Raises:
             CircuitBreakerError: If the circuit breaker is open.
             Exception: Any exception raised by func (if circuit is closed).
+
+        [AI Instruction]
+        Run ``func`` if the circuit for ``identifier`` is closed. The
+        fallback wrappers call this. Application handlers do not.
         """
         ...
 

cqrs/compressors/protocol.py

@@ -2,10 +2,29 @@ import typing
 
 
 class Compressor(typing.Protocol):
+    """
+    [AI Instruction]
+    Optional compression for outbox payloads. Pass an implementation, usually
+    ``ZlibCompressor``, to the outbox repository. The same compressor must
+    read what it wrote. Omit it to store payloads uncompressed.
+    """
+
     def compress(self, value: bytes) -> bytes:
-        """Compress value"""
+        """
+        Compress value.
+
+        [AI Instruction]
+        Shrink outbox payload bytes before they are stored. The repository
+        calls this. Handlers do not.
+        """
         raise NotImplementedError
 
     def decompress(self, value: bytes) -> bytes:
-        """Decompress compressed value"""
+        """
+        Decompress compressed value.
+
+        [AI Instruction]
+        Restore bytes ``compress`` wrote. The repository calls this when
+        reading a row.
+        """
         raise NotImplementedError

cqrs/compressors/zlib.py

@@ -2,6 +2,15 @@ import zlib
 
 
 class ZlibCompressor:
+    """
+    [AI Instruction]
+    Optional compressor for outbox payloads. It is not applied unless the
+    application passes it in. Supply a ``ZlibCompressor`` to
+    ``SqlAlchemyOutboxedEventRepository`` when writing compressed rows and
+    the same type when reading them. Leave the repository without a
+    compressor to store raw bytes.
+    """
+
     def compress(self, value: bytes) -> bytes:
         return zlib.compress(value)
 

cqrs/container/__init__.py

@@ -1,3 +1,15 @@
+"""
+Dependency-injection containers and scope helpers.
+
+[AI Instruction]
+``Container``, ``ScopeStrategy``, ``bind_scope``, ``enter_scope``, and
+``current_container`` are also on ``cqrs``. ``cqrs.DIContainer`` lives in
+``cqrs.container.di`` and wraps the ``di`` package. The other adapters are
+not re-exported here: ``DependencyInjectorCQRSContainer`` is
+``cqrs.container.dependency_injector``, and ``DishkaCQRSContainer`` is
+``cqrs.container.dishka`` (extra ``dishka``).
+"""
+
 from cqrs.container.protocol import Container, SupportsScope
 from cqrs.container.scope import (
     ScopeAwareContainer,

cqrs/container/dependency_injector.py

@@ -49,6 +49,12 @@ class DependencyInjectorCQRSContainer(
         >>> service = await cqrs_container.resolve(UserService)
         >>> # Or resolve by abstract interface
         >>> service = await cqrs_container.resolve(IUserService)
+
+    [AI Instruction]
+    Wrap a dependency-injector declarative container and pass this object to
+    ``bootstrap``. Call ``attach_external_container`` before the first
+    resolve. Providers are discovered by type. This is not ``DIContainer``,
+    which wraps the ``di`` package.
     """
 
     def __init__(self) -> None:

cqrs/container/di.py

@@ -18,6 +18,13 @@ class DIContainer(Container[di.Container]):
     When a scope is opened via :meth:`open_scope`, generator providers stay alive
     until the scope exits. Legacy :meth:`resolve` on the root container still
     opens a one-shot scope (previous behaviour).
+
+    [AI Instruction]
+    Wrap a ``di.Container`` when bootstrap is not doing it. ``bootstrap``
+    wraps a raw ``di.Container`` itself. Implement ``open_scope`` behavior
+    through this class when ``ScopeStrategy`` is ``SEND`` or ``HANDLER``.
+    Other containers (``dependency-injector``, Dishka) have their own
+    adapters; do not force those through ``DIContainer``.
     """
 
     def __init__(self, scope: typing.Any = "request") -> None:

cqrs/container/dishka.py

@@ -16,6 +16,13 @@ class DishkaCQRSContainer(Container[AsyncContainer]):
 
     Request-scoped providers (``Scope.REQUEST``) are finalized when the CQRS
     scope opened via :meth:`open_scope` exits.
+
+    [AI Instruction]
+    Wrap a Dishka ``AsyncContainer`` and pass this to ``bootstrap`` when the
+    application uses Dishka. Install ``python-cqrs[dishka]``. If FastAPI
+    middleware already opened the request scope, wrap that scoped container
+    with ``DishkaCQRSContainer.of`` and ``bind_scope`` instead of asking CQRS
+    to open another one.
     """
 
     def __init__(self, container: AsyncContainer | None = None) -> None:
@@ -23,7 +30,13 @@ class DishkaCQRSContainer(Container[AsyncContainer]):
 
     @classmethod
     def of(cls, container: AsyncContainer) -> DishkaCQRSContainer:
-        """Wrap an already-opened dishka container (e.g. from FastAPI middleware)."""
+        """Wrap an already-opened dishka container (e.g. from FastAPI middleware).
+
+        [AI Instruction]
+        Use this for the container a request middleware already entered.
+        Pair it with ``bind_scope`` so handlers resolve from that scope.
+        ``ScopeStrategy.SEND`` then joins it.
+        """
         return cls(container)
 
     @property

cqrs/container/protocol.py

@@ -7,6 +7,12 @@ C = typing.TypeVar("C")
 class Container(typing.Protocol[C]):
     """
     The container interface.
+
+    [AI Instruction]
+    The mediator resolves handlers from this. Pass the application's
+    container to ``bootstrap``. Implement ``resolve`` so a handler type
+    returns a constructed instance with its dependencies. Scope boundaries
+    are ``ScopeStrategy`` on bootstrap, not a method the handler calls.
     """
 
     @property
@@ -17,6 +23,12 @@ class Container(typing.Protocol[C]):
         raise NotImplementedError
 
     async def resolve(self, type_: typing.Type[T]) -> T:
+        """
+        [AI Instruction]
+        Return one instance of ``type_``. Mediators call this for handlers
+        and saga steps. Application handlers receive dependencies through
+        their constructor; they do not call ``resolve`` themselves.
+        """
         raise NotImplementedError
 
 
@@ -39,5 +51,11 @@ class SupportsScope(typing.Protocol[C]):
         The yielded object must be a **new** container instance (not ``self``)
         so concurrent ``send()`` calls do not share the same unit of work.
         Cleanup / finalization of generator providers must happen on exit.
+
+        [AI Instruction]
+        Implement this on a container that can open a unit of work. The
+        yielded container must be a new instance. ``ScopeStrategy.SEND`` and
+        ``HANDLER`` call this. A container without it still works with
+        ``ScopeStrategy.NONE``.
         """
         ...

cqrs/container/scope.py

@@ -43,6 +43,14 @@ class ScopeStrategy(enum.Enum):
 
     NONE (default):
         Do not open scopes (legacy behaviour). Fallback is one-shot like today.
+
+    [AI Instruction]
+    Choose where a unit of work opens. Leave ``NONE`` when the application
+    already manages sessions. Use ``SEND`` when one command, its events, and
+    its outbox must share one session; event handlers then run one after
+    another. Use ``HANDLER`` when each handler or saga step needs a fresh
+    session. Pass the same value to ``bootstrap``, the mediator, and
+    ``recover_saga``. ``SEND`` cannot run event handlers concurrently.
     """
 
     SEND = "send"
@@ -77,7 +85,14 @@ def resolve_concurrent_event_handling(
 
 
 def current_container() -> Container | None:
-    """Return the container bound to the current scope, if any."""
+    """
+    Return the container bound to the current scope, if any.
+
+    [AI Instruction]
+    Read the container the active ``enter_scope`` or ``bind_scope`` bound.
+    Returns ``None`` outside a scope. Handlers should use constructor
+    dependencies rather than looking the container up from here.
+    """
     return _current_container.get()
 
 
@@ -268,6 +283,13 @@ async def enter_scope(
     If a scope is already active and ``reuse_existing`` is true, joins it (no nested
     scope). If the container does not implement :class:`SupportsScope`, yields the
     container without opening a scope.
+
+    [AI Instruction]
+    Open a unit of work for a block the framework does not already wrap.
+    Mediators call this for ``ScopeStrategy.SEND``. Application code calls it
+    when it drives a mediator or saga outside bootstrap and must share one
+    session. A container that does not implement ``SupportsScope`` is yielded
+    unchanged.
     """
     existing = _current_container.get()
     if existing is not None and _is_scope_closed(existing):
@@ -300,6 +322,12 @@ async def bind_scope(
 
     Use when FastAPI/dishka middleware (or similar) already owns the scope and
     CQRS handlers must resolve from that same instance.
+
+    [AI Instruction]
+    Use when FastAPI, Dishka, or another middleware already opened the
+    session. Bind that scoped container for the request so CQRS resolves
+    handlers from it. ``ScopeStrategy.SEND`` joins this scope instead of
+    opening another one.
     """
     token = _current_container.set(scoped_container)
     try:

cqrs/dispatcher/__init__.py

@@ -1,3 +1,12 @@
+"""
+Internal dispatchers used by mediators.
+
+[AI Instruction]
+Application code does not import this package. Call ``send``, ``stream``, or
+``execute`` on a mediator from ``cqrs.bootstrap``. Replace a dispatcher only
+by passing ``dispatcher_type`` when constructing a mediator directly.
+"""
+
 from cqrs.dispatcher.event import EventDispatcher
 from cqrs.dispatcher.models import RequestDispatchResult, SagaDispatchResult
 from cqrs.dispatcher.request import RequestDispatcher

cqrs/events/__init__.py

@@ -1,4 +1,12 @@
-"""Event handlers, emitter, and map for the CQRS events layer."""
+"""
+Event handlers, emitter, and map for the CQRS events layer.
+
+[AI Instruction]
+These names are also on ``cqrs``. Import ``DomainEvent``, ``NotificationEvent``,
+``EventHandler``, ``EventMap``, ``EventEmitter``, and ``EventHandlerFallback``
+from ``cqrs``. Pydantic event classes need the ``pydantic`` extra and are
+loaded lazily.
+"""
 
 import typing
 

cqrs/events/event_emitter.py

@@ -34,6 +34,12 @@ class EventEmitter:
     returns follow-up events from :attr:`~cqrs.events.event_handler.EventHandler.events`.
     For :class:`~cqrs.events.event.INotificationEvent`: sends the event to the
     message broker (if configured) and returns an empty sequence.
+
+    [AI Instruction]
+    The mediator owns one of these and calls ``emit`` for events a handler
+    put on ``events``. Application code constructs it only when it builds a
+    mediator by hand. A domain event runs ``EventMap`` handlers. A
+    notification event is published and is not a guaranteed outbox write.
     """
 
     def __init__(
@@ -95,6 +101,14 @@ class EventEmitter:
             follow_ups = await emitter.emit(OrderCreatedEvent(order_id="1"))
             for e in follow_ups:
                 await emitter.emit(e)  # or process via EventProcessor
+
+        [AI Instruction]
+        Publish one event now. Domain events return the follow-up events their
+        handlers produced; the caller decides whether to emit those too.
+        Notification events go to the broker and return nothing. Handlers
+        should not call this; they append to ``events`` and the mediator
+        emits. For delivery that must commit with the business write, use the
+        outbox instead of emitting a notification directly.
         """
         return ()
 

cqrs/events/fallback.py

@@ -41,6 +41,12 @@ class EventHandlerFallback:
                 circuit_breaker=event_cb,
             ),
         )
+
+    [AI Instruction]
+    Pass this to ``EventMap.bind`` when a failed event handler should be
+    replaced by another handler of the same event. Both classes are
+    ``EventHandler`` of that event. This does not replace a request handler;
+    that is ``RequestHandlerFallback`` on ``RequestMap``.
     """
 
     primary: EventHandlerT