core.orm.cache
==============

.. py:module:: core.orm.cache

.. autoapi-nested-parse::

   Provides a simple and mostly transparent way of defining orm-cached
   properties on the application class.

   For example::

       from onegov.core import Framework
       from onegov.core.orm import orm_cached

       class App(Framework):

           @orm_cached(policy='on-table-change:users')
           def users(self):
               # ... fetch users from database

   Properties defined in this way are accessible through the instance::

       app.users

   If there are any changes to the users table, the cache is removed. Since the
   cache is usually a shared redis instance, this works for multiple processes.



Attributes
----------

.. autoapisummary::

   core.orm.cache.Creator
   core.orm.cache._T
   core.orm.cache._QT
   core.orm.cache.unset


Classes
-------

.. autoapisummary::

   core.orm.cache.OrmCacheApp
   core.orm.cache.OrmCacheDescriptor


Functions
---------

.. autoapisummary::

   core.orm.cache.orm_cached
   core.orm.cache.request_cached


Module Contents
---------------

.. py:data:: Creator

.. py:data:: _T

.. py:data:: _QT

.. py:data:: unset

.. py:class:: OrmCacheApp

   Integrates the orm cache handling into the application
   (i.e. :class:`onegov.core.framework.Framework`).

   In addition, the application needs to call :meth:`setup_orm_cache` inside
   of `:meth:onegov.server.application.Application.set_application_id` to
   enable the cache evicition mechanism.



   .. py:attribute:: session_manager
      :type:  core.orm.session_manager.SessionManager


   .. py:method:: configure_orm_cache(**cfg: Any) -> None


   .. py:method:: setup_orm_cache() -> None

      Sets up the event handlers for the change-detection. 



   .. py:method:: descriptor_bound_orm_change_handler(descriptor: OrmCacheDescriptor[Any]) -> collections.abc.Callable[[str, core.orm.Base], None]

      Listens to changes to the database and evicts the cache if the
      policy demands it. Available policies:

      * policy='on-table-change:table': clears the cache if there's a change
        on the given table

      * policy=lambda obj: ...: clears the cache if the given policy function
        returns true (it receives the object which has changed)




   .. py:property:: orm_cache_descriptors
      :type: collections.abc.Iterator[OrmCacheDescriptor[Any]]


      Yields all orm cache descriptors installed on the class. 



.. py:class:: OrmCacheDescriptor(cache_policy: CachePolicy, creator: Creator[sqlalchemy.orm.query.Query[_QT]], by_role: bool = False)
              OrmCacheDescriptor(cache_policy: CachePolicy, creator: Creator[_T], by_role: bool = False)

   Bases: :py:obj:`Generic`\ [\ :py:obj:`_T`\ ]


   The descriptor implements the protocol for fetching the objects
   either from cache or creating them using the :param:``creator``.

   You are not allowed to store ORM objects in this cache, since it
   leads to unpredictable results when attempting to merge the restored
   objects with the current session.


   .. py:attribute:: used_cache_keys
      :type:  set[str]


   .. py:attribute:: cache_policy


   .. py:attribute:: cache_key_prefix


   .. py:attribute:: creator


   .. py:attribute:: by_role
      :value: False



   .. py:method:: cache_key(obj: OrmCacheApp | _HasApp) -> str


   .. py:method:: assert_no_orm_objects(obj: object, depth: int = 0) -> None

      Ensures the object contains no ORM objects

              



   .. py:method:: create(instance: OrmCacheApp | _HasApp) -> _T

      Uses the creator to load the object to be cached.

      Since the return value of the creator might not be something we want
      to cache, this function will turn some return values into something
      more useful (e.g. queries are completely fetched).




   .. py:method:: load(instance: OrmCacheApp | _HasApp) -> _T

      Loads the object from the database or cache. 



   .. py:method:: __get__(instance: None, owner: type[Any]) -> Self
                  __get__(instance: Any, owner: type[Any]) -> _T

      Handles the object/cache access. 



.. py:function:: orm_cached(policy: CachePolicy, by_role: bool = False) -> _OrmCacheDecorator

   The decorator use to setup the cache descriptor.

   See the :mod:`onegov.core.orm.cache` docs for usage.



.. py:function:: request_cached(appmethod: collections.abc.Callable[[_FrameworkT], _T]) -> _RequestCached[_FrameworkT, _T]

   This is like a request scoped :func:`orm_cached`.

   This may store ORM objects in contrast to :func:`orm_cached`, which
   should only be used to store other kinds of objects.