Installation

PyEventEngine can be installed from PyPI or built from source. The package includes both a Cython-accelerated implementation and a pure Python fallback.

Quick Install (PyPI)

The simplest way to install PyEventEngine:

pip install PyEventEngine

This will install the package with pre-compiled wheels if available for your platform, or automatically fall back to the pure Python implementation.

Install from Source

To get the latest development version:

pip install git+https://github.com/BolunHan/PyEventEngine.git

Building with Cython (Linux/macOS)

To build the Cython extensions from source on Linux or macOS, you’ll need:

  • Python 3.12 or later

  • GCC or Clang compiler

  • Cython (automatically installed as build dependency)

Step 1: Install build dependencies

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install build-essential python3-dev

# macOS (with Homebrew)
xcode-select --install
brew install python

Step 2: Clone and build

git clone https://github.com/BolunHan/PyEventEngine.git
cd PyEventEngine

# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Install with Cython compilation
pip install -e .

Step 3: Verify installation

from event_engine import USING_FALLBACK, EventEngine
print(f"Using fallback: {USING_FALLBACK}")  # Should be False if compiled
print(f"EventEngine: {EventEngine}")

If USING_FALLBACK is False, you’re using the compiled Cython version.

Building on Windows

Building Cython extensions on Windows requires Microsoft Visual C++ Build Tools.

Step 1: Install Visual C++ Build Tools

Download and install from: https://visualstudio.microsoft.com/visual-cpp-build-tools/

During installation, select: - “Desktop development with C++” - Windows 10 SDK (or later)

Step 2: Clone and build

git clone https://github.com/BolunHan/PyEventEngine.git
cd PyEventEngine

# Create virtual environment
python -m venv venv
venv\Scripts\activate

# Install with Cython compilation
pip install -e .

Step 3: Verify installation

from event_engine import USING_FALLBACK
print(f"Using fallback: {USING_FALLBACK}")

Note

If compilation fails on Windows, PyEventEngine will automatically fall back to the pure Python implementation. All features work identically, but performance may be reduced.

Using the Pure Python Fallback

If you explicitly want to use the pure Python implementation (e.g., for debugging or platforms without a C compiler):

# Install without attempting compilation
pip install --no-binary :all: PyEventEngine

Or import directly from the native module:

from event_engine.native import EventEngine, Topic

# This always uses pure Python, even if Cython is available
engine = EventEngine()

Development Installation

For development work with tests and documentation:

git clone https://github.com/BolunHan/PyEventEngine.git
cd PyEventEngine

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -e ".[dev,docs]"

# Run tests
python -m pytest demo/

# Build documentation
cd docs
make html
# Open docs/_build/html/index.html in a browser

Requirements

  • Python: 3.10 or later

  • Required packages: None (stdlib only for pure Python)

  • Optional build dependencies: Cython >= 3.0, C compiler

  • Optional dev dependencies: pytest, sphinx, furo (for docs)

Platform Support

PyEventEngine is tested on:

  • Linux: Ubuntu 20.04+, Debian 11+, RHEL 8+

  • macOS: 11.0+ (Big Sur and later)

  • Windows: Windows 10/11 with Visual C++ Build Tools

Both x86_64 and ARM64 (Apple Silicon) are supported.

Troubleshooting

Compilation fails on Linux

# Install development headers
sudo apt-get install python3-dev

# Or use fallback
PEE_NO_CYTHON=1 pip install PyEventEngine

Compilation fails on Windows

  • Ensure Visual C++ Build Tools are installed

  • Try running from “Developer Command Prompt for VS”

  • Or use the pure Python fallback (automatically used if compilation fails)

Import errors

# Check what's actually installed
import event_engine
print(event_engine.__version__)
print(event_engine.USING_FALLBACK)

# If imports fail, try reinstalling
pip install --force-reinstall PyEventEngine

Performance concerns

If USING_FALLBACK is True and you need maximum performance:

  1. Ensure you have a C compiler installed

  2. Reinstall with pip install --force-reinstall --no-cache-dir PyEventEngine

  3. Check for compilation errors in the output

For benchmarking, see Examples for performance test examples.