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-0.6.2-cp315-cp315t-win_amd64.whl (1.7 MB view details)

Uploaded CPython 3.15tWindows x86-64

pyeventengine-0.6.2-cp315-cp315t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (3.4 MB view details)

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

pyeventengine-0.6.2-cp315-cp315-win_amd64.whl (1.7 MB view details)

Uploaded CPython 3.15Windows x86-64

pyeventengine-0.6.2-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (3.3 MB view details)

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

pyeventengine-0.6.2-cp314-cp314t-win_amd64.whl (1.7 MB view details)

Uploaded CPython 3.14tWindows x86-64

pyeventengine-0.6.2-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (3.4 MB view details)

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

pyeventengine-0.6.2-cp314-cp314-win_amd64.whl (1.7 MB view details)

Uploaded CPython 3.14Windows x86-64

pyeventengine-0.6.2-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (3.3 MB view details)

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

pyeventengine-0.6.2-cp313-cp313-win_amd64.whl (1.6 MB view details)

Uploaded CPython 3.13Windows x86-64

pyeventengine-0.6.2-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (3.3 MB view details)

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

pyeventengine-0.6.2-cp312-cp312-win_amd64.whl (1.6 MB view details)

Uploaded CPython 3.12Windows x86-64

pyeventengine-0.6.2-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (3.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-0.6.2-cp315-cp315t-win_amd64.whl.

File metadata

File hashes

Hashes for pyeventengine-0.6.2-cp315-cp315t-win_amd64.whl
Algorithm Hash digest
SHA256 e75ac3a57d751915e70200ab393f929ecc355c72c7e965f763efa4320cefb3bb
MD5 09ec20c000142304c2529ade1e49872b
BLAKE2b-256 480c727b191376cf745f73023e542c98b7036565e8f27190659d8a21cbc862c1

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for pyeventengine-0.6.2-cp315-cp315t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 01b81f2985b69d95ee33ded50e2c3afa1f268ddaa4d7464bd18eb6ef93fec461
MD5 47f44bd1131926a670525d9e8bb6ecc8
BLAKE2b-256 3ba5da84eeceac4034928abdc65aca4db279f11fb3e5424651ec99d66cbae50f

See more details on using hashes here.

File details

Details for the file pyeventengine-0.6.2-cp315-cp315-win_amd64.whl.

File metadata

File hashes

Hashes for pyeventengine-0.6.2-cp315-cp315-win_amd64.whl
Algorithm Hash digest
SHA256 c3c0e50113534c4112fffcffed6a2ad505a05fa5c60266e9ef3916fb5f464007
MD5 4a234ecdc2052a3a5304b0f613b983a2
BLAKE2b-256 2217d4ae1a2df49d962199d75f7fb371012393033d37c0f773ab219a8e422cd2

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for pyeventengine-0.6.2-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 1a106f313fcabf9b35e9dd476c4e66650c1b124460e1872bf523cce7c7790c7f
MD5 0b18f34f5688f9638813bdb4848d2afd
BLAKE2b-256 c20b706dd8eb9258928e8b522c01c1fe65fd6f67fe7979f1ab480fd6ced9c773

See more details on using hashes here.

File details

Details for the file pyeventengine-0.6.2-cp314-cp314t-win_amd64.whl.

File metadata

File hashes

Hashes for pyeventengine-0.6.2-cp314-cp314t-win_amd64.whl
Algorithm Hash digest
SHA256 b61f3a3c8d6e83081986983e2b48e4963471823812a805194c8e3b67eaeb7419
MD5 fe673e1aa098f4a06b370e8d5661c55b
BLAKE2b-256 4d94c2ed5934c08c4f28f3bced38742affc5064d5466e5fed3aa16a45d1d4b12

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for pyeventengine-0.6.2-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 cd0a08fa5cbdaaa7370c78e970e69aa34f652f277fafbe38715d40ead4c2fadb
MD5 96235e67396202993354b48e1c39500d
BLAKE2b-256 dfb6a5a3a48a2ee07249969578e8da951f478dd350d7cf3efd459d40139ce132

See more details on using hashes here.

File details

Details for the file pyeventengine-0.6.2-cp314-cp314-win_amd64.whl.

File metadata

File hashes

Hashes for pyeventengine-0.6.2-cp314-cp314-win_amd64.whl
Algorithm Hash digest
SHA256 24fa40ffa8dce5826720194fd47609e9447533da0603ce5972e17c3c463d1539
MD5 f28310f7668a0f2334e71b347d63771c
BLAKE2b-256 011a7c6737eaab0b6b811dc1a3f97a8f37f938434403a0c1386423ddc6ce3094

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for pyeventengine-0.6.2-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 07f25a5cae3273362657ad3709efcf70ed049324ebb5d02bcff1f41a37ee6012
MD5 65001e29cf0be8bbcb9517dcf158e421
BLAKE2b-256 4ad23dfcfe905e705f7551dd3bb7492898ae175b4e6b4cf35925aa04cb6a772a

See more details on using hashes here.

File details

Details for the file pyeventengine-0.6.2-cp313-cp313-win_amd64.whl.

File metadata

File hashes

Hashes for pyeventengine-0.6.2-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 4eaebe693a5980ede857dc91ee378a2b08bce1e8f2e2a6c044ce0e73cceee50c
MD5 2ffa55f78dfda47f0e0097bab8384d6e
BLAKE2b-256 da535966b3b05d17bedbc17ad1712f93ea0f1dcf10d0f9e0864b6e890ab215c6

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for pyeventengine-0.6.2-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 4fcb74ed0b40e78d26bedc9f6fa863e6a3fc0c3dc61ea733017c9816370014e4
MD5 dbfd8af49d0c63aa9e3c6d21394a5258
BLAKE2b-256 e4cf708d69b827bc58a3e80911a646fc0b266c9d3f1efb93a88fa2a64c1cc956

See more details on using hashes here.

File details

Details for the file pyeventengine-0.6.2-cp312-cp312-win_amd64.whl.

File metadata

File hashes

Hashes for pyeventengine-0.6.2-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 13be8c391d884b8c1902a4a338121698f9353aa976b14918c9af87d8c757a109
MD5 85046a4aa4abcd02c79ff5495a7981fa
BLAKE2b-256 829e15c9eb6096dfea6e38ee5e09cce0fb812185743a8f025c0c80849a31c9bd

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for pyeventengine-0.6.2-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 2b787cf78a410d403a751c8d82a10307160fa500246e1d5c67099f62df69a248
MD5 11cae1dac55831711df385c0478dac07
BLAKE2b-256 cd8eeee0c22076af2ba76f1d5aac77791493f7c0fa053e6cbe9b6fd663fef8c8

See more details on using hashes here.

Release history Release notifications | RSS feed

1.0.2

12 files

1.0.1

6 files

1.0.0

6 files

0.6.2.post1

12 files

This release

0.6.2 This release

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