Key Fields

The cache-key field types used inside a KeyConstructor. See the Key Constructors guide for an overview and worked examples.

CacheKeyField

CacheKeyField(
    partition=False,
    hash_value=False,
    *_args,
    sort_lists: bool = True,
    **_kwargs,
)

Bases: ABC

Base class for the pieces that go into a cache key.

Each subclass pulls a piece of data out of a function call and turns it into a stable string.

get_key_payload abstractmethod

get_key_payload(func, args, kwargs) -> dict[str, Any]

Return a name-to-value payload extracted from the call.

normalize

normalize(data)

Normalize cache key components for consistent cache key generation.

stringify

stringify(value)

Turn value into the string the cache key uses, hashing the result when hash_value is set.

get_cache_key_part

get_cache_key_part(func, args, kwargs)

Return the string this field contributes to the cache key for the given call.

extract_request_object

extract_request_object(
    func,
    args,
    kwargs,
    request_arg="request",
    normalize=False,
    view_self_request_fallback: bool = True,
)

Find the request object on the call, falling back to the DRF viewset convention when enabled.

ConstantKeyField

ConstantKeyField(
    key: str,
    value: Any,
    *args,
    partition=False,
    hash_value=False,
    sort_lists: bool = False,
    **kwargs,
)

Bases: CacheKeyField

Cache-key field that contributes a fixed key-value pair on every call.

Example

::

class UserKey(KeyConstructor):
    env = ConstantKeyField("env", "production")
    user = ArgsKeyField("user_id", partition=True)

ArgsKeyField

ArgsKeyField(
    arguments: str | list[str] = "*",
    path: str | None = None,
    normalizer: Callable[[Any], Any] | None = None,
    *args,
    partition=False,
    hash_value=False,
    sort_lists: bool = False,
    **kwargs,
)

Bases: CacheKeyField

Cache-key field that captures function arguments by name.

Example

::

class UserKey(KeyConstructor):
    user = ArgsKeyField("user_id", partition=True)
    lang = ArgsKeyField("lang")

RequestValueKeyField

RequestValueKeyField(
    path: str,
    request_arg: str = "request",
    *args,
    partition=False,
    hash_value=False,
    sort_lists: bool = False,
    view_self_request_fallback: bool = True,
    **kwargs,
)

Bases: CacheKeyField

Cache-key field that reads a value off the request object.

Example

::

class UserKey(KeyConstructor):
    user = RequestValueKeyField("user.id", partition=True)

QueryParamsKeyField

QueryParamsKeyField(
    params: str | list[str] = "*",
    request_arg: str = "request",
    *args,
    partition=False,
    hash_value=False,
    sort_lists: bool = False,
    view_self_request_fallback: bool = True,
    **kwargs,
)

Bases: CacheKeyField

Cache-key field that captures values from the request's query string.

Example

::

class ListUsersKey(KeyConstructor):
    filters = QueryParamsKeyField(["status", "role"])

DjangoModelKeyField

DjangoModelKeyField(model_class)

Bases: CacheKeyField

Cache-key field that fingerprints a Django model's schema.

Records the model's name, module, and concrete fields. Migrations that change the schema invalidate the cache automatically. The payload is always hashed.

Example

::

class UserKey(KeyConstructor):
    shape = DjangoModelKeyField(User)

DrfSerializerKeyField

DrfSerializerKeyField(serializer_class)

Bases: CacheKeyField

Cache-key field that fingerprints a DRF serializer's shape.

Walks declared fields (including nested and list serializers) and records their classes and modules. Adding or removing a field invalidates the cache automatically. The payload is always hashed.

Example

::

class ListUsersKey(KeyConstructor):
    shape = DrfSerializerKeyField(UserSerializer)