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
# From PyPI (pre-compiled wheels available)
pip install PyEventEngine
# From source (requires C compiler + Cython ≥ 3.0)
git clone https://github.com/BolunHan/PyEventEngine.git
cd PyEventEngine
# Build + install
./build.sh -i
# Or via Makefile:
make build && pip install -U . --no-build-isolation
# Or step by step:
python setup.py build_ext --inplace --verbose --force
pip install -U . --no-build-isolation
See the Installation Guide for platform-specific prerequisites, compile-time macros, and troubleshooting.
Quick Start
import time
from event_engine import EventEngine, Topic
# 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 time for processing
engine.stop()
print(calls) # [('a test sub-topic', 'Demo.Test'), ('a live sub-topic', 'Demo.Live')]
Timers (EventEngineEx)
import time
from event_engine import 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))
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 propagates 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). Check the active backend:
from event_engine import USING_FALLBACK
print('Using native fallback?', USING_FALLBACK)
Development
# Clone and build in-place
git clone https://github.com/BolunHan/PyEventEngine.git
cd PyEventEngine
./build.sh -i
# Run tests
python -m pytest demo/
# Performance benchmarks
python demo/native_performance_test.py
python demo/capi_performance_test.py # requires compiled extensions
Build scripts
| Command | Effect |
|---|---|
./build.sh -i |
Clean + build + install |
./build.sh -l |
List compile-time macros |
make build |
Clean + build in-place |
make clean-all |
Deep clean (removes .c/.so) |
Documentation
Full documentation: https://bolunhan.github.io/PyEventEngine/
Build locally:
pip install sphinx furo sphinx-autodoc-typehints
cd docs
sphinx-build -M html . _build
# Open _build/html/index.html
License
MIT — see LICENSE.
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.post2-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.
File metadata
- Download URL: pyeventengine-0.6.0.post2-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 |
9fad9ecda10ce75ca8b7751f69f3a8ed614d9855f598fb1d3685bee306be8125
|
|
| MD5 |
f6ab9c1ae5a32d47849a550ce33166e5
|
|
| BLAKE2b-256 |
063a4c33235d42307b1ffef3f1a553773fab48b5b9d23e890f5336b828168791
|
File details
Details for the file pyeventengine-0.6.0.post2-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.
File metadata
- Download URL: pyeventengine-0.6.0.post2-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 |
6bbe993a9d9b0d2a2cf24248f97bed07007dae6e9dd8e04a47c3faba5c4bbdbd
|
|
| MD5 |
33f8b978db752ea44e02e93f38de972a
|
|
| BLAKE2b-256 |
553d7694c1d21e36438d120e8a00c1dd717618133079930021d50ca411356d8a
|
File details
Details for the file pyeventengine-0.6.0.post2-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.
File metadata
- Download URL: pyeventengine-0.6.0.post2-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 |
2a37dddf93e8917b98464d4b698e841360a54437c02baff8688c75315afefa9a
|
|
| MD5 |
aa28389f85dc8ca12c1976158a3cb3a4
|
|
| BLAKE2b-256 |
1dc943d3812d97bb60509fe7313f61a6bdacbc938b46c7b243dfd16834f3ddc1
|
File details
Details for the file pyeventengine-0.6.0.post2-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.
File metadata
- Download URL: pyeventengine-0.6.0.post2-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 |
9f2702639007d0f2468f9359bb564d800448280dbcede33b3eb8875135087308
|
|
| MD5 |
9ba122f2d22d9859f564a9846cc6feb6
|
|
| BLAKE2b-256 |
0bc258e7aa00a913483a91f8507d772ede6f2bd90fca1dfd6da59f783ec8a98c
|
