PyEventEngine

docs pypi-linux pypi-windows

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.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.0.2)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for BolunHan from gravatar.com BolunHan

Credits

Author: Han Bolun

Requires

Python >=3.12

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

pyeventengine-1.0.0-cp315-cp315t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (4.4 MB view details)

Uploaded CPython 3.15tmanylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

pyeventengine-1.0.0-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (4.3 MB view details)

Uploaded CPython 3.15manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

pyeventengine-1.0.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (4.4 MB view details)

Uploaded CPython 3.14tmanylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

pyeventengine-1.0.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (4.3 MB view details)

Uploaded CPython 3.14manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

pyeventengine-1.0.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (4.2 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

pyeventengine-1.0.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (4.3 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

File details

Details for the file pyeventengine-1.0.0-cp315-cp315t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyeventengine-1.0.0-cp315-cp315t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 2120d93b3ae560472c049b41cf97c7dbb1d64ca45a7e57a5ecdb159a7d2612bd
MD5 f126862e2c917d58e0bdb188f57c7182
BLAKE2b-256 73bc3e17c40c87358491d9181a52c1ab8c37b285bf9ad4b5c3842fe39b59d60f

See more details on using hashes here.

File details

Details for the file pyeventengine-1.0.0-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyeventengine-1.0.0-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 1f8739bb2c49a2f0f9989f45feca219f6f7117741b9ba4504d75a771526e7053
MD5 ddbbdd740c1c7ae0deab10b919e846d5
BLAKE2b-256 e616ddaa4fdac621701a5910880d71940c4d6645c12790e28f150c8160be1f58

See more details on using hashes here.

File details

Details for the file pyeventengine-1.0.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyeventengine-1.0.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 b0a1189a0311c4b9e268053805fe5bce4720dbe0ce434b841029029f5f5aa879
MD5 2b684f9a4c6724af3f19bea334debfb1
BLAKE2b-256 33f3a8ead9fec69bd1105c8f80951d856dc85bb786b49b0ddbfdfe79198895f7

See more details on using hashes here.

File details

Details for the file pyeventengine-1.0.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyeventengine-1.0.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 9a2d442dd81e26969de3bd187ed4d53bc53cb9616a1871fbcdad2cbdcab87052
MD5 bfd7725057174ca0e09d631c8af5747f
BLAKE2b-256 8d1b854b76c7eac2fed348e2d2ca1604f7498730489a8d7300ea45c755c4ae88

See more details on using hashes here.

File details

Details for the file pyeventengine-1.0.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyeventengine-1.0.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 e3b6593cf30b8ac99c78aab04df682b8740142f3d1c3afc5458becca3267311b
MD5 3970e95af5c8b27bb33f5a789b990756
BLAKE2b-256 4b1bdaeaedf4e6111d2e15ae8c04ad75f4062d2d590ce84ab437491e9ad59169

See more details on using hashes here.

File details

Details for the file pyeventengine-1.0.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for pyeventengine-1.0.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 36deb8b004d7c023b4a4cc57330cc8b332d66ae5519bbb824fae67fa66af30c6
MD5 2314b1507516a5da8ecb7f7235183640
BLAKE2b-256 6fcaf6bffa88b549eb3ff8aa02d110fd9a4a982744f2924805f90f3a0e5016ea

See more details on using hashes here.

Release history Release notifications | RSS feed

1.0.2

12 files

1.0.1

6 files

This release

1.0.0 This release

6 files

0.6.2.post1

12 files

0.6.2

12 files

0.6.0.post3

8 files

0.6.0.post2

4 files

0.6.0.post1

4 files

0.6.0

4 files

0.5.2.post3

4 files

0.5.2.post1

4 files

0.5.2

4 files

0.5.1.post1

4 files

0.5.1

4 files

0.5.0.post2

4 files

0.5.0.post1

4 files

0.4.6.post1

4 files

0.4.6

4 files

0.4.5

4 files

0.4.4.post1

4 files

0.4.4

4 files

0.3.2

2 files

0.3.0.post5

1 file

0.3.0.post4

1 file

0.3.0.post3

1 file

0.3.0.post2

1 file

0.3.0.post1

1 file

0.3.0

1 file

0.2.1

1 file

0.1.4

1 file

0.1.2

1 file

0.1.1

1 file

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page