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
|
{}
|
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
|
{}
|
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 |
required |
handler_args
|
Sequence[Any] | None
|
The positional arguments to pass to the handler
when it is called. Default is |
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
|
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 |
None
|
filter_payload
|
bool
|
If |
False
|
Raises:
| Type | Description |
|---|---|
TypeError
|
if |
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 |
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
|
|
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
|
{}
|
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
|
{}
|
Raises:
| Type | Description |
|---|---|
TypeError
|
if the handler returns an awaitable. Use
|
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