Development

Requirements

• Python 3.9+
• Rust 1.70+
• uv package manager
• Linux or MacOS

Before you start: Please make sure you can successfully build and run the Fluss Rust client on your machine. The Python bindings require a working Fluss Rust backend and compatible environment.

Install Development Dependencies

cd bindings/python
uv sync --all-extras

Build Development Version

source .venv/bin/activate
uv run maturin develop

Build Release Version

uv run maturin build --release

Code Formatting and Linting

uv run ruff format python/
uv run ruff check python/

Type Checking

uv run mypy python/

Stub Drift Check

The public API is typed in fluss/__init__.pyi. Because that stub is hand-written while the runtime classes come from the compiled PyO3 module, the two can drift apart. stubtest (shipped with mypy) compares them and is run in CI. After changing the binding's public surface, rebuild the module and run:

uv sync --extra dev --no-install-project
uv run --no-sync maturin develop --uv
uv run --no-sync python -m mypy.stubtest fluss \
  --mypy-config-file pyproject.toml \
  --allowlist stubtest-allowlist.txt

stubtest-allowlist.txt holds the few differences that are inherent to PyO3 and cannot be expressed in the stub. Keep it minimal — stubtest treats an unused allowlist entry as an error, so stale lines must be removed.

Run Examples

Each example is standalone and runnable on its own. They default to a local cluster at 127.0.0.1:9123; override with FLUSS_BOOTSTRAP_SERVERS.

uv run python example/log_table.py
uv run python example/pk_table.py
uv run python example/complex_types.py
uv run python example/partitioned_table.py
uv run python example/partitioned_kv_table.py

# Point at a specific cluster:
FLUSS_BOOTSTRAP_SERVERS=host:port uv run python example/log_table.py

CI runs every example against an ephemeral test cluster via test/test_examples.py, which auto-discovers any example/*.py exposing a callable main(bootstrap_servers). New examples are checked automatically with no test changes.

Build API Docs

uv run pdoc fluss

Release

# Build wheel
uv run maturin build --release

# Publish to PyPI
uv run maturin publish

Project Structure

bindings/python/
├── Cargo.toml            # Rust dependency configuration
├── pyproject.toml         # Python project configuration
├── README.md              # User guide
├── DEVELOPMENT.md         # This file
├── API_REFERENCE.md       # API reference
├── src/                   # Rust source code (PyO3 bindings)
│   ├── lib.rs
│   ├── config.rs
│   ├── connection.rs
│   ├── admin.rs
│   ├── table.rs
│   └── error.rs
├── fluss/                 # Python package
│   ├── __init__.py
│   ├── __init__.pyi       # Type stubs
│   └── py.typed
├── example/                       # Standalone, CI-checked examples
│   ├── log_table.py
│   ├── pk_table.py
│   ├── complex_types.py
│   ├── partitioned_table.py
│   └── partitioned_kv_table.py
└── test/
    └── test_examples.py           # Runs every example against the cluster

License

Apache 2.0 License