KeyRing¶

FragmentedKeyRing is a factory for defining reusable key templates and producing configured StandardKey instances.

Basic Usage¶

from redis import Redis
from fragmented_keys import FragmentedKeyRing, RedisHandler, MemoryHandler

redis_handler = RedisHandler(Redis())
memory_handler = MemoryHandler()

ring = FragmentedKeyRing(
    global_options={"type": "standard"},
    global_tag_options={
        "universe": {"type": "constant", "version": 1.0},
    },
    default_cache_handler="redis",
    cache_handlers={
        "redis": redis_handler,
        "memory": memory_handler,
    },
    default_prefix="MyApp",
)

Defining Key Templates¶

Use define_key to register a template. Each parameter is either a tag name string or a dict with at least a "tag" key and optional overrides.

ring.define_key("Users", [
    "universe",
    {"tag": "planet", "cache_handler": "memory"},
    "city",
])

Retrieving Key Objects¶

# Positional values map 1:1 to the defined parameters
key_obj = ring.get_key_obj("Users", ["MilkyWay", "Earth", "Chicago"])
cache_key = key_obj.get_key_str()

Dynamic Accessor¶

A convenience syntax is available via __getattr__:

# Equivalent to ring.get_key_obj("Users", ["MilkyWay", "Earth", "Chicago"])
key_obj = ring.get_users_key_obj("MilkyWay", "Earth", "Chicago")

The method name follows the pattern get_<key_name>_key_obj. Key name matching is case-insensitive and ignores underscores.

Tag Options¶

Options are merged in priority order:

global_options → global_tag_options[tag_name] → per-key overrides

Option	Type	Description
`type`	`"standard"` \| `"constant"`	Tag type (default: `"standard"`)
`version`	`float`	Initial version value
`cache_handler`	`str`	Handler key from `cache_handlers` dict
`prefix`	`str`	Override global prefix for this tag

Constructor¶

FragmentedKeyRing(
    global_options: dict | None = None,        # Default options for all tags
    global_tag_options: dict | None = None,     # Per-tag-name option overrides
    default_cache_handler: str = "memory",      # Default handler key
    cache_handlers: dict | None = None,         # Named handler instances
    default_prefix: str = "DefaultPrefix",      # Key namespace prefix
)