PyEventEngine
High-performance, topic-driven event engine for Python with a Cython-accelerated core and a native Python fallback.
- Fast publish/subscribe event routing by topic (exact + generic wildcard/pattern matching)
- Clean, typed API with drop-in fallback when C extensions are unavailable
- Built-in timers, handler stats (EventHookEx), and convenient formatting helpers
Installation
pip install PyEventEngine
Or install from source:
pip install git+https://github.com/BolunHan/PyEventEngine.git
Quick Start
import time
from event_engine import EventEngine, Topic, EventHook
# Create and start the engine
engine = EventEngine(capacity=8192)
engine.start()
# Register a handler for an exact topic
exact = Topic('Demo.Hello')
def hello_handler(name: str, topic=None):
print(f"Hello {name} from {topic.value if topic else 'N/A'}")
engine.register_handler(exact, hello_handler)
# Publish a message
engine.put(exact, 'World')
# Clean up
time.sleep(0.1)
engine.stop()
engine.clear()
Generic topics (wildcards/patterns)
import time
from event_engine import Topic, EventEngine
engine = EventEngine()
pattern = Topic('Demo.{what}')
calls = []
def f(what: str, topic=None):
calls.append((what, topic.value))
engine.register_handler(pattern, f)
engine.start()
engine.put(Topic('Demo.Test'), 'a test sub-topic')
engine.put(Topic('Demo.Live'), 'a live sub-topic')
time.sleep(0.1) # allow some time for processing
engine.stop()
print(calls) # [('a test sub-topic', 'Demo.Test'), ('a live sub-topic', 'Demo.Live')]
Timers (EventEngineEx)
from event_engine import EventEngine, EventEngineBase, EventEngine as EventEngineEx, Topic
engine = EventEngineEx(capacity=4096)
engine.start()
# Create a 1-second timer topic and subscribe
timer_topic = engine.get_timer(1.0)
engine.register_handler(timer_topic, lambda **kw: print('tick', kw))
# ... run a little while
import time; time.sleep(3)
engine.stop(); engine.clear()
Logging
By default, the package uses a colored logger under event_engine.base. To integrate with your
application's logging, call set_logger once after import. It will propagate to submodules.
import logging
from event_engine import set_logger
logger = logging.getLogger('MyApp')
logger.setLevel(logging.INFO)
set_logger(logger)
Fallback behavior
On import, the package tries to use the Cython implementation (event_engine.capi). If that fails
(e.g., no compiler available), it automatically falls back to the native Python implementation (event_engine.native).
You can check the active backend via:
from event_engine import USING_FALLBACK
print('Using native fallback?' , USING_FALLBACK)
Development
- Run unit tests and demos under
demo/ - Native performance test:
python demo/native_performance_test.py - CAPI performance test (requires compiled extensions):
python demo/capi_performance_test.py
Documentation
Full documentation is available at: https://bolunhan.github.io/PyEventEngine/ (auto-generated from main branch)
To build documentation locally, see docs/BUILD.md.
See demo/ for more examples: matching, timers, performance. Issues and PRs welcome!
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distributions
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file pyeventengine-0.6.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.
File metadata
- Download URL: pyeventengine-0.6.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
- Upload date:
- Size: 2.7 MB
- Tags: CPython 3.14t, manylinux: glibc 2.17+ x86-64, manylinux: glibc 2.28+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.14.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a163892471394b256416de051bb9c8cf3ee3f3f05f6ef4e6400bbacfec52fa97
|
|
| MD5 |
5cac61b50745d316c1b9c06cfcccc125
|
|
| BLAKE2b-256 |
45de8cd7800952754654dfd8e66855b9e6902abebc582d428cc6d17fd6ffe7a1
|
File details
Details for the file pyeventengine-0.6.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.
File metadata
- Download URL: pyeventengine-0.6.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
- Upload date:
- Size: 2.7 MB
- Tags: CPython 3.14, manylinux: glibc 2.17+ x86-64, manylinux: glibc 2.28+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.14.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6db7cee39881cd697bf7ecaffe30bd38401ba58d97a6602eb063a1e201538b67
|
|
| MD5 |
b4b10907999d4b9cc6212bf1553fed9b
|
|
| BLAKE2b-256 |
cc7e8c6f8bfba954ddbe94c5eb67505e526a9043d5ff3704851179c60b5f0f18
|
File details
Details for the file pyeventengine-0.6.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.
File metadata
- Download URL: pyeventengine-0.6.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
- Upload date:
- Size: 2.7 MB
- Tags: CPython 3.13, manylinux: glibc 2.17+ x86-64, manylinux: glibc 2.28+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.14.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
617c90213c44090c4542ede97fb2628349ec3c65059bca830116b37d1b8236e5
|
|
| MD5 |
925b308a39f09aff9aee0f614eab2a68
|
|
| BLAKE2b-256 |
7bbcaa733942ff7f4718e7a79f845f0b46411cf5dfe13a737b0e0ea8152fe0ba
|
File details
Details for the file pyeventengine-0.6.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.
File metadata
- Download URL: pyeventengine-0.6.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
- Upload date:
- Size: 2.7 MB
- Tags: CPython 3.12, manylinux: glibc 2.17+ x86-64, manylinux: glibc 2.28+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.14.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a7f733329dcccdd31257e0483fdd1a2f20ae4eb409b73d29082518fbf5bce26a
|
|
| MD5 |
3d3b0244ca881a0bc1e0e33f31686411
|
|
| BLAKE2b-256 |
80a10c09660417f723db8737d66e76e529dfe8f412a12362eb15c61d2f48b4f8
|
