Asyncevents: a small library to help developers perform asynchronous event handling in Python

Overview

asyncevents - Asynchronous event handling for modern Python

asyncevents is a small library to help developers perform asynchronous event handling in modern Python code.

Features

  • Priority queueing to allow for deterministic event triggering (with a catch, see below)
  • Built-in exception handling (optional)
  • The public API is fully type hinted for those sweet, sweet editor suggestions
  • Public API is fully documented (and some private stuff too): you could write this from scratch in a couple of hours (like I did)
  • Very small (~200 CLOC), although it can't fit on a postcard

Note: Deterministic event handling can only occur in blocking mode, i.e. when a call to emit() blocks until all event handlers have run. If the non-blocking mode is used, handlers are started according to their priority, but there's no telling on how they will be further scheduled to run and that depends entirely on the underlying asyncio event loop

Limitations

  • Only compatible with asyncio due to the fact that other libraries such as trio and curio have wildly different design goals (structured concurrency, separation of environments, etc.), which makes implementing some functionality (i.e. the wait() method) tricky, if not outright impossible. Also those libraries, especially trio, already have decent machinery to perform roughly what asyncevent does
  • Does not support using any other loop than the currently running one because of some subtleties of modern asyncio wrappers like asyncio.run() which creates its own event loop internally (Thanks, asyncio)
  • Exceptions are kinda finicky in non-blocking mode due to how asyncio.gather works: only the first exception in a group of handlers is properly raised and log messages might get doubled. Also, exception logging and propagation is delayed until you await wait("some_event") so be careful

Why?

This library exists because the current alternatives either suck, lack features or are inspired by other languages' implementations of events like C# and Node.js: asyncevents aims to be a fully Pythonic library that provides just the features you need and nothing more (nor nothing less).

Cool! How do I use it?

Like this

import time
import asyncio
from asyncevents import on_event, emit, wait


@on_event("hello")
async def hello(_, event: str):
    print(f"Hello {event!r}!")


@on_event("hi")
async def hi(_, event: str):
    print(f"Hi {event!r}! I'm going to sleep for 5 seconds")
    await asyncio.sleep(5)  # Simulates some work


async def main():
    print("Firing blocking event 'hello'")
    await emit("hello")  # This call blocks until hello() terminates
    print("Handlers for event 'hello' have exited")
    # Notice how, until here, the output is in order: this is on purpose!
    # When using blocking mode, asyncevents even guarantees that handlers
    # with different priorities will be executed in order
    print("Firing non-blocking event 'hi'")
    await emit("hi", block=False)  # This one spawns hi() and returns immediately
    print("Non-blocking event 'hi' fired")
    await emit("event3")  # Does nothing: No handlers registered for event3!
    # We wait now for the the handler of the "hi" event to complete
    t = time.time()
    print("Waiting on event 'hi'")
    await wait("hi")  # Waits until all the handlers triggered by the "hi" event exit
    print(f"Waited for {time.time() - t:.2f} seconds")  # Should print roughly 5 seconds


if __name__ == "__main__":
    asyncio.run(main())

Note: This example showed that the event names match the functions' names: this is just for explanatory purposes! It's not compulsory for your event and their respective handlers' names to match. You can also register as many functions you want for the same or multiple events and asyncevents will call them all when one of them is fired. For more usage examples (until the documentation is done), check out the tests directory or read the source code: it's pretty straightforward, I promise.

TODOs

  • Documentation
  • More tests
  • Trio/curio backend (maybe)
Owner
Mattia
A fan of the FOSS philosophy, *nix systems and Python. Occasionally a freelance Software Developer
Mattia
MassReportBot - Discord Mass Report Bot By Dropout

Discord Mass Report Bot By Dropout Discord Report Bot, Just Re-Made The "Admin R

vanis / 1800 0 Jan 20, 2022
4 Oct 28, 2021
The successor of GeoSnipe, a pythonic Minecraft username sniper based on AsyncIO.

OneSnipe The successor of GeoSnipe, a pythonic Minecraft username sniper based on AsyncIO. Documentation View Documentation Features • Mojang & Micros

1 Jan 14, 2022
An open-source, multipurpose, configurable discord bot that does it all

Spacebot is an open source discord bot that is designed to be fun, easy to use, and replace every other discord bot out there!! Feel free to add a star ⭐ to the repository to promote the project!

Dhravya Shah 41 Dec 10, 2022
Pls give vaccine.

Pls Give Vaccine A script to spam yourself with vaccine notifications. Explore the docs » View Demo · Report Bug · Request Feature Table of Contents A

Rohan Mukherjee 3 Oct 27, 2021
This is a simple code for discord bot !

Discord bot dice roller this is a simple code for discord bot it can roll 1d4, 1d6, 1d8, 1d10, 1d12, 1d20, 1d100 for you in your discord server. Actua

Mostafa Koolabadi 0 Jan 02, 2022
Python client for Invidious' JSON API

Python project template A template for new Python projects. Features Automatically builds PDoc documentation & uploads package to PyPI on new GitHub r

Kevo 2 Jun 05, 2022
A discord bot can stress ip addresses with python tool

Python-ddos-bot Coded by Lamp#1442 A discord bot can stress ip addresses with python tool. Warning! DOS or DDOS is illegal, i shared for educational p

IrgyGANS 1 Nov 16, 2021
Telegram Url Upload Bot With Same more Features ✨

Telegram Url Upload Bot With Same more Features ✨

Group Dc Bots 4 Feb 12, 2022
A Bot To Find Telegram User ID Easily

Telegram ID Bot 🤖 A Bot To Find Telegram User ID Easily Made with Python3 (C) @BXBotz Copyright permission under MIT License License - https://githu

MuFaz-TG 6 Nov 21, 2022
Music bot because Octave is down and I can : )

Chords On a mission to build the best Discord Music Bot View Demo · Report Bug · Request Feature Table of Contents About The Project Built With Gettin

Aman Prakash Jha 53 Jan 07, 2023
Wallpaper API from wallpaperscraft.com

wallpaper-api Wallpaper API from https://wallpaperscraft.com for API documentation see https://maajid-wallpaper-api.deta.dev/docs How to Run first, cl

Athallah Muhammad Maajid 2 Apr 06, 2022
A zero-dependency Python library for getting the Kubernetes token of a AWS EKS cluster

tokeks A zero-dependency Python library for getting the Kubernetes token of a AWS EKS cluster. No AWS CLI, third-party client or library (boto3, botoc

Chris Karageorgiou Kaneen 6 Nov 04, 2022
Tesseract Open Source OCR Engine (main repository)

Tesseract OCR About This package contains an OCR engine - libtesseract and a command line program - tesseract. Tesseract 4 adds a new neural net (LSTM

48.3k Jan 05, 2023
Telegram bot to clip youtube videos

youtube-clipper-bot Telegram bot to clip youtube videos How to deploy? Create a file called config.env BOT_TOKEN: Provide your bot token generated by

Shivam Jha 11 Dec 10, 2022
Telegram bot for Whisper Message.

Whisper Bot @WhisperStarkBot A star ⭐ from you means a lot to us! Telegram bot for Whisper Message. Usage Deploy to Heroku Tap on above button and fil

Stark Bots 33 Nov 24, 2022
A GitHub Action that automatically reports your Advent of Code progress in a table in your README

Advent README Stars This action adds and maintains a stars report in your README based on your Advent of Code progress. Example Table 2021 Results Day

Kevin Duff 36 Dec 30, 2022
Telegram bot for our internal organizers tasks

Welcome to ppm-telegram-bot 👋 Telegram Bot Platform integration for bot commands processing. We use it for our internal @piterpy-meetup needs, basica

PiterPy Meetup 10 Jul 28, 2022
Pluggable Telethon - Telegram UserBot

A stable pluggable Telegram userbot, based on Telethon.

Team Ultroid 2.3k Dec 30, 2022
Cryptocurrency Prices Telegram Bot For Python

Cryptocurrency Prices Telegram Bot How to Run Set your telegram bot token as environment variable TELEGRAM_BOT_TOKEN: export TELEGRAM_BOT_TOKEN=your_

Sina Nazem 3 Oct 31, 2022