API Reference¶

Full auto-generated API documentation from source docstrings.

Protocols¶

class fragmented_keys.protocols.CacheHandler(*args, **kwargs)[source]¶

Bases: Protocol

Interface for cache backend implementations.

group_name()[source]¶

Return a unique identifier for this handler type.

Return type:: str

get(key)[source]¶

Fetch a single value by key. Returns None on miss.

Parameters:: key (str)
Return type:: str | None

set(key, value, ttl=None)[source]¶

Store a value, optionally with a TTL in seconds.

Parameters:

key (str)
value (str)
ttl (int | None)

Return type:

None

get_multi(keys)[source]¶

Fetch multiple values at once. Returns dict of found key-value pairs.

Parameters:: keys (list[str])
Return type:: dict[str, str]

class fragmented_keys.protocols.Tag(*args, **kwargs)[source]¶

Bases: Protocol

Interface for versioned tag-instance pairs.

get_tag_name()[source]¶

Return the tag identifier including instance and prefix.

Return type:: str

get_tag_version()[source]¶

Return the current version for this tag-instance.

Return type:: float

get_full_tag()[source]¶

Return the tag name with its current version.

Return type:: str

increment()[source]¶

Increment the tag version, invalidating dependent keys.

Return type:: None

reset_tag_version()[source]¶

Reset the tag version to a new value.

Return type:: None

set_tag_version(version, update=False)[source]¶

Manually set the tag version.

Parameters:

version (float)
update (bool)

Return type:

None

set_cache_handler(handler)[source]¶

Override the cache handler for this tag.

Parameters:: handler (CacheHandler)
Return type:: None

get_cache_handler()[source]¶

Return the cache handler used by this tag.

Return type:: CacheHandler

delegate_cache_query(group)[source]¶

Check if this tag’s version can be bulk-fetched with the given group.

Parameters:: group (str)
Return type:: bool

class fragmented_keys.protocols.Key(*args, **kwargs)[source]¶

Bases: Protocol

Interface for composite cache keys.

get_key_str(hash=True)[source]¶

Generate the composite cache key string.

Parameters:: hash (bool)
Return type:: str

add_tag(tag)[source]¶

Add a tag to this key’s composition.

Parameters:: tag (Tag)
Return type:: None

class fragmented_keys.protocols.KeyRing(*args, **kwargs)[source]¶

Bases: Protocol

Interface for key template factories.

define_key(key, params, globals=None)[source]¶

Define a reusable key template.

Parameters:

key (str)
params (list)
globals (dict | None)

Return type:

None

tag(tag, instance, options=None)[source]¶

Factory method for creating tag instances.

Parameters:

tag (str)
instance (str)
options (dict | None)

Return type:

Tag

Configuration¶

class fragmented_keys.configuration.Configuration[source]¶

Global configuration for the fragmented keys library.

classmethod set_default_cache_handler(handler)[source]¶

Parameters:: handler (CacheHandler)
Return type:: None

classmethod get_default_cache_handler()[source]¶

Return type:: CacheHandler

classmethod set_global_prefix(prefix)[source]¶

Parameters:: prefix (str)
Return type:: None

classmethod get_global_prefix()[source]¶

Return type:: str

classmethod reset()[source]¶

Reset configuration to defaults. Useful for testing.

Return type:: None

Tags¶

class fragmented_keys.tag.base.BaseTag(tag, instance='', version=None, handler=None, prefix=None)[source]¶

Bases: object

Base class for tag-instance version management.

A tag represents a logical grouping whose version is stored in a cache backend. Composite cache keys incorporate the tag’s current version so that incrementing a tag automatically invalidates every key that depends on it.

Parameters:

tag (str)
instance (str)
version (float | None)
handler (CacheHandler | None)
prefix (str | None)

get_tag_name()[source]¶

Return the cache key used to store this tag’s version.

Return type:: str

get_full_tag()[source]¶

Return a human-readable string of tag name + current version.

Return type:: str

get_cache_handler()[source]¶

Return type:: CacheHandler

set_cache_handler(handler)[source]¶

Parameters:: handler (CacheHandler)
Return type:: None

delegate_cache_query(group)[source]¶

Return True if this tag’s handler matches group (bulk-fetch).

Parameters:: group (str)
Return type:: bool

get_tag_version()[source]¶

Return type:: float

set_tag_version(version, update=False)[source]¶

Parameters:

version (float)
update (bool)

Return type:

None

increment()[source]¶

Return type:: None

reset_tag_version()[source]¶

Return type:: None

class fragmented_keys.tag.standard.StandardTag(tag, instance='', version=None, handler=None, prefix=None)[source]¶

Bases: BaseTag

A tag whose version is stored in cache and can be incremented.

Incrementing the version causes all composite keys that include this tag-instance to resolve to a new cache key, effectively invalidating the old cached values without deleting them.

Parameters:

tag (str)
instance (str)
version (float | None)
handler (CacheHandler | None)
prefix (str | None)

increment()[source]¶

Increment the tag version by 0.1 and persist.

Return type:: None

reset_tag_version()[source]¶

Reset the tag version to a new microtime-based value.

Return type:: None

class fragmented_keys.tag.constant.ConstantTag(tag, instance='', version=1.0, handler=None, prefix=None)[source]¶

Bases: BaseTag

A tag with a fixed version that never changes.

Useful for incorporating non-versionable data into composite keys. Calls to increment, reset_tag_version, and set_tag_version are no-ops.

Parameters:

tag (str)
instance (str)
version (float)
handler (CacheHandler | None)
prefix (str | None)

get_tag_version()[source]¶

Return type:: float

increment()[source]¶

Return type:: None

reset_tag_version()[source]¶

Return type:: None

set_tag_version(version, update=False)[source]¶

Parameters:

version (float)
update (bool)

Return type:

None

delegate_cache_query(group)[source]¶

Return True if this tag’s handler matches group (bulk-fetch).

Parameters:: group (str)
Return type:: bool

Keys¶

class fragmented_keys.key.standard.StandardKey(key, tags=None, group_id='')[source]¶

Bases: object

A composite cache key built from multiple versioned tags.

The final key string is an MD5 hash of the base key name combined with each tag’s name and current version, so that any tag version change produces a completely different key.

Parameters:

key (str)
tags (list[BaseTag] | None)
group_id (str)

add_tag(tag)[source]¶

Parameters:: tag (BaseTag)
Return type:: None

get_key_str(hash=True)[source]¶

Build the composite key string.

When hash is True (default) the key is returned as an MD5 hex digest suitable for use as a cache key. Pass False to get the raw string for debugging.

Parameters:: hash (bool)
Return type:: str

Cache Handlers¶

class fragmented_keys.cache_handler.redis_handler.RedisHandler(client)[source]¶

Bases: object

Redis cache handler.

Parameters:: client (Redis)

group_name()[source]¶

Return type:: str

get(key)[source]¶

Parameters:: key (str)
Return type:: str | None

set(key, value, ttl=None)[source]¶

Parameters:

key (str)
value (str)
ttl (int | None)

Return type:

None

get_multi(keys)[source]¶

Parameters:: keys (list[str])
Return type:: dict[str, str]

class fragmented_keys.cache_handler.memory.MemoryHandler[source]¶

Bases: object

In-memory cache handler for testing and temporary caching.

group_name()[source]¶

Return type:: str

get(key)[source]¶

Parameters:: key (str)
Return type:: str | None

set(key, value, ttl=None)[source]¶

Parameters:

key (str)
value (str)
ttl (int | None)

Return type:

None

get_multi(keys)[source]¶

Parameters:: keys (list[str])
Return type:: dict[str, str]

clear()[source]¶

Clear all cached values.

Return type:: None

KeyRing¶

class fragmented_keys.key_ring.FragmentedKeyRing(global_options=None, global_tag_options=None, default_cache_handler='memory', cache_handlers=None, default_prefix='DefaultPrefix')[source]¶

Bases: object

Factory for creating and managing related keys with predefined configurations.

Define key templates once with define_key, then retrieve configured StandardKey objects with get_key_obj or the convenience get_<name>_key_obj(...) dynamic method.

Parameters:

global_options (dict[str, Any] | None)
global_tag_options (dict[str, dict[str, Any]] | None)
default_cache_handler (str)
cache_handlers (dict[str, Any] | None)
default_prefix (str)

set_tag_options(tag, options)[source]¶

Parameters:

tag (str)
options (dict[str, Any])

Return type:

None

get_tag_options(tag, extra=None)[source]¶

Parameters:

tag (str)
extra (dict[str, Any] | None)

Return type:

dict[str, Any]

set_global_options(options)[source]¶

Parameters:: options (dict[str, Any])
Return type:: None

get_global_options()[source]¶

Return type:: dict[str, Any]

tag(tag, instance, options=None)[source]¶

Create a tag instance with merged options.

Parameters:

tag (str)
instance (str)
options (dict[str, Any] | None)

Return type:

BaseTag

define_key(key, params, globals=None)[source]¶

Define a reusable key template.

params is a list where each element is either a tag name string or a dict with at least a "tag" key and optional overrides (cache_handler, type, version, prefix).

Parameters:

key (str)
params (list[str | dict[str, Any]])
globals (dict[str, Any] | None)

Return type:

None

get_key_obj(key, tag_values)[source]¶

Return a StandardKey populated from a defined template.

Parameters:

key (str)
tag_values (list[str])

Return type:

StandardKey