CyRedis

High-performance Redis client for Python, built with Cython and the vendored hiredis C library. No redis-py. No RESP parsing in Python. All connection I/O goes through native C.

• Full Redis command coverage — strings, lists, sets, sorted sets, hashes, streams, HyperLogLog, bitmaps, pub/sub, scripting, transactions
• Sync and async — every operation has a sync path and an *_async coroutine; async path uses run_in_executor over the same native pool
• TLS — native via hiredis_ssl/OpenSSL, including mutual TLS and SNI; connection retry with exponential backoff built in
• Cluster and Sentinel — native CyRedisCluster (slot map, MOVED/ASK, cross-slot fan-out) and CySentinel (master discovery, failover re-resolve)
• Redis Streams — async iterators for SUBSCRIBE, PSUBSCRIBE, and XREAD (docs/streams.md)
• Lua scripting and Redis Functions — pre-built scripts plus a script manager for atomic multi-key operations (docs/scripting.md)
• Modules — JSON, full-text/vector search and graph wrappers with capability probing, so a missing module raises a clear ModuleUnavailableError (docs/advanced.md, docs/valkey.md)
• Distributed primitives — distributed locks and cross-process shared dicts (CySharedDict)

The web layer, auth (JWT/sessions/2FA), worker coordination, RPC/reliable queues, the ClickHouse bridge, probabilistic/AI structures, the game engine and the pgcache Redis module are not part of this package. They live in experimental/ in the repository, are unsupported, and are built separately — see experimental/README.md.

cy-redis is not on PyPI yet — 0.2.0 will be the first release. Until that tag exists, install from source:

git clone https://github.com/Ugbot/CyRedis.git && cd CyRedis
uv sync                                # test + build tooling (Cython, setuptools, ...)
uv pip install --no-build-isolation -e .

Building from source needs a C/C++ toolchain and make; the vendored hiredis builds automatically. OpenSSL development headers are needed for TLS (see below). Once released, pip install cy-redis will install binary wheels for CPython 3.9–3.14 on Linux (x86_64/aarch64, glibc and musl) and macOS (arm64 on 14.0+, x86_64 on 15.0+), with the sdist as the fallback elsewhere.

The core client has no runtime dependencies. One optional extra, async (uvloop): uv pip install --no-build-isolation -e ".[async]".

Developer loop (make help lists everything):

make build          # Cython extensions in place
make test-unit      # no server needed
make test           # needs a Redis or Valkey on REDIS_HOST/REDIS_PORT
make lint           # what CI gates on
make dist-check     # sdist + wheel, twine check, content guard

TLS rides on the vendored hiredis_ssl + OpenSSL — no Python-level socket wrapping. PyPI wheels always ship it; source builds need OpenSSL development headers (the build falls back to plain-TCP-only with a warning if they are missing).

from cy_redis import CyRedisClient

client = CyRedisClient(
    host="redis.example.com", port=6380,
    use_tls=True,
    ssl_ca_certs="/path/to/ca.pem",     # omit to use the system trust store
    ssl_certfile="/path/to/client.crt", # optional: mutual TLS
    ssl_keyfile="/path/to/client.key",
    ssl_server_name="redis.example.com",  # optional: SNI override
)

Connection establishment also retries transient TCP failures with exponential backoff (connect_retries=2, connect_backoff=0.1 by default); TLS and AUTH errors are configuration problems and are never retried.

from cy_redis import CyRedisClient

client = CyRedisClient(host="localhost", port=6379)

client.set("greeting", "hello")
print(client.get("greeting"))   # "hello"

# Async
import asyncio
async def main():
    await client.set_async("key", "value")
    print(await client.get_async("key"))
asyncio.run(main())

See docs/getting-started.md for connection options, pooling, and the first 10 minutes.

cy_redis/                      — the published package
  core/           — CyRedisClient, connection pool, protocol negotiation,
                    cluster, sentinel, TLS, async core
  features/       — distributed locks, functions, script_manager,
                    capabilities, json_ops, search, graph
  data/           — shared_dict (CySharedDict, CySharedDictManager)
  lua_scripts/    — bundled Lua sources
  utils/          — redis_iterators (stream/pubsub async generators)
hiredis/                       — vendored hiredis C library (built into every extension)
experimental/                  — unsupported, not packaged; separate build
  cyredis_experimental/
    auth/ web/ workers/ communication/ game/ extras/
  pgcache/        — PostgreSQL read-through cache Redis module
  tests/

• Python 3.9+
• Cython >= 3.0
• A running Redis or Valkey instance

No runtime Python dependencies. All Redis communication goes through the vendored hiredis C library compiled into each extension.

MIT