CacheConfig
class
Bases: ExtensionConfig
Typed runtime view of one component's Cache declaration.
Citry creates this value from the component's nested Cache class. Read
it through component.cache while the component is rendering.
Attributes
enabled
bool
- Whether Citry may cache this component's rendered output.
ttl
float | None
- How many seconds an entry remains valid, or None for no
expiry.
version
int | str
- An application-controlled value included in the cache key.
CacheKeyError
class
Bases: ValueError
A value cannot be represented safely in a render-cache key.
Attributes
path
- Location of the rejected value within the semantic variation.
reason
- Human-readable reason the value was rejected.
OnComponentCacheHitContext
class
Notify an observer after one cached component subtree was replayed.
component is the live boundary from the current call, never an
archived object. key_digest is exactly 64 lowercase hexadecimal
characters without a backend-key prefix. artifact_bytes is the
stored value's validated UTF-8 size, and frame_count includes the
boundary frame. kind distinguishes a Component.Cache hit from a
transparent <c-cache> fragment hit. For a fragment, component is
the live built-in Cache boundary from the current call. Return values and
observer failures do not alter the committed hit.
The dataclass is shallowly frozen. Observers should copy the scalar fields they need instead of retaining the live component through this context.
component_cache_key
function
Build the exact physical key for one component variation.
This helper does not construct the component, run input hooks, or call a
component's Cache.vary() method. Callers supply the already-computed semantic
variation value.
Parameters
component
type[Component]
- Component class whose stable class ID identifies the entry.
vary
object
- Semantic variation accepted by Citry's canonical key encoder.
version
int | str
- Author-controlled exact integer or non-empty string version.
Returns
str: A short ASCII key suitable for deleting one exact backend entry.
Raises
TypeError - If component is not a Component class.
ValueError - If version is invalid.
CacheKeyError - If vary cannot be encoded safely.
fragment_cache_key
function
Build the exact physical key for one named fragment variation.
Like <c-cache>, this unwraps an outer Const marker from key,
vary, and version before validation and encoding.
Parameters
citry
Citry
- Engine whose cache scope and local revision apply.
key
str
- Exact non-empty semantic fragment name.
vary
object
- Semantic variation accepted by Citry's canonical key encoder.
version
int | str
- Author-controlled exact integer or non-empty string version.
Returns
str: A short ASCII key suitable for deleting one exact backend entry.
Raises
TypeError - If citry is not a Citry instance.
ValueError - If key or version is invalid.
CacheKeyError - If vary cannot be encoded safely.