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!

Async handlers

# Import the module
import pyding
import asyncio

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

# Call the event
asyncio.run(pyding.async_call('greetings'))

# Hello there from pyding!

Waiting for events

You can wait for events to be called from another part from your code without having to create a handler by using pyding.wait_for

# Import the module
import pyding
from threading import Thread
from time import sleep

def random_calls():
    # Keep calling the event every 10 seconds.
    while True:
        pyding.call("random_event")
        sleep(10)

# Start the thread
thread = Thread(target=random_calls, daemon=True)
thread.start()

# Wait for the event to be called
event_inputs = pyding.wait_for("random_event")
# event_inputs = {'event': EventCall object, ... any other keyargs here ... }

Queues

Queues are populated from events, useful for multiple entry points approaches with pyding.queue

import pyding
from threading import Thread

def listener(event):
    queue = pyding.queue("foo")
    while True:
        event = queue.get()
        # do stuff here...

# Start the listener
Thread(target=listener, daemon=True).start()

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

Cancellable events

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

⚠️ - Cancelling an 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

🛑 - You can also stop the event execution by using event.stop()

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!

Essential arguments can be passed to @pyding.on to make sure the handler only will be called if they're met.

import pyding

# Attach the handler to an event
@pyding.on("greetings", name="John Doe")
def john_doe_greeter(event, name, time):
    return f"Hello {name}! It's currently {time}"


# Call the event
event_two = pyding.call("greetings", name="John Bar", time="10 AM")
# There won't be any response since the handler won't be called since the 'name' essential keyword wasn't equal to 'John Doe'.
event_two.response
# None

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

event.response
# "Hello John Doe! It's currently 10 AM"

# You can also raise pyding.exceptions.UnfulfilledException if you add requirement_exceptions=True to pyding.on decorator.

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!

Removing handlers

Event spaces allow you to unregister handlers.

# Import the module
import pyding

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

# Unregister event
pyding.unregister_handler(greeter)
# Or
greeter.unregister()
# You can also remove handlers from other modules by using pyding.unregister_from_module(module)