Consumer

Consumer

A consumer is a component that listens for and reacts to ocurrences in a bounded context. Occurrences can be modeled as events and should contain all the information needed to describe what happened in the system. Then consumers are responsible for processing events and triggering side effects in response to them.

Unlike a subscriber, that receive messages routed by the publisher, a consumer is responsible for deciding which handlers to invoke based on the type of the event it consumes. The event type should describe the ocurrence in past tense as DDD suggests when modeling events.

The events should be modeled with ubiquitous language. This means that the names of the events should reflect the domain ocurrences that the consumer is responsible for. Keep this in mind when naming the events that will be consumed by the consumer. The consumer maps it's handlers to keys generated by the event's name.

Methods:

Name	Description
handler	Decorator for registering a handler function for one or more message types.
consume	Consumes an event by invoking its registered handler functions.

Example

from pymsgbus import Consumer, event

@event
class ModelTrained:
    model: Callable
    metrics: Sequence

@event
class ModelEvaluated:
    model: Callable
    metrics: Sequence
...

consumer = Consumer()

@consumer.hander
def handle_iteration(event: ModelTrained | ModelEvaluated):
    ...
    #your logic here...

@consumer.hander
def handle_training(event: ModelTrained):
    ...
    #your logic here...

consumer.consume(ModelTrained(model, [{'name': 'loss', 'value': 0.1}])) 
# Will call both handle iteration and training. I
# If ModelEvaluated passed will only handle iteration.      

dependency_overrides property

Returns the dependency overrides for the consumer. This is useful for late binding, testing and changing the behavior of the consumer in runtime.

Returns:

Name	Type	Description
dict	dict	A dictionary of the dependency map.

consume(event)

Consumes an event by invoking its registered handler functions. If the event type is not registered with any handler, it will be ignored.

Parameters:

Name	Type	Description	Default
event	Any	The message to consume.	required

handler(wrapped)

Decorator for registering a handler function for one or more message types. The handler is registered with the name of the function as the key. The handler is also injected with the dependencies provided by the consumer.

Each message type can have multiple handlers registered to it and each handler can be registered to multiple message at the same time using unions.

Parameters:

Name	Type	Description	Default
wrapped	Callable[..., None]	The function to be registered as a handler.	required

Returns:

Type	Description
Callable[..., None]	Callable[..., None]: The injected handler function.

override(dependency, implementation)

Overrides a dependency with an implementation.

Parameters:

Name	Type	Description	Default
dependency	Callable	The dependency function to override.	required
implementation	Callable	The implementation of the function.	required

register(annotation, handler)

Registers an event type and its corresponding handler function. Handles nested or generic annotations and union types. If the annotation is a union type, it will register the handler for each of its arguments.

This method is used to register a handler from the handler method and should not be called directly. Use the handler decorator instead.

Parameters:

Name	Type	Description	Default
annotation	Any	The event annotation to be registered.	required
handler	Callable[..., None]	The handler function to be registered.	required

Returns:

Type	Description
Callable[..., None]	Callable[..., None]: The injected handler function at the end of the recursion.

event(cls)

A decorator to define an Event message. An event will store weak references to objects and is meant to be consumed by consumers inside the scope where they are produced.

Parameters:

Name	Type	Description	Default
cls	type	The ocurrence of something that happened represented by a class	required

Returns:

Name	Type	Description
type		A dataclass representing the event.