pyding 1.3.2

Simpĺe but effective event framework

pyding 🛎

PyDing is a (very) simple but effective event handler.

Usage

# Import the module
import pyding

# Attach a handler to an event.
@pyding.on("greetings")
def greeter(event):
    print("Hello there from pyding!")

# Call the event
pyding.call("greetings")

# Hello there from pyding!

Cancellable events

You can also make events that can be cancelled, using the cancellable keyword for pyding.call

⚠️ - Cancelling and event which cannot be cancelled will raise pyding.exceptions.UncancellableEvent

import pyding

# Attach the handler to an event
@pyding.on("check")
def checker(event):
    # Do stuff    
    # Cancel the event
    event.cancel()

# Call the event
event = pyding.call("check", cancellable=True)

event.cancelled
# will return True

Hierarchy

Event handlers can have an priority attached to them. If the event is cancelled, it will not execute the next handlers. This behavior can be changed by the blocking keyword for pyding.call

import pyding

# Attach the handler to an event
@pyding.on("check", priority=10)
def checker_one(event):
    print("I got executed!")


@pyding.on("check", priority=0)
def checker_two(event):
    print("Me too")


# Call the event
event = pyding.call("check")

# I got executed!
# Me too

import pyding

# Attach the handler to an event
@pyding.on("check", priority=10)
def checker_one(event):
    print("I got executed!")
    event.cancel()


@pyding.on("check", priority=0)
def checker_two(event):
    # This won't be executed at first since it got cancelled by checker_one
    print("Me too")


# Call the event
pyding.call("check", cancellable=True)

# I got executed!

# Call the event and do not break if the event is cancelled.
event = pyding.call("check", cancellable=True, blocking=False)

# I got executed!
# Me too

event.cancelled
# True

Dealing with the response

Events can return values, which will be attributed to event.response and event.responses

import pyding

# Attach the handler to an event
@pyding.on("greetings")
def greeter(event):
    return "Hello World!"


# Call the event
event = pyding.call("greetings")

event.response
# Hello World!

event.responses
# ['Hello World!']

Using arguments

Arguments can be passed onto the handlers through pyding.call

import pyding

# Attach the handler to an event
@pyding.on("greetings")
def greeter(event, name):
    return f"Hello {name}!"


# Call the event
event = pyding.call("greetings", name="John Doe")

event.response
# Hello John Doe!

Events within classes

Objects can have methods that act as an event handler.

import pyding


class MyClass(pyding.EventSupport):
    def __init__(self, name):
        self.register_events()
        self.name = name

    @pyding.on("my_event")
    def event_handler(self, event):
        print(f"Hello World from MyClass! My name is {self.name}.")

# Nothing will happen because there is no instance of MyClass
pyding.call("my_event")

myclass = MyClass("foo")

pyding.call("my_event")
# "Hello world from MyClass! My name is foo."

Dealing with Event Spaces

Event spaces allow to separate event handlers.

# Import the module
import pyding

# Create an Event Space
myspace = pyding.EventSpace()

# Attach a handler to an event.
@myspace.on("greetings")
def greeter(event):
    print("Hello there from myspace's event space!")

# Calling the event from the global space won't trigger any handler from myspace.
pyding.call("greetings")

# Calling the event from myspace will trigger the "greeter" handler.
myspace.call("greetings")
# Hello there from myspace's event space!