Skip to content

Handlers

minevent.handlers

Implement the event handlers.

minevent.handlers.BaseEventHandler

Bases: ABC

Define the base class to implement an event handler.

A child class has to implement the handle method. Event handlers are compared by identity, so they can be put in a set or used as dict keys. Use the Subscription returned by EventManager.add_event_handler to identify a registration.

Example
>>> from minevent import EventHandler
>>> def hello_handler() -> None:
...     print("Hello!")
...
>>> handler = EventHandler(hello_handler)
>>> handler
EventHandler(handler=<function hello_handler at 0x...>, handler_args=(), handler_kwargs={}, condition=None, filter_payload=False)
>>> handler.handle()
Hello!

minevent.handlers.BaseEventHandler.ahandle async

ahandle(**payload: object) -> None

Handle the event asynchronously.

This method is called by EventManager.atrigger_event. The default implementation calls handle, so it works for synchronous event handlers. Child classes that support coroutines should override it.

Parameters:

Name Type Description Default
**payload object

The keyword arguments given to EventManager.atrigger_event.

{}
Example
>>> import asyncio
>>> from minevent import EventHandler
>>> def hello_handler() -> None:
...     print("Hello!")
...
>>> asyncio.run(EventHandler(hello_handler).ahandle())
Hello!

minevent.handlers.BaseEventHandler.handle abstractmethod

handle(**payload: object) -> None

Handle the event.

This method executes the logic associated with the event handler. It should be implemented by child classes to define the specific behavior when an event is triggered.

Parameters:

Name Type Description Default
**payload object

The keyword arguments given to EventManager.trigger_event. The payload is empty when the event is triggered without data.

{}
Example
>>> from minevent import EventHandler
>>> def hello_handler() -> None:
...     print("Hello!")
...
>>> handler = EventHandler(hello_handler)
>>> handler.handle()
Hello!

minevent.handlers.EventHandler

Bases: BaseEventHandler

Implement an event handler.

This class wraps a callable function or method and allows it to be executed as an event handler. The handler can be configured with positional and keyword arguments that will be passed when the handler is executed, and with an optional condition. When a condition is given, the handler is executed only if the condition evaluates to True. This is useful for scenarios where event handlers should only run under specific circumstances, such as periodic execution or state-based triggering.

The handler is called as handler(*handler_args, **handler_kwargs, **payload), where payload is the data given when the event is triggered.

Parameters:

Name Type Description Default
handler Callable[..., object]

The callable function or method to be invoked when the event is triggered (and the condition is True).

required
handler_args Sequence[Any] | None

The positional arguments to pass to the handler when it is called. Default is None.

None
handler_kwargs Mapping[str, Any] | None

The keyword arguments to pass to the handler when it is called. The dictionary is copied, so changing it afterwards does not change the handler. Default is None.

None
condition Condition | None

The condition that controls whether the handler is executed: a function without argument that returns a boolean, such as a lambda or a PeriodicCondition. It is called each time the event is triggered, before the handler. If None, the handler is always executed. Default is None.

None
filter_payload bool

If True, only the payload keys that the signature of the handler accepts are passed to it, so handlers with different needs can share an event without **kwargs. The accepted keys are computed once, at construction. A handler with a **kwargs parameter, or whose signature cannot be inspected, receives the whole payload. Keys of handler_kwargs are not filtered. Default is False.

False

Raises:

Type Description
TypeError

if handler is not callable, if handler_args is a str or bytes (which would be split into characters) or is not iterable, if handler_kwargs is not a mapping or has a key that is not a str, or if condition is neither None nor callable.

Example
>>> from minevent import EventHandler, PeriodicCondition
>>> def hello_handler() -> None:
...     print("Hello!")
...
>>> handler = EventHandler(hello_handler)
>>> handler
EventHandler(handler=<function hello_handler at 0x...>, handler_args=(), handler_kwargs={}, condition=None, filter_payload=False)
>>> handler.handle()
Hello!
>>> handler = EventHandler(print, handler_args=["Hello!"])
>>> handler.handle()
Hello!
>>> handler = EventHandler(hello_handler, condition=PeriodicCondition(freq=3))
>>> handler
EventHandler(handler=<function hello_handler at 0x...>, handler_args=(), handler_kwargs={}, condition=PeriodicCondition(freq=3, skip_first=False, step=0), filter_payload=False)
>>> handler.handle()
Hello!
>>> handler.handle()
>>> handler.handle()
>>> handler.handle()
Hello!
>>> def epoch_handler(epoch: int) -> None:
...     print(f"epoch {epoch}")
...
>>> handler = EventHandler(epoch_handler, filter_payload=True)
>>> handler.handle(epoch=3, loss=0.5)
epoch 3

minevent.handlers.EventHandler.condition property

condition: Condition | None

Get the condition that controls handler execution.

Returns:

Type Description
Condition | None

The condition that must evaluate to True for the handler to be executed, or None if the handler is always executed.

minevent.handlers.EventHandler.filter_payload property

filter_payload: bool

Indicate if the payload is filtered by the signature of the handler.

Returns:

Type Description
bool

True if only the payload keys accepted by the handler are passed to it, otherwise False.

minevent.handlers.EventHandler.handler property

handler: Callable[..., object]

Get the handler function.

Returns:

Type Description
Callable[..., object]

The handler function that will be called when the event is triggered.

minevent.handlers.EventHandler.handler_args property

handler_args: tuple[Any, ...]

Get the positional arguments for the handler.

Returns:

Type Description
tuple[Any, ...]

A tuple containing the positional arguments that will be passed to the handler when it is called.

minevent.handlers.EventHandler.handler_kwargs property

handler_kwargs: dict[str, Any]

Get the keyword arguments for the handler.

Returns:

Type Description
dict[str, Any]

A copy of the dictionary containing the keyword arguments that will be passed to the handler when it is called. Modifying the returned dictionary does not change the handler.

minevent.handlers.EventHandler.ahandle async

ahandle(**payload: object) -> None

Handle the event asynchronously.

Like handle, but if the handler returns an awaitable (for example because it is a coroutine function), the awaitable is awaited. handle raises a TypeError for an awaitable, so use ahandle (or EventManager.atrigger_event) with coroutine functions.

Parameters:

Name Type Description Default
**payload object

The keyword arguments given to EventManager.atrigger_event.

{}
Example
>>> import asyncio
>>> from minevent import EventHandler
>>> async def hello_handler() -> None:
...     print("Hello!")
...
>>> asyncio.run(EventHandler(hello_handler).ahandle())
Hello!

minevent.handlers.EventHandler.handle

handle(**payload: object) -> None

Handle the event.

Calls the handler if the condition is True (or if there is no condition). The handler must be synchronous: a coroutine function would be silently dropped, so it is rejected.

Parameters:

Name Type Description Default
**payload object

The keyword arguments given to EventManager.trigger_event. The payload is empty when the event is triggered without data.

{}

Raises:

Type Description
TypeError

if the handler returns an awaitable. Use ahandle (or EventManager.atrigger_event) with coroutine functions.

Example
>>> from minevent import EventHandler
>>> async def hello_handler() -> None:
...     print("Hello!")
...
>>> EventHandler(hello_handler).handle()
Traceback (most recent call last):
    ...
TypeError: ...hello_handler... returned an awaitable; use ahandle or atrigger_event