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 following methods:

- ``handle``
- ``equal``

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): {}
)
>>> handler.handle()
Hello!

minevent.handlers.BaseEventHandler.equal abstractmethod

equal(other: Any) -> bool

Compare two event handlers for equality.

This method should be implemented by child classes to define how event handlers are compared. This is used by the event manager to check for duplicate handlers.

Parameters:

Name	Type	Description	Default
other	Any	The other object to compare with. Can be any type, though typically an event handler.	required

Returns:

Type	Description
bool	True if the two event handlers are considered equal, otherwise False.

Example

>>> from minevent import EventHandler
>>> def hello_handler() -> None:
...     print("Hello!")
...
>>> handler = EventHandler(hello_handler)
>>> handler.equal(EventHandler(hello_handler))
True
>>> handler.equal(EventHandler(print, handler_args=["Hello!"]))
False

minevent.handlers.BaseEventHandler.handle abstractmethod

handle() -> 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.

Example

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

minevent.handlers.BaseEventHandlerWithArguments

Bases: BaseEventHandler

Define a base class to implement an event handler with positional and/or keyword arguments.

A child class has to implement the equal method.

Parameters:

Name	Type	Description	Default
handler	Callable	The callable function or method to be invoked when the event is triggered.	required
handler_args	Sequence[Any] | None	The positional arguments to pass to the handler when it is called. Default is None.	None
handler_kwargs	dict[str, Any] | None	The keyword arguments to pass to the handler when it is called. Default is None.	None

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): {}
)
>>> handler.handle()
Hello!
>>> handler = EventHandler(print, handler_args=["Hello!"])
>>> handler.handle()
Hello!

minevent.handlers.BaseEventHandlerWithArguments.handler property

handler: Callable

Get the handler function.

Returns:

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

minevent.handlers.BaseEventHandlerWithArguments.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.BaseEventHandlerWithArguments.handler_kwargs property

handler_kwargs: dict[str, Any]

Get the keyword arguments for the handler.

Returns:

Type	Description
dict[str, Any]	A dictionary containing the keyword arguments that will be passed to the handler when it is called.

minevent.handlers.ConditionalEventHandler

Bases: BaseEventHandlerWithArguments

Implement a conditional event handler.

This class extends BaseEventHandlerWithArguments to add conditional execution. The handler is executed only if the associated 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.

Parameters:

Name	Type	Description	Default
handler	Callable	The callable function or method to be invoked when the event is triggered and the condition is True.	required
condition	BaseCondition	The condition object that controls whether the handler is executed. The condition's evaluate method is called without arguments and must return a boolean value.	required
handler_args	Sequence[Any] | None	The positional arguments to pass to the handler when it is called. Default is None.	None
handler_kwargs	dict[str, Any] | None	The keyword arguments to pass to the handler when it is called. Default is None.	None

Example

>>> from minevent import ConditionalEventHandler, PeriodicCondition
>>> def hello_handler() -> None:
...     print("Hello!")
...
>>> handler = ConditionalEventHandler(hello_handler, PeriodicCondition(freq=3))
>>> handler
ConditionalEventHandler(
  (handler): <function hello_handler at 0x...>
  (handler_args): ()
  (handler_kwargs): {}
  (condition): PeriodicCondition(freq=3, step=0)
)
>>> handler.handle()
Hello!
>>> handler.handle()
>>> handler.handle()
>>> handler.handle()
Hello!

minevent.handlers.ConditionalEventHandler.condition property

condition: BaseCondition

Get the condition that controls handler execution.

Returns:

Type	Description
BaseCondition	The condition that must evaluate to True for the handler to be executed.

minevent.handlers.EventHandler

Bases: BaseEventHandlerWithArguments

Implement a simple 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.

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): {}
)
>>> handler.handle()
Hello!