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

Uploaded CPython 3.15tWindows x86-64

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

Uploaded CPython 3.15Windows x86-64

pyeventengine-0.6.2.post1-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.post1-cp314-cp314t-win_amd64.whl (1.7 MB view details)

Uploaded CPython 3.14tWindows x86-64

pyeventengine-0.6.2.post1-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.post1-cp314-cp314-win_amd64.whl (1.7 MB view details)

Uploaded CPython 3.14Windows x86-64

pyeventengine-0.6.2.post1-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.post1-cp313-cp313-win_amd64.whl (1.6 MB view details)

Uploaded CPython 3.13Windows x86-64

pyeventengine-0.6.2.post1-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.post1-cp312-cp312-win_amd64.whl (1.6 MB view details)

Uploaded CPython 3.12Windows x86-64

pyeventengine-0.6.2.post1-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.post1-cp315-cp315t-win_amd64.whl.

File metadata

File hashes

Hashes for pyeventengine-0.6.2.post1-cp315-cp315t-win_amd64.whl
Algorithm Hash digest
SHA256 fdcaf4042176479a388d4ea5ce678c865341ea45e5d9efd2ed20a90d033b2888
MD5 580025c218503a34489b17e3a765c336
BLAKE2b-256 d3e04bf06def86ae56e1db1d5ad193b1c2f4280af1165ca0dd9a15bcf76a7e3d

See more details on using hashes here.

File details

Details for the file pyeventengine-0.6.2.post1-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.post1-cp315-cp315t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 271c10f17502a299607b5d732013c2afe830b778a799486d22719fc3fc92f48d
MD5 7773e54561bd9750928fab4678f47a10
BLAKE2b-256 d9c4e0d9e0742a1a1756160ff4d20d546479c57bc0f5b750c9f78d4365b9c426

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for pyeventengine-0.6.2.post1-cp315-cp315-win_amd64.whl
Algorithm Hash digest
SHA256 a2ec1907d37823419014c2ca8d30666acf7244c2403bd29ec70d5828041baaa3
MD5 c2fc906a6d5f671c2abc4e825d3a96a8
BLAKE2b-256 cc94756affe031a953096068b0170d747020bbee8a7ffc0419689805f7562680

See more details on using hashes here.

File details

Details for the file pyeventengine-0.6.2.post1-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.post1-cp315-cp315-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 23a44ba6003c91c3e9092fc7a38565aec5687a86182ebd05e142e6a1d2813a52
MD5 5415a1f16fdfa3b51a20409620961b9c
BLAKE2b-256 353edcd2552fdf1bc941a2b5b7458b4bff7c64fbf51a296eb74bbc8977e982fd

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for pyeventengine-0.6.2.post1-cp314-cp314t-win_amd64.whl
Algorithm Hash digest
SHA256 0a42fe67b53f324644ed36671716ca8d077ee26dc7ea13fc43696dfc3b357c9c
MD5 f358eb9a60b5d64df9f3ab81c2aaa2dc
BLAKE2b-256 7da5aac22539760b6496d3dfe1d0dae12415e8485fd3d7c2e06ef553e8df5db0

See more details on using hashes here.

File details

Details for the file pyeventengine-0.6.2.post1-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.post1-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 2d8f8bdb74c68d7da52556407648ce745ea7494dec27119f3e7b619bcfe168f7
MD5 06b4748f7b33dc986417043a969a7e98
BLAKE2b-256 4c1f3a8b4545ca2f7058368b509b769046877d2ce07fd9a1a9bc8ef7fc9f6641

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for pyeventengine-0.6.2.post1-cp314-cp314-win_amd64.whl
Algorithm Hash digest
SHA256 9f0de36c968db45f870a11b42d75525a624f4e9664834f915ddcea9a79144e39
MD5 81860713311777ceda991f8c3cc18213
BLAKE2b-256 781016f113bbeba0b1480b79d8a0cb052ab83dbbcc51b899b62caaf62555381b

See more details on using hashes here.

File details

Details for the file pyeventengine-0.6.2.post1-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.post1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 b8a3b2e3735837ddfcbb2607fee9d3317519cb07530f564cce20b4b0e0f14828
MD5 588dd6b63a238b92f48f9f581fed789b
BLAKE2b-256 eec3dc1081451b5610bbef1c5cfb035944d8098cd7e7c1d689be27516e56e285

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for pyeventengine-0.6.2.post1-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 80ea177639a7463ad50eeb3fa723a28387ad421841a04b8c07bb80ea1dbf0e90
MD5 ffb208b5ce0bac7396aa1259f51c989c
BLAKE2b-256 24443c5b50e4da36adb0ea62219d197054df9109081eba81ce52952fbcc8ddb9

See more details on using hashes here.

File details

Details for the file pyeventengine-0.6.2.post1-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.post1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 3918e72bcfd50f721ef3d7f2fa71bb280afb8bb7722405b955661bbdc03a40b7
MD5 953571a040a16fff1fa5666ba01da330
BLAKE2b-256 11750377e87d9d854dcf025a9cbdf8b1f8ada58a4877eb52a97409fd5c72e142

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for pyeventengine-0.6.2.post1-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 1eb8d668914e767dbdb97a5afd75c01273e5b7799815315a1c885238974ead79
MD5 476d8882daaf5e61db0186f393878c44
BLAKE2b-256 64f5f954c6895372a84b8e57e54352a5ede82794b598a35ee6bd39b649fc50ea

See more details on using hashes here.

File details

Details for the file pyeventengine-0.6.2.post1-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.post1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 e37b0d01e79cc772fb8bae2fd6cc93fa4a696e5529e9ba994b8f1cd1a8b9b9e5
MD5 727b15fcfdfdb9a6b916a2acae490a44
BLAKE2b-256 f025dbbd04599b06880a06df03dbbc000e6eb9e30119517aa82ea01f123e3345

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

This release

0.6.2.post1 This release

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