Quick Start

Installation

uv add fragmented-keys

Or with pip:

pip install fragmented-keys

Basic Usage

from redis import Redis
from fragmented_keys import Configuration, RedisHandler, StandardTag, StandardKey

# Setup
client = Redis(host="127.0.0.1", port=6379)
Configuration.set_default_cache_handler(RedisHandler(client))
Configuration.set_global_prefix("MyApp")

# Create tags
user_tag = StandardTag("User", "42")
city_tag = StandardTag("City", "chicago")

# Build a composite key
key = StandardKey("UserDashboard", [user_tag, city_tag])
cache_key = key.get_key_str()  # MD5 hex digest

# Use it with Redis
data = client.get(cache_key)
if data is None:
    data = fetch_from_database()
    client.set(cache_key, data)

# Invalidate all keys depending on User:42
user_tag = StandardTag("User", "42")
user_tag.increment()
# Next call to get_key_str() with User:42 will produce a different key

How It Works

  1. Each StandardTag stores its current version in the cache backend under the key {tag}_{instance}{prefix}.

  2. When building a composite key, StandardKey bulk-fetches all tag versions using get_multi (grouped by handler) for efficiency. ConstantTag instances are skipped in bulk fetches since their version is fixed.

  3. The final key is md5("{keyName}_{groupId}:t{tag1Name}:v{version1}:t{tag2Name}:v{version2}...").

  4. Calling tag.increment() bumps the stored version by 0.1, so subsequent key builds produce a different MD5 — effectively invalidating all cached data under the old key without deleting it.