Main classes and functions¶

minevent ¶

Contain the main features of the minevent package.

minevent.BaseCondition ¶

Bases: ABC

Define the base class to implement a condition for ConditionalEventHandler.

A child class has to implement the following methods:

- ``evaluate``
- ``equal``

Example

>>> from minevent import PeriodicCondition
>>> condition = PeriodicCondition(freq=3)
>>> condition.evaluate()
True
>>> condition.evaluate()
False
>>> condition.evaluate()
False
>>> condition.evaluate()
True
>>> condition.evaluate()
False
>>> condition.evaluate()
False
>>> condition.evaluate()
True

minevent.BaseCondition.equal `abstractmethod` ¶

equal(other: Any) -> bool

Compare two conditions for equality.

This method should be implemented by child classes to define how conditions are compared. This is used when comparing conditional event handlers.

Parameters:

Name	Type	Description	Default
`other`	`Any`	The other object to compare with. Can be any type, though typically a condition.	required

Returns:

Type	Description
`bool`	`True` if the two conditions are considered equal, otherwise `False`.

Example

>>> from minevent import PeriodicCondition
>>> condition = PeriodicCondition(freq=3)
>>> condition.equal(PeriodicCondition(freq=3))
True
>>> condition.equal(PeriodicCondition(freq=2))
False

minevent.BaseCondition.evaluate `abstractmethod` ¶

evaluate() -> bool

Evaluate the condition given the current state.

This method should be implemented by child classes to define the logic for determining whether a conditional event handler should be executed. The method is called without arguments and may maintain internal state between calls.

Returns:

Type	Description
`bool`	`True` if the condition is satisfied and the event handler logic should be executed, otherwise `False`.

Example

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

minevent.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.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.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.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.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.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.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.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.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.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!

minevent.EventManager ¶

Implement an event manager.

This event manager allows registering event handlers and triggering events. An event is represented by a case-sensitive string. Each event can have multiple handlers attached, and all handlers are executed in the order they were added when the event is triggered. The manager also tracks the last triggered event.

Example

>>> from minevent import EventHandler, EventManager
>>> def hello_handler():
...     print("Hello!")
...
>>> manager = EventManager()
>>> manager.add_event_handler("my_event", EventHandler(hello_handler))
>>> manager.trigger_event("my_event")
Hello!

minevent.EventManager.last_triggered_event `property` ¶

last_triggered_event: str | None

Get the last event name that was triggered.

Returns:

Type	Description
`str \| None`	The last event name that was fired of `None` if no event was fired.

Example

>>> from minevent import EventHandler, EventManager
>>> manager = EventManager()
>>> def hello_handler():
...     print("Hello!")
...
>>> manager.add_event_handler("my_event", EventHandler(hello_handler))
>>> manager.trigger_event("my_event")
Hello!
>>> manager.last_triggered_event

minevent.EventManager.add_event_handler ¶

add_event_handler(
    event: str, event_handler: BaseEventHandler
) -> None

Add an event handler to an event.

The event handler will be called every time the specified event is triggered. Multiple handlers can be registered to the same event, and they will be executed in the order they were added.

Parameters:

Name	Type	Description	Default
`event`	`str`	The event name (case-sensitive string) to which the event handler should be attached.	required
`event_handler`	`BaseEventHandler`	The event handler instance to attach to the event.	required

Example

>>> from minevent import EventManager, EventHandler
>>> def hello_handler():
...     print("Hello!")
...
>>> manager = EventManager()
>>> manager.add_event_handler("my_event", EventHandler(hello_handler))

minevent.EventManager.has_event_handler ¶

has_event_handler(
    event_handler: BaseEventHandler,
    event: str | None = None,
) -> bool

Indicate if a handler is registered in the event manager.

This method checks whether a specific event handler is registered, either for a specific event or across all events. Note that this method relies on the equal method of the input event handler to compare event handlers.

Parameters:

Name	Type	Description	Default
`event_handler`	`BaseEventHandler`	The event handler instance to search for in the registered handlers.	required
`event`	`str \| None`	An event name (case-sensitive string) to check. If `None`, the method will search across all registered events. Default is `None`.	`None`

Example

>>> from minevent import EventHandler, EventManager
>>> def hello_handler():
...     print("Hello!")
...
>>> manager = EventManager()
>>> # Check if `hello_handler` is registered in the event manager
>>> manager.has_event_handler(EventHandler(hello_handler))
False
>>> # Check if `hello_handler` is registered in the event manager for 'my_event' event
>>> manager.has_event_handler(EventHandler(hello_handler), "my_event")
False
>>> # Add an event handler
>>> manager.add_event_handler("my_event", EventHandler(hello_handler))
>>> # Check if `hello_handler` is registered in the event manager
>>> manager.has_event_handler(EventHandler(hello_handler))
True
>>> # Check if `hello_handler` is registered in the event manager for 'my_event' event
>>> manager.has_event_handler(EventHandler(hello_handler), "my_event")
True
>>> # Check if `hello_handler` is registered in the event manager for 'my_other_event' event
>>> manager.has_event_handler(EventHandler(hello_handler), "my_other_event")
False

minevent.EventManager.remove_event_handler ¶

remove_event_handler(
    event: str, event_handler: BaseEventHandler
) -> None

Remove an event handler of a given event.

This method removes all occurrences of the specified event handler from the given event. If the same event handler was added multiple times to the event, all duplicates are removed. This method relies on the equal method of the input event handler to compare event handlers.

Parameters:

Name	Type	Description	Default
`event`	`str`	The event name (case-sensitive string) from which the handler should be removed.	required
`event_handler`	`BaseEventHandler`	The event handler instance to remove from the event.	required

Raises:

Type	Description
`RuntimeError`	if the event does not exist or if the handler is not attached to the event.

Example

>>> from minevent import EventHandler, EventManager
>>> manager = EventManager()
>>> def hello_handler():
...     print("Hello!")
...
>>> manager.add_event_handler("my_event", EventHandler(hello_handler))
>>> # Check if `hello_handler` is registered in the event manager for 'my_event' event
>>> manager.has_event_handler(EventHandler(hello_handler), "my_event")
True
>>> # Remove the event handler of the engine
>>> manager.remove_event_handler("my_event", EventHandler(hello_handler))
>>> # Check if `hello_handler` is registered in the event manager for 'my_event' event
>>> manager.has_event_handler(EventHandler(hello_handler), "my_event")
False

minevent.EventManager.reset ¶

reset() -> None

Reset the event manager.

This method removes all registered event handlers from the event manager and resets the last triggered event to None. After calling this method, the event manager returns to its initial state.

Example

>>> # Create an event manager
>>> from minevent import EventManager
>>> manager = EventManager()
>>> # Add an event handler to the engine
>>> def hello_handler():
...     print("Hello!")
...
>>> from minevent import EventHandler
>>> manager.add_event_handler("my_event", EventHandler(hello_handler))
>>> # Check if `hello_handler` is registered in the event manager for 'my_event' event
>>> manager.has_event_handler(EventHandler(hello_handler), "my_event")
True
>>> manager.trigger_event("my_event")
>>> manager.last_triggered_event
my_event
>>> # Reset the event manager
>>> manager.reset()
>>> # Check if `hello_handler` is registered in the event manager for 'my_event' event
>>> manager.has_event_handler(EventHandler(hello_handler), "my_event")
False
>>> manager.last_triggered_event
None

minevent.EventManager.trigger_event ¶

trigger_event(event: str) -> None

Trigger the handler(s) for the given event.

This method executes all event handlers registered for the specified event in the order they were added. The last triggered event name is updated regardless of whether any handlers are registered.

Parameters:

Name	Type	Description	Default
`event`	`str`	The event name (case-sensitive string) to trigger.	required

Example

>>> from minevent import EventHandler, EventManager
>>> manager = EventManager()
>>> manager.trigger_event("my_event")  # do nothing because there is no event handler
>>> def hello_handler():
...     print("Hello!")
...
>>> manager.add_event_handler("my_event", EventHandler(hello_handler))
>>> manager.trigger_event("my_event")
Hello!

minevent.PeriodicCondition ¶

Bases: BaseCondition

Implement a periodic condition.

This condition evaluates to True every freq calls to the evaluate method. It maintains an internal counter that increments with each evaluation. The condition is True when the counter modulo freq equals zero.

Parameters:

Name	Type	Description	Default
`freq`	`int`	The frequency (interval) at which the condition evaluates to `True`. Must be a positive integer.	required

Example

>>> from minevent import PeriodicCondition
>>> condition = PeriodicCondition(freq=3)
>>> condition.evaluate()
True
>>> condition.evaluate()
False
>>> condition.evaluate()
False
>>> condition.evaluate()
True
>>> condition.evaluate()
False
>>> condition.evaluate()
False
>>> condition.evaluate()
True

minevent.PeriodicCondition.freq `property` ¶

freq: int

Get the frequency of the periodic condition.

Returns:

Type	Description
`int`	The number of evaluations between each `True` result. The condition evaluates to `True` every `freq` calls.

Main classes and functions¶

minevent ¶

minevent.BaseCondition ¶

minevent.BaseCondition.equal abstractmethod ¶

minevent.BaseCondition.evaluate abstractmethod ¶

minevent.BaseEventHandler ¶

minevent.BaseEventHandler.equal abstractmethod ¶

minevent.BaseEventHandler.handle abstractmethod ¶

minevent.BaseEventHandlerWithArguments ¶

minevent.BaseEventHandlerWithArguments.handler property ¶

minevent.BaseEventHandlerWithArguments.handler_args property ¶

minevent.BaseEventHandlerWithArguments.handler_kwargs property ¶

minevent.ConditionalEventHandler ¶

minevent.ConditionalEventHandler.condition property ¶

minevent.EventHandler ¶

minevent.EventManager ¶

minevent.EventManager.last_triggered_event property ¶

minevent.EventManager.add_event_handler ¶

minevent.EventManager.has_event_handler ¶

minevent.EventManager.remove_event_handler ¶

minevent.EventManager.reset ¶

minevent.EventManager.trigger_event ¶

minevent.PeriodicCondition ¶

minevent.PeriodicCondition.freq property ¶

minevent.BaseCondition.equal `abstractmethod` ¶

minevent.BaseCondition.evaluate `abstractmethod` ¶

minevent.BaseEventHandler.equal `abstractmethod` ¶

minevent.BaseEventHandler.handle `abstractmethod` ¶

minevent.BaseEventHandlerWithArguments.handler `property` ¶

minevent.BaseEventHandlerWithArguments.handler_args `property` ¶

minevent.BaseEventHandlerWithArguments.handler_kwargs `property` ¶

minevent.ConditionalEventHandler.condition `property` ¶

minevent.EventManager.last_triggered_event `property` ¶

minevent.PeriodicCondition.freq `property` ¶