fastapi-rtk 2.11.4__tar.gz → 2.12.0__tar.gz

{fastapi_rtk-2.11.4 → fastapi_rtk-2.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastapi-rtk
-Version: 2.11.4
+Version: 2.12.0
 Summary: A package that provides a set of tools to build a FastAPI application with a Class-Based CRUD API.
 Project-URL: Homepage, https://codeberg.org/datatactics/fastapi-rtk
 Project-URL: Issues, https://codeberg.org/datatactics/fastapi-rtk/issues

{fastapi_rtk-2.11.4 → fastapi_rtk-2.12.0}/fastapi_rtk/__init__.py

@@ -7,6 +7,7 @@ from .auth import *
 from .backends.generic import *
 from .backends.sqla import *
 from .bases import *
+from .caches import *
 from .const import *
 from .db import *
 from .decorators import *
@@ -22,6 +23,7 @@ from .routers import *
 from .schemas import *
 from .security import *
 from .security.sqla.apis import *  #! Manually import security APIs to prevent circular imports
+from .security.sqla.user_cache import *
 from .setting import *
 from .types import *
 from .utils import *
@@ -143,6 +145,8 @@ __all__ = [
     "SQLASessionMaker",
     "SQLAScopedSession",
     # .bases
+    "AbstractCacheSerializer",
+    "AbstractCacheStorage",
     "DBQueryParams",
     "AbstractQueryBuilder",
     "BaseFileException",
@@ -157,6 +161,11 @@ __all__ = [
     "MissingGreenletError",
     "BasicModel",
     "AbstractSession",
+    # .caches
+    "Cache",
+    "JSONCacheSerializer",
+    "PickleCacheSerializer",
+    "InMemoryCacheStorage",
     # .const
     "logger",
     # .db
@@ -236,6 +245,14 @@ __all__ = [
     "PermissionViewApi",
     "UsersApi",
     "RolesApi",
+    # .security.sqla.user_cache
+    "USER_CACHE_KEY_PREFIX",
+    "CachedUser",
+    "CachedUserDatabase",
+    "get_cached_user",
+    "set_cached_user",
+    "invalidate_user_cache",
+    "clear_user_cache",
     # .setting
     "Setting",
     # .types

fastapi_rtk-2.12.0/fastapi_rtk/_version.py

@@ -0,0 +1 @@
+__version__ = "2.12.0"

{fastapi_rtk-2.11.4 → fastapi_rtk-2.12.0}/fastapi_rtk/auth/auth.py

@@ -12,6 +12,7 @@ import makefun
 from ..const import DEFAULT_COOKIE_NAME, DEFAULT_SECRET, DEFAULT_TOKEN_URL, logger
 from ..db import User, UserDatabase, get_user_db
 from ..manager import UserManager
+from ..security.sqla.user_cache import CachedUserDatabase
 from .strategies import Strategy, StrategyConfig
 from .strategies.jwt import get_jwt_strategy_generator
 
@@ -85,9 +86,10 @@ class Authenticator(fastapi_users.authentication.Authenticator):
         get_enabled_backends: fastapi_users.authentication.authenticator.EnabledBackendsDependency
         | None = None,
         default_to_none: bool = False,
+        use_cache: bool = False,
     ):
         """
-        Modified version of the default `current_user` function. This adds `default_to_none` parameter.
+        Modified version of the default `current_user` function. This adds `default_to_none` and `use_cache` parameters.
 
         Return a dependency callable to retrieve currently authenticated user.
 
@@ -108,6 +110,9 @@ class Authenticator(fastapi_users.authentication.Authenticator):
         By default, all specified authentication backends are enabled.
         Please note however that every backend will appear in the OpenAPI documentation,
         as FastAPI resolves it statically.
+        :param use_cache: If `True`, the user is looked up through the user cache honoring `AUTH_USER_CACHE_TTL`,
+        leaving the session untouched on a hit. Only for read paths: a cached user is detached and carries no
+        fresher state than the entry. Defaults to `False`.
         """
         signature = self._get_dependency_signature(get_enabled_backends)
 
@@ -120,6 +125,7 @@ class Authenticator(fastapi_users.authentication.Authenticator):
                 verified=verified,
                 superuser=superuser,
                 default_to_none=default_to_none,
+                use_cache=use_cache,
                 **kwargs,
             )
             return user
@@ -164,6 +170,7 @@ class Authenticator(fastapi_users.authentication.Authenticator):
         verified: bool = False,
         superuser: bool = False,
         default_to_none: bool = False,
+        use_cache: bool = False,
         strategy_params: tuple[tuple, dict[str, typing.Any]] | None = None,
     ):
         """
@@ -178,6 +185,7 @@ class Authenticator(fastapi_users.authentication.Authenticator):
             verified (bool, optional): If `True`, the authenticated user must be verified. Defaults to False.
             superuser (bool, optional): If `True`, the authenticated user must be a superuser. Defaults to False.
             default_to_none (bool, optional): If `True`, return `None` if there is no authenticated user instead of raising a HTTPException. Defaults to False.
+            use_cache (bool, optional): If `True`, the user is looked up through the user cache honoring `AUTH_USER_CACHE_TTL`, leaving the session untouched on a hit. Only for read paths: a cached user is detached and carries no fresher state than the entry. Defaults to False.
             strategy_params (tuple[tuple, dict[str, typing.Any]] | None, optional): Parameters for the authentication strategy. Defaults to None.
 
         Returns:
@@ -191,6 +199,7 @@ class Authenticator(fastapi_users.authentication.Authenticator):
             verified=verified,
             superuser=superuser,
             default_to_none=default_to_none,
+            use_cache=use_cache,
             **(strategy_params[1] if strategy_params else {}),
         )
 
@@ -205,8 +214,15 @@ class Authenticator(fastapi_users.authentication.Authenticator):
         verified: bool = False,
         superuser: bool = False,
         default_to_none: bool = False,
+        use_cache: bool = False,
         **kwargs,
     ) -> tuple[fastapi_users.models.UP | None, str | None]:
+        user_db = user_manager.user_db
+        if use_cache:
+            user_manager.user_db = CachedUserDatabase(
+                user_db.session, user_db.user_table, user_db.oauth_account_table
+            )
+
         user, token = None, None
         try:
             user, token = await super()._authenticate(
@@ -221,6 +237,11 @@ class Authenticator(fastapi_users.authentication.Authenticator):
         except fastapi.HTTPException as e:
             if not default_to_none:
                 raise e
+        finally:
+            # The user manager is shared with the rest of the request, and only this
+            # lookup may answer from the cache: a cached user is detached, so a later
+            # write through it would clash with the session's own copy of that row.
+            user_manager.user_db = user_db
         return user, token
 
 

{fastapi_rtk-2.11.4 → fastapi_rtk-2.12.0}/fastapi_rtk/bases/__init__.py

@@ -1,3 +1,4 @@
+from .cache import *
 from .db import *
 from .file_manager import *
 from .filter import *
@@ -6,6 +7,8 @@ from .model import *
 from .session import *
 
 __all__ = [
+    "AbstractCacheSerializer",
+    "AbstractCacheStorage",
     "DBQueryParams",
     "AbstractQueryBuilder",
     "BaseFileException",

fastapi_rtk-2.12.0/fastapi_rtk/bases/cache.py

@@ -0,0 +1,85 @@
+import abc
+import typing
+
+__all__ = ["AbstractCacheSerializer", "AbstractCacheStorage"]
+
+
+class AbstractCacheSerializer(abc.ABC):
+    """
+    Converts a cached value to and from the form a storage can hold.
+
+    Implement this to control the wire format of a storage that cannot hold Python objects, e.g. JSON or pickle for redis. The signature picks how `Cache` schedules the call: an `async def` is awaited on the event loop, while a plain `def` is treated as heavy and runs in a thread. Declare `async def` unless the conversion is costly enough to be worth a thread hop.
+    """
+
+    @abc.abstractmethod
+    async def dumps(self, value: typing.Any) -> typing.Any:
+        """
+        Convert a value into its stored form.
+
+        Args:
+            value (typing.Any): The value handed to `Cache.set`.
+
+        Returns:
+            typing.Any: The value to hand to the storage.
+        """
+
+    @abc.abstractmethod
+    async def loads(self, value: typing.Any) -> typing.Any:
+        """
+        Convert a stored value back into its original form.
+
+        Args:
+            value (typing.Any): The value read from the storage.
+
+        Returns:
+            typing.Any: The value to hand back to the caller.
+        """
+
+
+class AbstractCacheStorage(abc.ABC):
+    """
+    Keeps already-serialized values under string keys, with a per-entry expiry.
+
+    Implement this to hold entries somewhere other than the process memory, e.g. redis or memcached.
+    """
+
+    @abc.abstractmethod
+    async def get(self, key: str) -> typing.Any | None:
+        """
+        Read the stored value under the given key.
+
+        Args:
+            key (str): The key to read.
+
+        Returns:
+            typing.Any | None: The stored value, or `None` when absent or expired.
+        """
+
+    @abc.abstractmethod
+    async def set(self, key: str, value: typing.Any, ttl: int) -> None:
+        """
+        Write a value under the given key.
+
+        Args:
+            key (str): The key to write.
+            value (typing.Any): The already-serialized value to store.
+            ttl (int): Seconds the entry stays valid.
+        """
+
+    @abc.abstractmethod
+    async def delete(self, key: str) -> None:
+        """
+        Drop the entry under the given key.
+
+        Args:
+            key (str): The key to drop.
+        """
+
+    @abc.abstractmethod
+    async def clear(self, prefix: str | None = None) -> None:
+        """
+        Drop every entry, or every entry whose key starts with the given prefix.
+
+        Args:
+            prefix (str | None, optional): Only drop keys starting with this. Defaults to None, which drops everything.
+        """

fastapi_rtk-2.12.0/fastapi_rtk/caches/__init__.py

@@ -0,0 +1,10 @@
+from .cache import *
+from .serializers import *
+from .storages import *
+
+__all__ = [
+    "Cache",
+    "JSONCacheSerializer",
+    "PickleCacheSerializer",
+    "InMemoryCacheStorage",
+]

fastapi_rtk-2.12.0/fastapi_rtk/caches/cache.py

@@ -0,0 +1,78 @@
+import typing
+
+from ..bases.cache import AbstractCacheSerializer, AbstractCacheStorage
+from ..utils import smart_run
+from .storages import InMemoryCacheStorage
+
+__all__ = ["Cache"]
+
+
+class Cache:
+    """
+    Cache pairing a storage with an optional serializer.
+
+    Swap the storage to move entries out of the process, and the serializer to match what that storage can hold.
+    """
+
+    def __init__(
+        self,
+        storage: AbstractCacheStorage | None = None,
+        serializer: AbstractCacheSerializer | None = None,
+    ):
+        """
+        Initialize the cache.
+
+        Args:
+            storage (AbstractCacheStorage | None, optional): Where entries are kept. Defaults to None, which uses an `InMemoryCacheStorage`.
+            serializer (AbstractCacheSerializer | None, optional): Applied on write and reversed on read. Defaults to None, which stores values as handed in and only works for a storage holding Python objects.
+        """
+        self.storage = storage or InMemoryCacheStorage()
+        self.serializer = serializer
+
+    async def get(self, key: str) -> typing.Any | None:
+        """
+        Read the value cached under the given key.
+
+        Args:
+            key (str): The key to read.
+
+        Returns:
+            typing.Any | None: The cached value, or `None` when absent or expired.
+        """
+        value = await self.storage.get(key)
+        if value is None or self.serializer is None:
+            return value
+
+        return await smart_run(self.serializer.loads, value)
+
+    async def set(self, key: str, value: typing.Any, ttl: int) -> None:
+        """
+        Cache a value under the given key.
+
+        Args:
+            key (str): The key to write.
+            value (typing.Any): The value to cache.
+            ttl (int): Seconds the entry stays valid.
+        """
+        if self.serializer is not None:
+            value = await smart_run(self.serializer.dumps, value)
+
+        await self.storage.set(key, value, ttl)
+
+    async def delete(self, key: str) -> None:
+        """
+        Drop the entry cached under the given key.
+
+        Args:
+            key (str): The key to drop.
+        """
+        await self.storage.delete(key)
+
+    async def clear(self, prefix: str | None = None) -> None:
+        """
+        Drop every cached entry, or every entry whose key starts with the given prefix.
+
+        Args:
+            prefix (str | None, optional): Only drop keys starting with this. Defaults to None, which drops everything.
+        """
+        await self.storage.clear(prefix)

fastapi_rtk-2.12.0/fastapi_rtk/caches/serializers.py

@@ -0,0 +1,95 @@
+import json
+import pickle
+import typing
+
+from ..bases.cache import AbstractCacheSerializer
+
+__all__ = ["JSONCacheSerializer", "PickleCacheSerializer"]
+
+
+class JSONCacheSerializer(AbstractCacheSerializer):
+    """
+    Stores values as JSON text.
+
+    Values must be JSON-native; a payload holding `datetime` or `Decimal` needs `PickleCacheSerializer` or a custom encoder.
+    """
+
+    def __init__(
+        self,
+        dumps_kwargs: dict[str, typing.Any] | None = None,
+        loads_kwargs: dict[str, typing.Any] | None = None,
+    ):
+        """
+        Initialize the serializer.
+
+        Args:
+            dumps_kwargs (dict[str, typing.Any] | None, optional): Keyword arguments passed to `json.dumps`, e.g. a custom `cls` encoder. Defaults to None.
+            loads_kwargs (dict[str, typing.Any] | None, optional): Keyword arguments passed to `json.loads`. Defaults to None.
+        """
+        self.dumps_kwargs = dumps_kwargs or {}
+        self.loads_kwargs = loads_kwargs or {}
+
+    async def dumps(self, value: typing.Any) -> str:
+        """
+        Convert a value into JSON text.
+
+        Args:
+            value (typing.Any): The value to store.
+
+        Returns:
+            str: The JSON text to hand to the storage.
+        """
+        return json.dumps(value, **self.dumps_kwargs)
+
+    async def loads(self, value: str) -> typing.Any:
+        """
+        Convert JSON text back into a value.
+
+        Args:
+            value (str): The JSON text read from the storage.
+
+        Returns:
+            typing.Any: The decoded value.
+        """
+        return json.loads(value, **self.loads_kwargs)
+
+
+class PickleCacheSerializer(AbstractCacheSerializer):
+    """
+    Stores values as pickled bytes, keeping types JSON cannot express.
+
+    Only point this at a store the application itself owns: unpickling attacker-controlled bytes executes arbitrary code.
+    """
+
+    def __init__(self, protocol: int = pickle.HIGHEST_PROTOCOL):
+        """
+        Initialize the serializer.
+
+        Args:
+            protocol (int, optional): The pickle protocol to write with. Defaults to `pickle.HIGHEST_PROTOCOL`.
+        """
+        self.protocol = protocol
+
+    async def dumps(self, value: typing.Any) -> bytes:
+        """
+        Convert a value into pickled bytes.
+
+        Args:
+            value (typing.Any): The value to store.
+
+        Returns:
+            bytes: The pickled value to hand to the storage.
+        """
+        return pickle.dumps(value, protocol=self.protocol)
+
+    async def loads(self, value: bytes) -> typing.Any:
+        """
+        Convert pickled bytes back into a value.
+
+        Args:
+            value (bytes): The pickled value read from the storage.
+
+        Returns:
+            typing.Any: The unpickled value.
+        """
+        return pickle.loads(value)

fastapi_rtk-2.12.0/fastapi_rtk/caches/storages.py

@@ -0,0 +1,78 @@
+import time
+import typing
+
+from ..bases.cache import AbstractCacheStorage
+
+__all__ = ["InMemoryCacheStorage"]
+
+
+class InMemoryCacheStorage(AbstractCacheStorage):
+    """
+    Storage backed by a dictionary in the worker process.
+
+    Each worker keeps its own entries, so a deletion only reaches the worker that performed it and the others fall back to the TTL.
+    """
+
+    def __init__(self):
+        """
+        Initialize the storage with no entries.
+        """
+        self._entries: dict[str, tuple[float, typing.Any]] = {}
+
+    async def get(self, key: str) -> typing.Any | None:
+        """
+        Read the stored value under the given key, dropping it when it expired.
+
+        Args:
+            key (str): The key to read.
+
+        Returns:
+            typing.Any | None: The stored value, or `None` when absent or expired.
+        """
+        entry = self._entries.get(key)
+        if entry is None:
+            return None
+
+        expires_at, value = entry
+        if expires_at <= time.monotonic():
+            self._entries.pop(key, None)
+            return None
+
+        return value
+
+    async def set(self, key: str, value: typing.Any, ttl: int) -> None:
+        """
+        Write a value under the given key, dropping entries that expired meanwhile.
+
+        Args:
+            key (str): The key to write.
+            value (typing.Any): The already-serialized value to store.
+            ttl (int): Seconds the entry stays valid.
+        """
+        now = time.monotonic()
+        for expired in [k for k, (exp, _) in self._entries.items() if exp <= now]:
+            self._entries.pop(expired, None)
+        self._entries[key] = (now + ttl, value)
+
+    async def delete(self, key: str) -> None:
+        """
+        Drop the entry under the given key.
+
+        Args:
+            key (str): The key to drop.
+        """
+        self._entries.pop(key, None)
+
+    async def clear(self, prefix: str | None = None) -> None:
+        """
+        Drop every entry, or every entry whose key starts with the given prefix.
+
+        Args:
+            prefix (str | None, optional): Only drop keys starting with this. Defaults to None, which drops everything.
+        """
+        if prefix is None:
+            self._entries.clear()
+            return
+
+        for key in [k for k in self._entries if k.startswith(prefix)]:
+            self._entries.pop(key, None)

{fastapi_rtk-2.11.4 → fastapi_rtk-2.12.0}/fastapi_rtk/db.py

@@ -71,7 +71,7 @@ class UserDatabase(
         statement = sqlalchemy.select(self.user_table).where(
             sqlalchemy.func.lower(self.user_table.email) == sqlalchemy.func.lower(email)
         )
-        return await self._get_user(statement)
+        return await self._get_first_user(statement, field="email")
 
     async def get_by_oauth_account(
         self, oauth: str, account_id: str
@@ -149,7 +149,7 @@ class UserDatabase(
             sqlalchemy.func.lower(self.user_table.username)
             == sqlalchemy.func.lower(username)
         )
-        return await self._get_user(statement)
+        return await self._get_first_user(statement, field="username")
 
     async def _get_user(
         self, statement: sqlalchemy.Select
@@ -157,6 +157,30 @@ class UserDatabase(
         results = await smart_run(self.session.execute, statement)
         return results.unique().scalar_one_or_none()
 
+    async def _get_first_user(
+        self, statement: sqlalchemy.Select, *, field: str
+    ) -> fastapi_users.models.UP | None:
+        """
+        Resolve a case-insensitive user lookup deterministically.
+
+        Legacy databases may contain rows that differ only in the casing of
+        `email`/`username` (the unique constraint is case-sensitive). Instead
+        of raising `MultipleResultsFound` (which surfaced as HTTP 500 on
+        login), the lowest-id matching row wins and a warning is logged.
+        """
+        statement = statement.order_by(self.user_table.id)
+        results = await smart_run(self.session.execute, statement)
+        users = results.unique().scalars().all()
+        if len(users) > 1:
+            logger.warning(
+                "Multiple users match %s case-insensitively (ids=%s). "
+                "Using the lowest-id row (id=%s); please de-duplicate the user table.",
+                field,
+                [user.id for user in users],
+                users[0].id,
+            )
+        return users[0] if users else None
+
 
 class lazy(lazy_self["DatabaseSessionManager", T]): ...
 

{fastapi_rtk-2.11.4 → fastapi_rtk-2.12.0}/fastapi_rtk/dependencies.py

@@ -19,6 +19,8 @@ def set_global_user():
     """
     A dependency for FastAPI that will set the current user to the global variable `g.user`.
 
+    The user is read through `g.cache` when `AUTH_USER_CACHE_TTL` is set, so a cached request issues no query and never checks out a database connection for the lookup.
+
     Usage:
     ```python
     async def get_info(
@@ -31,7 +33,9 @@ def set_global_user():
 
     async def set_global_user_dependency(
         user: User | None = fastapi.Depends(
-            g.auth.fastapi_users.current_user(active=True, default_to_none=True)
+            g.auth.fastapi_users.current_user(
+                active=True, default_to_none=True, use_cache=True
+            )
         ),
     ):
         g.user = user

{fastapi_rtk-2.11.4 → fastapi_rtk-2.12.0}/fastapi_rtk/fastapi_react_toolkit.py

@@ -20,6 +20,7 @@ from .api import BaseApi, ModelRestApi
 from .apis import InfoApi, LicenseApi
 from .auth import Auth
 from .backends.sqla.session import SQLASession
+from .caches import Cache
 from .cli.commands.db import upgrade
 from .cli.commands.translate import init_babel_cli
 from .const import (
@@ -90,6 +91,7 @@ class FastAPIReactToolkit:
         exclude_apis (list[BASE_APIS] | None, optional): List of security APIs to be excluded when initializing the FastAPI application. Defaults to None.
         global_user_dependency (bool, optional): Whether to add the `set_global_user` dependency to the FastAPI application. This allows you to access the current user with the `g.user` object. Defaults to True.
         global_background_tasks (bool, optional): Whether to add the `set_global_background_tasks` dependency to the FastAPI application. This allows you to access the background tasks with the `g.background_tasks` object. Defaults to True.
+        cache (Cache | None, optional): The cache backend used by caching features such as `AUTH_USER_CACHE_TTL`, also reachable as `g.cache`. Defaults to None, which uses the `CACHE` config key or a `Cache` backed by an `InMemoryCacheStorage`.
         instrumentator (Instrumentator | None, optional): The instrumentator to use for monitoring the FastAPI application. Defaults to `Instrumentator(**Setting.INSTRUMENTATOR_CONFIG)`.
         on_startup (Callable[[FastAPI], None]  |  Awaitable[Callable[[FastAPI], None]]  |  None, optional): Function to call when the app is starting up. Can either be a regular function or an async function. If the function takes a `FastAPI` instance as an argument, it will be passed to the function. Defaults to None.
         on_shutdown (Callable[[FastAPI], None]  |  Awaitable[Callable[[FastAPI], None]]  |  None, optional): Function to call when the app is shutting down. Can either be a regular function or an async function. If the function takes a `FastAPI` instance as an argument, it will be passed to the function. Defaults to None.
@@ -212,6 +214,7 @@ class FastAPIReactToolkit:
         global_user_dependency: bool = True,
         global_background_tasks: bool = True,
         global_request: bool = True,
+        cache: Cache | None = None,
         instrumentator: prometheus_fastapi_instrumentator.Instrumentator | None = None,
         on_startup: (
             collections.abc.Callable[[fastapi.FastAPI], None]
@@ -246,6 +249,7 @@ class FastAPIReactToolkit:
             global_user_dependency (bool, optional): Whether to add the `set_global_user` dependency to the FastAPI application. This allows you to access the current user with the `g.user` object. Defaults to True.
             global_background_tasks (bool, optional): Whether to add the `set_global_background_tasks` dependency to the FastAPI application. This allows you to access the background tasks with the `g.background_tasks` object. Defaults to True.
             global_request (bool, optional): Whether to add the `set_global_request` dependency to the FastAPI application. This allows you to access the current request with the `g.request` object. Defaults to True.
+            cache (Cache | None, optional): The cache backend used by caching features such as `AUTH_USER_CACHE_TTL`, also reachable as `g.cache`. Defaults to None, which uses the `CACHE` config key or a `Cache` backed by an `InMemoryCacheStorage`.
             instrumentator (Instrumentator | None, optional): The instrumentator to use for monitoring the FastAPI application. Defaults to `Instrumentator(**Setting.INSTRUMENTATOR_CONFIG)`.
             on_startup (Callable[[FastAPI], None]  |  Awaitable[Callable[[FastAPI], None]]  |  None, optional): Function to call when the app is starting up. Can either be a regular function or an async function. If the function takes a `FastAPI` instance as an argument, it will be passed to the function. Defaults to None.
             on_shutdown (Callable[[FastAPI], None]  |  Awaitable[Callable[[FastAPI], None]]  |  None, optional): Function to call when the app is shutting down. Can either be a regular function or an async function. If the function takes a `FastAPI` instance as an argument, it will be passed to the function. Defaults to None.
@@ -265,6 +269,8 @@ class FastAPIReactToolkit:
         self.global_user_dependency = global_user_dependency
         self.global_background_tasks = global_background_tasks
         self.global_request = global_request
+        if cache is not None:
+            self.cache = cache
         if instrumentator is not None:
             self.instrumentator = instrumentator
         self.on_startup = on_startup
@@ -798,3 +804,25 @@ class FastAPIReactToolkit:
     @property
     def config(self):
         return g.config
+
+    @property
+    def cache(self) -> Cache:
+        """
+        The cache used by caching features such as `AUTH_USER_CACHE_TTL`.
+
+        Reads and writes `g.cache`, so the toolkit and the rest of the framework always see the same instance.
+
+        Returns:
+            Cache: The active cache, built from the `CACHE` config key or defaulting to an `InMemoryCacheStorage`.
+        """
+        return g.cache
+
+    @cache.setter
+    def cache(self, value: Cache) -> None:
+        """
+        Replace the cache used by caching features.
+
+        Args:
+            value (Cache): The cache to use.
+        """
+        g.cache = value