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 usage:

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

Parameters:

Name	Type	Description	Default
other	Any	Specifies the other object to compare with.	required

Returns:

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

Example usage:

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

Returns:

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

Example usage:

>>> 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 usage:

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

Parameters:

Name	Type	Description	Default
other	Any	Specifies the other object to compare with.	required

Returns:

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

Example usage:

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

Example usage:

>>> 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	Specifies the handler.	required
handler_args	Sequence | None	Specifies the positional arguments of the handler.	None
handler_kwargs	dict | None	Specifies the arbitrary keyword arguments of the handler.	None

Example usage:

>>> 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

The handler.

minevent.BaseEventHandlerWithArguments.handler_args property

handler_args: tuple

Variable length argument list of the handler.

minevent.BaseEventHandlerWithArguments.handler_kwargs property

handler_kwargs: dict

Arbitrary keyword arguments of the handler.

minevent.ConditionalEventHandler

Bases: BaseEventHandlerWithArguments

Implement a conditional event handler.

The handler is executed only if the condition is True.

Parameters:

Name	Type	Description	Default
handler	Callable	Specifies the handler.	required
condition	BaseCondition	Specifies the condition for this event handler. The condition should be callable without arguments.	required
handler_args	Sequence | None	Specifies the positional arguments of the handler.	None
handler_kwargs	dict | None	Specifies the arbitrary keyword arguments of the handler.	None

Example usage:

>>> 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

The condition.

minevent.EventHandler

Bases: BaseEventHandlerWithArguments

Implement a simple event handler.

Example usage:

>>> 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 adding event handlers and firing events. An event is represented by a case-sensitive string.

Example usage:

>>> 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 usage:

>>> 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 everytime the event happens.

Parameters:

Name	Type	Description	Default
event	str	Specifies the event to attach the event handler.	required
event_handler	BaseEventHandler	Specifies the event handler to attach to the event.	required

Example usage:

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

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	Specifies the event handler to check.	required
event	str | None	Specifies an event to check. If the value is None, it will check all the events.	None

Example usage:

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

Note that if the same event handler was added multiple times the event, all the duplicated handlers 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	Specifies the event handler is attached to.	required
event_handler	BaseEventHandler	Specifies the event handler to remove.	required

Raises:

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

Example usage:

>>> 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 the event handlers from the event manager.

Example usage:

>>> # 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.

Parameters:

Name	Type	Description	Default
event	str	Specifies the event to fire.	required

Example usage:

>>> 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 is true every freq events.

Parameters:

Name	Type	Description	Default
freq	int	Specifies the frequency.	required

Example usage:

>>> 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

The frequency of the condition.