kv-store-py 0.0.6

A simple wrapper for key-value stores supporting Python dict, Redis, Valkey, PostgreSQL, Memcached, and SQLite and other backend clients.

kv-store

A unified async interface for key-value stores in Python. Write your caching logic once, swap backends without changing code.

Installation

pip install kv-store-py

Or with uv:

uv add kv-store-py

For Redis support:

pip install kv-store-py redis

Quick Start

from kv_store import AbstractStore, RedisStore, PostgresStore

# Use Redis
store: AbstractStore = await RedisStore.from_url("redis://localhost:6379/0")
await store.set("key", "value", ttl=3600)
await store.get("key")

# Swap to Postgres - same interface
store: AbstractStore = await PostgresStore.from_url("postgresql://localhost/mydb")
await store.set_many({"k1": "v1", "k2": "v2"}, ttl=3600)
await store.get_many(["k1", "k2"])

# Distributed locking (supported by both Redis and Postgres)
async with store.lock("my-resource", timeout=30):
    # critical section
    pass

API Reference

All store implementations share the same async interface:

Single Key Operations

# Get a value (returns default if key doesn't exist or is expired)
value = await store.get(key: str, default: Any = None) -> Any

# Set a value with TTL in seconds
success = await store.set(key: str, value: Any, ttl: int) -> bool

# Delete a key
existed = await store.delete(key: str) -> bool

Batch Operations

# Get multiple keys at once
results = await store.get_many(
    keys: list[str],
    default: Any = None  # Single value or list of defaults per key
) -> dict[str, Any]

# Set multiple keys atomically
results = await store.set_many(items: dict[str, Any], ttl: int) -> dict[str, bool]

# Delete multiple keys
count = await store.delete_many(keys: list[str]) -> int

Distributed Locking

# Acquire a lock for mutual exclusion
async with store.lock("resource:id", timeout=30, blocking_timeout=10):
    # Critical section - only one process can execute this
    await perform_exclusive_operation()

Supported Backends

Backend	Status	Class
In-Memory	Available	InMemoryStore
Redis	Available	RedisStore
PostgreSQL	Available	PostgresStore
Valkey	Planned	-
SQLite	Planned	-
MySQL	Planned	-

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE for details.