StreamRequestHandler

StreamRequestHandler defines the generator that handles one StreamRequest type. The request's StreamRequest[ChunkT] declaration supplies the required iterator element type.

from abc import ABC, abstractmethod
from collections.abc import AsyncIterator
from typing import Any

from pymediate import StreamRequest, StreamRequestHandler

class StreamRequestHandler[StreamReqT: StreamRequest[Any]](ABC):
    @abstractmethod
    def __call__(self, request: StreamReqT) -> AsyncIterator[Any]: ...

The asynchronous abstract signature is a regular def returning AsyncIterator[Any]. A concrete asynchronous handler implements it as an async generator: async def containing yield.

Definition-time validation

When Python defines a stream-handler subclass, PyMediate checks that:

• StreamReqT is a parameterized StreamRequest subclass;
• the subclass defines an async generator for pymediate.StreamRequestHandler, or a plain generator for pymediate.sync.StreamRequestHandler;
• the generator has exactly one parameter besides self, annotated with the exact StreamReqT class; and
• its return annotation is AsyncIterator[ChunkT] or Iterator[ChunkT], matching the chunk type declared by the request.

A function that returns an iterator without using yield does not satisfy this contract. Validation can raise InvalidStreamRequestTypeError, InvalidHandlerSignatureError, or HandlerAlreadyRegisteredError. The process-wide handler registry permits one stream-handler class for each stream-request type.

Example

from collections.abc import AsyncIterator

from pymediate import StreamRequestHandler

class ExportOrdersHandler(StreamRequestHandler[ExportOrders]):
    async def __call__(self, request: ExportOrders) -> AsyncIterator[bytes]:
        yield b"order_id,total_pence\n"
        yield b"42,2500\n"

Pipeline behaviors wrap send() only; they do not wrap stream().

Introspection methods

See also

• StreamRequest — declares the chunk type
• Mediator.stream() — resolves and invokes the handler
• Streaming — lazy iteration and errors
• Errors — validation and dispatch errors