Render cache keys

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.

enabled: bool

ttl: float | None

version: int | str

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.

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.

citry: Citry

component: Component

kind: Literal['component', 'fragment']

key_digest: str

artifact_bytes: int

frame_count: int

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.

An app served below a sub-path, such as /shop, stores its entries under keys that include it, because a cached render can hold URLs that start with it. Inside a request the key uses the request's sub-path. Outside one, such as in a background job, it uses the app's setting (FastAPI's root_path, Flask's APPLICATION_ROOT, Django's FORCE_SCRIPT_NAME), so pass sub_path when only the server sets the sub-path.

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.
• sub_path str | None - The sub-path the app is served below, such as "/shop", or "" for the site root. None reads the current one.

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 or sub_path is invalid.
• CacheKeyError - If vary cannot be encoded safely.

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. The key includes the sub-path the app is served below, as component_cache_key() describes.

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.
• sub_path str | None - The sub-path the app is served below, such as "/shop", or "" for the site root. None reads the current one.

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, version, or sub_path is invalid.
• CacheKeyError - If vary cannot be encoded safely.