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.0.post3-cp314-cp314t-win_amd64.whl (1.4 MB view details)

Uploaded CPython 3.14tWindows x86-64

pyeventengine-0.6.0.post3-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (2.7 MB view details)

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

pyeventengine-0.6.0.post3-cp314-cp314-win_amd64.whl (1.3 MB view details)

Uploaded CPython 3.14Windows x86-64

pyeventengine-0.6.0.post3-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (2.7 MB view details)

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

pyeventengine-0.6.0.post3-cp313-cp313-win_amd64.whl (1.3 MB view details)

Uploaded CPython 3.13Windows x86-64

pyeventengine-0.6.0.post3-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (2.7 MB view details)

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

pyeventengine-0.6.0.post3-cp312-cp312-win_amd64.whl (1.3 MB view details)

Uploaded CPython 3.12Windows x86-64

pyeventengine-0.6.0.post3-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (2.7 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.0.post3-cp314-cp314t-win_amd64.whl.

File metadata

File hashes

Hashes for pyeventengine-0.6.0.post3-cp314-cp314t-win_amd64.whl
Algorithm Hash digest
SHA256 e1c09a66fd456df358d552f072e4bb53ace21f5caf1313396d57d6a60b234e08
MD5 15a70d866c8d78dcebe8e33b27649c11
BLAKE2b-256 2a2bb229194ec1616ace3db971e5799b09ad59912cf4342ff20446af5db0a876

See more details on using hashes here.

File details

Details for the file pyeventengine-0.6.0.post3-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.0.post3-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 1d9ec1387209b5de2f6353f25397a453dadfedd5b2ef76e4b70a3e9cc191d3c8
MD5 9518c9e3424437c6c6237f8522e3328f
BLAKE2b-256 8ac1225c58120deaea903ca492de58e3d2a55ce0dfd33c4a5f589ea25d8b612e

See more details on using hashes here.

File details

Details for the file pyeventengine-0.6.0.post3-cp314-cp314-win_amd64.whl.

File metadata

File hashes

Hashes for pyeventengine-0.6.0.post3-cp314-cp314-win_amd64.whl
Algorithm Hash digest
SHA256 31fb49a570031a1288c3b0dc090a27e129bd544031689a2866c703122e84b77f
MD5 1d4d7acacf44c301f3e8cb0bfdbbd310
BLAKE2b-256 3512ef58f1cb2a2314952859912a8f836a6dea950af64e2f3a8d0b6d8113e573

See more details on using hashes here.

File details

Details for the file pyeventengine-0.6.0.post3-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.0.post3-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 97d49e7f365f55393c2f384fc4c697d73f84ce124daff5c078387649040a2590
MD5 9335e1a05c8a368c6d5015ab8a817077
BLAKE2b-256 f8663056de65b077f3c6dfe3c77d982186d98e1bfd50056f5132843bc8c954ca

See more details on using hashes here.

File details

Details for the file pyeventengine-0.6.0.post3-cp313-cp313-win_amd64.whl.

File metadata

File hashes

Hashes for pyeventengine-0.6.0.post3-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 bf9929ba2ee4c54bb0af26202a042b94ed762492db9387e1056719df8302bc7c
MD5 df3137be0c542f65438a19b395f57e03
BLAKE2b-256 03ad978e6f3b3d4f228ac231dcea070448e34c1f70b239e38f1635c2eda97303

See more details on using hashes here.

File details

Details for the file pyeventengine-0.6.0.post3-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.0.post3-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 db802b9067be069087e389d78cf0e5632d7c92b876e1a3097b2ceec8d0a99af1
MD5 62e33505dc699958f3b4bc16cc656852
BLAKE2b-256 c47521a98aae1cf197eeb0628bc9c3114cca5bd04e60df68eaf568d5534e1cd9

See more details on using hashes here.

File details

Details for the file pyeventengine-0.6.0.post3-cp312-cp312-win_amd64.whl.

File metadata

File hashes

Hashes for pyeventengine-0.6.0.post3-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 aa461a8c91be324f3011b1789243d6899d76772b16e952301f12193665d69d5e
MD5 8301c7b1d11784d847c039bbc353b81f
BLAKE2b-256 06a7136bd4727304bf0de99a617b035c01571a8f7fade4532eb654f44eb7d606

See more details on using hashes here.

File details

Details for the file pyeventengine-0.6.0.post3-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.0.post3-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 fcdf1defe3e48d808954172d5998a5a1f67d5e0f389b252153470819f6dc7e1c
MD5 f9c7307ef10679cc55e8ccf86bc1ac03
BLAKE2b-256 1201ecf5a35dd51c46b444d46e940c7b62e42f9f62b73d1d3affbc903c215497

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

0.6.2

12 files

This release

0.6.0.post3 This release

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