Overview

This document describes how to set up your development environment to build and test the Valkey GLIDE Python wrapper.

The Valkey GLIDE Python wrapper consists of both Python and Rust code. Rust bindings for Python are implemented using PyO3, and the Python package is built using maturin. The Python and Rust components communicate using the protobuf protocol.

📁 Python Project Structure

---

The python/ directory contains three separate components:

🔹 glide-async/

• Purpose: Async client for Valkey, implemented as a hybrid Python/Rust project.
• Rust bindings: via PyO3, defined in valkey-glide/python/glide-async/src/lib.rs.
• Communication Layer: Communicates with Glide’s Rust core using a Unix Domain Socket (UDS).
• Import path: import glide
• PyPI package name: valkey-glide
• Build backend: Maturin (Rust-based)

🔹 glide-sync/

• Purpose: Sync client for Valkey, implemented via CFFI, built with setuptools.
• Rust bindings: via CFFI, defined in valkey-glide/ffi/src/lib.rs.
• Communication Layer: Communicates with Glide’s Rust core via direct FFI.
• Import path: import glide_sync
• PyPI package name: valkey-glide-sync
• Build backend: setuptools (C-based)

🔹 glide-shared/

• Purpose: Shared Python logic used by both clients — includes command builders, exceptions, constants, protobuf message handling, and more.
• Import path: import glide_shared
• Installation: Installed locally via pip3 install valkey-glide/python/glide-shared during each client’s build process. Not published separately to PyPI.

🧱 High-Level Folder Structure

python/
├── glide-async/            # Async client (PyO3 + Maturin)
│   ├── Cargo.toml
│   ├── pyproject.toml
│   ├── python/glide/       # Python code for async client
│   └── src/                # Rust code with PyO3 bindings
├── glide-sync/             # Sync client (CFFI + setuptools)
│   ├── pyproject.toml
│   └── glide_sync/         # Python code for sync client
├── glide-shared/           # Shared logic used by both clients
│   ├── pyproject.toml
│   └── glide_shared/       # Shared source code
└── tests/                  # Shared test suite
ffi/
├── src/                    # Rust code provides a C-compatible FFI (used in glide-sync)

📦 Packaging and Installation Notes

• During development, glide_shared must be installed locally (editable or standard install).
• Each client is built and released independently, with its own isolated package name and pyproject.toml.
• Shared logic remains fully decoupled from both clients and reusable between them.