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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastapi-rtk
-Version: 2.12.0
+Version: 2.12.2
 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.12.0 → fastapi_rtk-2.12.2}/fastapi_rtk/__init__.py

@@ -161,6 +161,7 @@ __all__ = [
     "MissingGreenletError",
     "BasicModel",
     "AbstractSession",
+    "AbstractUserSerializer",
     # .caches
     "Cache",
     "JSONCacheSerializer",
@@ -246,8 +247,8 @@ __all__ = [
     "UsersApi",
     "RolesApi",
     # .security.sqla.user_cache
-    "USER_CACHE_KEY_PREFIX",
-    "CachedUser",
+    "UserSerializer",
+    "UserCache",
     "CachedUserDatabase",
     "get_cached_user",
     "set_cached_user",

fastapi_rtk-2.12.2/fastapi_rtk/_version.py

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

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

@@ -5,6 +5,7 @@ from .filter import *
 from .interface import *
 from .model import *
 from .session import *
+from .user_cache import *
 
 __all__ = [
     "AbstractCacheSerializer",
@@ -23,4 +24,5 @@ __all__ = [
     "MissingGreenletError",
     "BasicModel",
     "AbstractSession",
+    "AbstractUserSerializer",
 ]

fastapi_rtk-2.12.2/fastapi_rtk/bases/user_cache.py

@@ -0,0 +1,41 @@
+import abc
+import typing
+
+from .cache import AbstractCacheSerializer
+
+if typing.TYPE_CHECKING:
+    from ..security.sqla.models import User
+
+__all__ = ["AbstractUserSerializer"]
+
+
+class AbstractUserSerializer(AbstractCacheSerializer):
+    """
+    Converts a user row to and from the form a user cache entry holds.
+
+    Narrows `AbstractCacheSerializer` to users, since `UserCache` is the only caller and hands it nothing else. Scheduling is unchanged: an `async def` is awaited on the event loop, while a plain `def` is treated as heavy and runs in a thread.
+    """
+
+    @abc.abstractmethod
+    async def dumps(self, value: "User") -> typing.Any:
+        """
+        Serialize a user row.
+
+        Args:
+            value (User): The user handed to `UserCache.set_user`.
+
+        Returns:
+            typing.Any: The value to store in the cache.
+        """
+
+    @abc.abstractmethod
+    async def loads(self, value: typing.Any) -> "User":
+        """
+        Rebuild a detached user from a stored entry.
+
+        Args:
+            value (typing.Any): The value read from the cache.
+
+        Returns:
+            User: The user to hand back to the caller.
+        """

{fastapi_rtk-2.12.0 → fastapi_rtk-2.12.2}/fastapi_rtk/const.py

@@ -83,6 +83,7 @@ DEFAULT_PROFILER_FOLDER = DEFAULT_STATIC_FOLDER + "/profiler"
 DEFAULT_LANG_FOLDER = DEFAULT_BASEDIR + "/lang"
 DEFAULT_LANGUAGES = "en,de"
 DEFAULT_TRANSLATIONS_KEY = "translations"
+DEFAULT_USER_CACHE_KEY_PREFIX = "fastapi_rtk:user:"
 DEFAULT_SECWEB_PARAMS = {
     "Option": {
         "csp": {

{fastapi_rtk-2.12.0 → fastapi_rtk-2.12.2}/fastapi_rtk/globals.py

@@ -59,6 +59,7 @@ if typing.TYPE_CHECKING:
     from .caches import Cache
     from .fastapi_react_toolkit import FastAPIReactToolkit
     from .security.sqla.models import User
+    from .security.sqla.user_cache import UserCache
 
 __all__ = ["g", "current_app", "current_user", "request", "background_tasks"]
 
@@ -116,6 +117,10 @@ class Globals:
     """
     The cache object used by caching features such as `AUTH_USER_CACHE_TTL`. Defaults to `Cache` from `fastapi_rtk.caches.cache`, which keeps entries in an `InMemoryCacheStorage`.
     """
+    user_cache: "UserCache"
+    """
+    The object that stores and rebuilds authenticated users in `g.cache`. Defaults to the `AUTH_USER_CACHE` config key, or `UserCache` from `fastapi_rtk.security.sqla.user_cache`.
+    """
     current_app: "FastAPIReactToolkit"
     """
     The current FastAPI React Toolkit application instance.
@@ -323,6 +328,19 @@ g.set_default(
         )
     ),
 )
+g.set_default(
+    "user_cache",
+    lazy(
+        lambda: (
+            lazy_import(
+                "fastapi_rtk.setting", lambda mod: mod.Setting.AUTH_USER_CACHE
+            )()
+            or lazy_import(
+                "fastapi_rtk.security.sqla.user_cache", lambda mod: mod.UserCache()
+            )()
+        )
+    ),
+)
 g.config.add_callback(basic_callback)
 
 # Local Proxies

{fastapi_rtk-2.12.0 → fastapi_rtk-2.12.2}/fastapi_rtk/security/sqla/apis.py

@@ -188,7 +188,7 @@ class PermissionsApi(ModelRestApi):
 
 
 class PermissionViewApi(ModelRestApi):
-    resource_name = "permissionview"
+    resource_name = "permissionviews"
     datamodel = SQLAInterface(PermissionApi)
     description = "Allows the view of which roles have which permissions on which APIs."
     max_page_size = 200

fastapi_rtk-2.12.2/fastapi_rtk/security/sqla/user_cache.py

@@ -0,0 +1,238 @@
+import typing
+
+import sqlalchemy
+import sqlalchemy.orm
+
+from ...bases.user_cache import AbstractUserSerializer
+from ...db import UserDatabase
+from ...globals import g
+from ...setting import Setting
+from ...utils import lazy, smart_run, use_default_when_none
+from .models import Role, User
+
+__all__ = [
+    "UserSerializer",
+    "UserCache",
+    "CachedUserDatabase",
+    "get_cached_user",
+    "set_cached_user",
+    "invalidate_user_cache",
+    "clear_user_cache",
+]
+
+
+class UserSerializer(AbstractUserSerializer):
+    """
+    Convert a user row to and from the form a user cache entry holds.
+
+    Set an instance of a subclass as the `AUTH_USER_SERIALIZER` config key to change what an entry stores and what a cached user is rebuilt from. It only ever sees users, so it belongs to `UserCache` and not to the `CACHE` it writes through.
+    """
+
+    async def dumps(self, value: User) -> dict[str, typing.Any]:
+        """
+        Serialize a user row into its mapped columns and the (id, name) pair of each role.
+
+        Args:
+            value (User): The user to serialize, with its roles loaded.
+
+        Returns:
+            dict[str, typing.Any]: The serialized user, under the keys `columns` and `roles`.
+        """
+        mapper = sqlalchemy.inspect(type(value)).mapper
+        return {
+            "columns": {
+                attr.key: getattr(value, attr.key) for attr in mapper.column_attrs
+            },
+            "roles": [(role.id, role.name) for role in value.roles],
+        }
+
+    async def loads(self, value: dict[str, typing.Any]) -> User:
+        """
+        Rebuild a detached user from its serialized form.
+
+        `make_transient_to_detached` gives the instance the identity of the stored row, so a later `Session.add` updates that row instead of inserting a new one, and `set_committed_value` attaches the roles without marking the collection dirty.
+
+        Args:
+            value (dict[str, typing.Any]): The serialized user, under the keys `columns` and `roles`.
+
+        Returns:
+            User: The rebuilt user, detached from any session.
+        """
+        user = User(**value["columns"])
+        sqlalchemy.orm.make_transient_to_detached(user)
+
+        roles = []
+        for role_id, role_name in value["roles"]:
+            role = Role(id=role_id, name=role_name)
+            sqlalchemy.orm.make_transient_to_detached(role)
+            roles.append(role)
+        sqlalchemy.orm.attributes.set_committed_value(user, "roles", roles)
+
+        return user
+
+
+class UserCache:
+    """
+    Read and write authenticated users in `g.cache`.
+
+    Keys, TTL and storage access live here; what an entry holds lives in the serializer. Set an instance of a subclass as the `AUTH_USER_CACHE` config key to change the read and write paths.
+
+    Attributes:
+        serializer (AbstractUserSerializer): The `AUTH_USER_SERIALIZER` config key, or a `UserSerializer`, read on first use.
+    """
+
+    serializer: AbstractUserSerializer = lazy(
+        lambda self: use_default_when_none(
+            Setting.AUTH_USER_SERIALIZER, UserSerializer()
+        )
+    )
+
+    @property
+    def key_prefix(self) -> str:
+        """
+        Prefix of every key this cache writes, and the prefix `clear` drops.
+        """
+        return Setting.AUTH_USER_CACHE_KEY_PREFIX
+
+    @property
+    def ttl(self) -> int:
+        """
+        Seconds an entry stays cached, `0` or less disabling the cache.
+        """
+        return Setting.AUTH_USER_CACHE_TTL
+
+    async def get_user(self, user_id: typing.Any) -> User | None:
+        """
+        Rebuild the cached user with the given id.
+
+        The returned user is detached and behaves as if freshly loaded, so it can be handed to `Session.add` without inserting a second row.
+
+        Args:
+            user_id (typing.Any): The primary key of the user.
+
+        Returns:
+            User | None: The cached user, or `None` when caching is off or the entry is absent.
+        """
+        if self.ttl <= 0:
+            return None
+
+        cached = await g.cache.get(self.cache_key(user_id))
+        if cached is None:
+            return None
+
+        return await smart_run(self.serializer.loads, cached)
+
+    async def set_user(self, user: User) -> None:
+        """
+        Store the given user for `ttl` seconds.
+
+        Args:
+            user (User): The user to store, with its roles loaded.
+        """
+        ttl = self.ttl
+        if ttl <= 0:
+            return
+
+        value = await smart_run(self.serializer.dumps, user)
+        await g.cache.set(self.cache_key(user.id), value, ttl)
+
+    async def invalidate(self, user_id: typing.Any) -> None:
+        """
+        Drop the cached user with the given id.
+
+        Args:
+            user_id (typing.Any): The primary key of the user.
+        """
+        if self.ttl <= 0:
+            return
+
+        await g.cache.delete(self.cache_key(user_id))
+
+    async def clear(self) -> None:
+        """
+        Drop every cached user, leaving other cache entries alone.
+        """
+        if self.ttl <= 0:
+            return
+
+        await g.cache.clear(self.key_prefix)
+
+    def cache_key(self, user_id: typing.Any) -> str:
+        """
+        Build the cache key holding the user with the given id.
+
+        Args:
+            user_id (typing.Any): The primary key of the user.
+
+        Returns:
+            str: The key to read or write in `g.cache`.
+        """
+        return f"{self.key_prefix}{user_id}"
+
+
+class CachedUserDatabase(UserDatabase):
+    """
+    User database that answers `get` from the user cache before querying.
+
+    The session it is built from stays untouched on a cache hit, so the request never checks out a database connection for the lookup.
+    """
+
+    async def get(self, id: typing.Any):
+        """
+        Read the user with the given id, from the cache when it holds one.
+
+        Args:
+            id (typing.Any): The primary key of the user.
+
+        Returns:
+            User | None: The user, or `None` when no row matches.
+        """
+        cached = await get_cached_user(id)
+        if cached is not None:
+            return cached
+
+        user = await super().get(id)
+        if user is not None:
+            await set_cached_user(user)
+
+        return user
+
+
+async def get_cached_user(user_id: typing.Any) -> User | None:
+    """
+    Rebuild the cached user with the given id, through `g.user_cache`.
+
+    Args:
+        user_id (typing.Any): The primary key of the user.
+
+    Returns:
+        User | None: The cached user, or `None` when caching is off or the entry is absent.
+    """
+    return await g.user_cache.get_user(user_id)
+
+
+async def set_cached_user(user: User) -> None:
+    """
+    Store the given user through `g.user_cache`.
+
+    Args:
+        user (User): The user to store, with its roles loaded.
+    """
+    await g.user_cache.set_user(user)
+
+
+async def invalidate_user_cache(user_id: typing.Any) -> None:
+    """
+    Drop the cached user with the given id, through `g.user_cache`.
+
+    Args:
+        user_id (typing.Any): The primary key of the user.
+    """
+    await g.user_cache.invalidate(user_id)
+
+
+async def clear_user_cache() -> None:
+    """
+    Drop every cached user, leaving other cache entries alone.
+    """
+    await g.user_cache.clear()

{fastapi_rtk-2.12.0 → fastapi_rtk-2.12.2}/fastapi_rtk/setting.py

@@ -12,6 +12,7 @@ from .const import (
     DEFAULT_STATIC_FOLDER,
     DEFAULT_TEMPLATE_FOLDER,
     DEFAULT_TRANSLATIONS_KEY,
+    DEFAULT_USER_CACHE_KEY_PREFIX,
     AuthType,
     logger,
 )
@@ -20,7 +21,9 @@ from .globals import g
 
 if typing.TYPE_CHECKING:
     from .bases.file_manager import AbstractFileManager, AbstractImageManager
+    from .bases.user_cache import AbstractUserSerializer
     from .caches import Cache
+    from .security.sqla.user_cache import UserCache
 
 
 __all__ = ["Setting"]
@@ -299,6 +302,27 @@ class _Setting:
         """
         return g.config.get("AUTH_USER_CACHE_TTL", 0)
 
+    @property
+    def AUTH_USER_CACHE_KEY_PREFIX(self) -> str:
+        """
+        Prefix of every key the user cache writes, and the prefix it drops when clearing.
+        """
+        return g.config.get("AUTH_USER_CACHE_KEY_PREFIX", DEFAULT_USER_CACHE_KEY_PREFIX)
+
+    @property
+    def AUTH_USER_CACHE(self) -> "UserCache | None":
+        """
+        The user cache honoring `AUTH_USER_CACHE_TTL`. Also readable as `g.user_cache`.
+        """
+        return g.config.get("AUTH_USER_CACHE")
+
+    @property
+    def AUTH_USER_SERIALIZER(self) -> "AbstractUserSerializer | None":
+        """
+        The serializer deciding what a cached user entry holds, applied by `g.user_cache` before the value reaches `CACHE`.
+        """
+        return g.config.get("AUTH_USER_SERIALIZER")
+
     @property
     def AUTH_ROLE_ADMIN(self) -> str | None:
         return g.config.get("AUTH_ROLE_ADMIN", DEFAULT_ADMIN_ROLE)

{fastapi_rtk-2.12.0 → fastapi_rtk-2.12.2}/tests/unit/test_user_cache.py

@@ -4,14 +4,15 @@ import unittest.mock
 import pytest
 import sqlalchemy
 
+from fastapi_rtk.bases.user_cache import AbstractUserSerializer
 from fastapi_rtk.caches import Cache, InMemoryCacheStorage, PickleCacheSerializer
+from fastapi_rtk.const import DEFAULT_USER_CACHE_KEY_PREFIX
 from fastapi_rtk.db import UserDatabase
 from fastapi_rtk.security.sqla.models import Role, User
 from fastapi_rtk.security.sqla.user_cache import (
-    USER_CACHE_KEY_PREFIX,
     CachedUserDatabase,
-    _dump_user,
-    _rebuild_user,
+    UserCache,
+    UserSerializer,
     clear_user_cache,
     get_cached_user,
     invalidate_user_cache,
@@ -19,6 +20,25 @@ from fastapi_rtk.security.sqla.user_cache import (
 )
 
 
+class _PrefixedUserCache(UserCache):
+    key_prefix = "custom:user:"
+
+
+class _PasswordlessUserSerializer(UserSerializer):
+    async def dumps(self, user):
+        dumped = await super().dumps(user)
+        dumped["columns"].pop("password", None)
+        return dumped
+
+
+async def _dump_user(user):
+    return await UserSerializer().dumps(user)
+
+
+async def _rebuild_user(cached):
+    return await UserSerializer().loads(cached)
+
+
 def _make_user(user_id=7, roles=(("3", "Admin"),)):
     user = User(
         id=user_id,
@@ -39,35 +59,115 @@ def cache(global_setter):
     return cache
 
 
+@pytest.mark.asyncio
 class TestDumpAndRebuild:
-    def test_dump_keeps_columns_and_roles(self):
-        dumped = _dump_user(_make_user())
+    async def test_dump_keeps_columns_and_roles(self):
+        dumped = await _dump_user(_make_user())
         assert dumped["columns"]["id"] == 7
         assert dumped["columns"]["username"] == "user7"
         assert dumped["roles"] == [(3, "Admin")]
 
-    def test_rebuilt_user_is_detached_with_identity(self):
-        rebuilt = _rebuild_user(_dump_user(_make_user()))
+    async def test_rebuilt_user_is_detached_with_identity(self):
+        rebuilt = await _rebuild_user(await _dump_user(_make_user()))
         state = sqlalchemy.inspect(rebuilt)
         assert state.detached is True
         assert state.key == (User, (7,), None)
 
-    def test_rebuilt_roles_are_loaded_without_pending_changes(self):
-        rebuilt = _rebuild_user(_dump_user(_make_user()))
+    async def test_rebuilt_roles_are_loaded_without_pending_changes(self):
+        rebuilt = await _rebuild_user(await _dump_user(_make_user()))
         assert [(role.id, role.name) for role in rebuilt.roles] == [(3, "Admin")]
         assert sqlalchemy.inspect(rebuilt).attrs.roles.history.has_changes() is False
 
-    def test_rebuilt_columns_keep_their_types(self):
-        rebuilt = _rebuild_user(_dump_user(_make_user()))
+    async def test_rebuilt_columns_keep_their_types(self):
+        rebuilt = await _rebuild_user(await _dump_user(_make_user()))
         assert rebuilt.last_login == datetime.datetime(2026, 1, 2, 3, 4)
         assert rebuilt.active is True
 
 
+class TestSettings:
+    def test_default_key_prefix(self):
+        assert UserCache().key_prefix == DEFAULT_USER_CACHE_KEY_PREFIX
+
+    def test_key_prefix_reads_the_config(self, config_setter):
+        config_setter("AUTH_USER_CACHE_KEY_PREFIX", "myapp:user:")
+        assert UserCache().cache_key(7) == "myapp:user:7"
+
+    def test_ttl_reads_the_config(self, config_setter):
+        config_setter("AUTH_USER_CACHE_TTL", 42)
+        assert UserCache().ttl == 42
+
+    def test_serializer_defaults_to_user_serializer(self):
+        assert type(UserCache().serializer) is UserSerializer
+
+    def test_configured_serializer_is_used_as_is(self, config_setter):
+        configured = _PasswordlessUserSerializer()
+        config_setter("AUTH_USER_SERIALIZER", configured)
+        assert UserCache().serializer is configured
+
+    def test_serializer_implements_the_abstract_contract(self):
+        assert isinstance(UserSerializer(), AbstractUserSerializer)
+
+
+@pytest.mark.asyncio
+class TestUserCacheOverride:
+    async def test_module_functions_use_the_configured_cache(
+        self, cache, config_setter, global_setter
+    ):
+        config_setter("AUTH_USER_CACHE_TTL", 30)
+        global_setter("user_cache", _PrefixedUserCache())
+
+        await set_cached_user(_make_user())
+
+        assert "custom:user:7" in cache.storage._entries
+        assert (await get_cached_user(7)).username == "user7"
+
+    async def test_configured_serializer_decides_what_is_stored(
+        self, cache, config_setter, global_setter
+    ):
+        config_setter("AUTH_USER_CACHE_TTL", 30)
+        config_setter("AUTH_USER_SERIALIZER", _PasswordlessUserSerializer())
+        global_setter("user_cache", UserCache())
+
+        await set_cached_user(_make_user())
+
+        stored = await cache.get(f"{DEFAULT_USER_CACHE_KEY_PREFIX}7")
+        assert "password" not in stored["columns"]
+        rebuilt = await get_cached_user(7)
+        assert "password" not in sqlalchemy.inspect(rebuilt).dict
+        assert rebuilt.username == "user7"
+
+    async def test_clear_only_drops_the_configured_prefix(
+        self, cache, config_setter, global_setter
+    ):
+        config_setter("AUTH_USER_CACHE_TTL", 30)
+        global_setter("user_cache", _PrefixedUserCache())
+        await set_cached_user(_make_user())
+        await cache.set(f"{DEFAULT_USER_CACHE_KEY_PREFIX}9", "keep", 60)
+
+        await clear_user_cache()
+
+        assert await get_cached_user(7) is None
+        assert await cache.get(f"{DEFAULT_USER_CACHE_KEY_PREFIX}9") == "keep"
+
+    async def test_invalidate_uses_the_configured_key(
+        self, cache, config_setter, global_setter
+    ):
+        config_setter("AUTH_USER_CACHE_TTL", 30)
+        global_setter("user_cache", _PrefixedUserCache())
+        await set_cached_user(_make_user())
+
+        await invalidate_user_cache(7)
+
+        assert cache.storage._entries == {}
+
+
 @pytest.mark.asyncio
 class TestUserCacheDisabled:
     async def test_get_returns_none(self, cache, config_setter):
         config_setter("AUTH_USER_CACHE_TTL", 0)
-        await cache.set(f"{USER_CACHE_KEY_PREFIX}7", _dump_user(_make_user()), 60)
+        await cache.set(
+            f"{DEFAULT_USER_CACHE_KEY_PREFIX}7", await _dump_user(_make_user()), 60
+        )
         assert await get_cached_user(7) is None
 
     async def test_set_stores_nothing(self, cache, config_setter):
@@ -77,19 +177,19 @@ class TestUserCacheDisabled:
 
     async def test_invalidate_leaves_the_cache_alone(self, cache, config_setter):
         config_setter("AUTH_USER_CACHE_TTL", 0)
-        await cache.set(f"{USER_CACHE_KEY_PREFIX}7", "raw", 60)
+        await cache.set(f"{DEFAULT_USER_CACHE_KEY_PREFIX}7", "raw", 60)
 
         await invalidate_user_cache(7)
 
-        assert await cache.get(f"{USER_CACHE_KEY_PREFIX}7") == "raw"
+        assert await cache.get(f"{DEFAULT_USER_CACHE_KEY_PREFIX}7") == "raw"
 
     async def test_clear_leaves_the_cache_alone(self, cache, config_setter):
         config_setter("AUTH_USER_CACHE_TTL", 0)
-        await cache.set(f"{USER_CACHE_KEY_PREFIX}7", "raw", 60)
+        await cache.set(f"{DEFAULT_USER_CACHE_KEY_PREFIX}7", "raw", 60)
 
         await clear_user_cache()
 
-        assert await cache.get(f"{USER_CACHE_KEY_PREFIX}7") == "raw"
+        assert await cache.get(f"{DEFAULT_USER_CACHE_KEY_PREFIX}7") == "raw"
 
 
 @pytest.mark.asyncio
@@ -109,7 +209,7 @@ class TestUserCacheEnabled:
     async def test_entry_uses_prefixed_key(self, cache, config_setter):
         config_setter("AUTH_USER_CACHE_TTL", 30)
         await set_cached_user(_make_user())
-        assert f"{USER_CACHE_KEY_PREFIX}7" in cache.storage._entries
+        assert f"{DEFAULT_USER_CACHE_KEY_PREFIX}7" in cache.storage._entries
 
     async def test_invalidate_drops_single_user(self, cache, config_setter):
         config_setter("AUTH_USER_CACHE_TTL", 30)

fastapi_rtk-2.12.0/fastapi_rtk/_version.py

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