invenio-cache 3.0.1__py3-none-any.whl

invenio_cache/__init__.py

@@ -0,0 +1,86 @@
+# SPDX-FileCopyrightText: 2017-2018 CERN.
+# SPDX-FileCopyrightText: 2024-2026 Graz University of Technology.
+# SPDX-FileCopyrightText: 2026 TU Wien.
+# SPDX-License-Identifier: MIT
+
+"""Cache module for Invenio.
+
+Initialization
+--------------
+
+Create a Flask application:
+
+>>> from flask import Flask
+>>> app = Flask('myapp')
+>>> app.config['CACHE_TYPE'] = 'simple'
+
+Initialize Invenio-Cache:
+
+>>> from invenio_cache import InvenioCache
+>>> ext = InvenioCache(app)
+
+Jinja bytecode caching
+----------------------
+By default Jinja only supports filesystem and memcached backends for bytecode
+caching. Invenio-Cache provides another backend, which will use the default
+configured cache backend instead (and thus e.g. supports Redis). Bytecode
+caching helps reduce template load time especially in a multi-process
+environment where workers are recycled from time to time.
+
+For more information about Jinja bytecode caching please see
+http://jinja.pocoo.org/docs/2.9/api/#bytecode-cache
+
+Enabling the bytecode cache is as simple as:
+
+>>> from invenio_cache import BytecodeCache
+>>> app.jinja_options = dict(
+...     app.jinja_options,
+...     cache_size=1000,
+...     bytecode_cache=BytecodeCache(app)
+... )
+
+Programmatic API
+----------------
+The programmatic cache API is very simple. First get your cache instance:
+
+>>> cache = ext.cache
+
+If you are in an Flask application context you can also use a handy proxy:
+
+>>> app.app_context().push()
+>>> from invenio_cache import current_cache
+
+Now, simply set, get and delete cache values:
+
+>>> current_cache.set('mykey', 'myvalue')
+True
+>>> current_cache.get('mykey')
+'myvalue'
+>>> current_cache.delete('mykey')
+True
+
+Further documentation
+---------------------
+`Flask-Caching
+<http://pythonhosted.org/Flask-Caching/#configuring-flask-caching>`_ has a good
+and extensive API documentation so please refer to that for other APIs such
+as cache decorators for view, memoization of functions, Jinja snippet caching.
+"""
+
+from __future__ import absolute_import, print_function
+
+from .bccache import BytecodeCache
+from .decorators import cached_unless_authenticated
+from .ext import InvenioCache
+from .proxies import current_cache, current_cache_ext
+
+__version__ = "3.0.1"
+
+__all__ = (
+    "__version__",
+    "cached_unless_authenticated",
+    "current_cache_ext",
+    "current_cache",
+    "BytecodeCache",
+    "InvenioCache",
+)

invenio_cache/_compat.py

@@ -0,0 +1,12 @@
+# SPDX-FileCopyrightText: 2017-2018 CERN.
+# SPDX-License-Identifier: MIT
+
+"""Python 2/3 compatibility module."""
+
+from __future__ import absolute_import, print_function
+
+import sys
+
+PY3 = sys.version_info[0] == 3
+
+string_types = str if PY3 else basestring

invenio_cache/bccache.py

@@ -0,0 +1,21 @@
+# SPDX-FileCopyrightText: 2017-2018 CERN.
+# SPDX-License-Identifier: MIT
+
+"""Jinja bytecode cache for Redis."""
+
+from __future__ import absolute_import, print_function
+
+from jinja2.bccache import MemcachedBytecodeCache
+
+from .proxies import current_cache
+
+
+class BytecodeCache(MemcachedBytecodeCache):
+    """A bytecode cache."""
+
+    def __init__(self, app):
+        """Initialize `BytecodeCache`."""
+        prefix = "{0}jinja::".format(app.config.get("CACHE_KEY_PREFIX"))
+        super(self.__class__, self).__init__(
+            current_cache, prefix=prefix, timeout=None, ignore_memcache_errors=True
+        )

invenio_cache/config.py

@@ -0,0 +1,33 @@
+# SPDX-FileCopyrightText: 2017-2018 CERN.
+# SPDX-FileCopyrightText: 2025 Graz University of Technology.
+# SPDX-License-Identifier: MIT
+
+"""Configuration for Invenio-Cache module.
+
+By default the module is configured to use a Redis database 0 on localhost.
+The underlying Flask-Caching module however supports many other cahe backends.
+
+For how to configure other cache backends please refer to the `Flask-Caching
+<http://pythonhosted.org/Flask-Caching/#configuring-flask-caching>`_
+documentation.
+"""
+
+CACHE_KEY_PREFIX = "cache::"
+"""Cache key prefix."""
+
+#: Sets the cache type.
+CACHE_TYPE = "flask_caching.backends.redis"
+"""Cache type.
+
+Please refer to Flask-Caching documentation for other cache types.
+"""
+
+CACHE_REDIS_URL = "redis://localhost:6379/0"
+"""Redis location and database."""
+
+
+CACHE_IS_AUTHENTICATED_CALLBACK = None
+"""Import path to callback.
+
+Callback is executed to determine if request is authenticated.
+"""

invenio_cache/decorators.py

@@ -0,0 +1,98 @@
+# SPDX-FileCopyrightText: 2017-2023 CERN.
+# SPDX-License-Identifier: MIT
+
+"""Decorators to help with caching."""
+
+import hashlib
+import threading
+import time
+from functools import wraps
+
+from .proxies import current_cache, current_cache_ext
+
+
+def cached_unless_authenticated(timeout=50, key_prefix="default"):
+    """Cache anonymous traffic."""
+
+    def caching(f):
+        @wraps(f)
+        def wrapper(*args, **kwargs):
+            cache_fun = current_cache.cached(
+                timeout=timeout,
+                key_prefix=key_prefix,
+                unless=lambda: current_cache_ext.is_authenticated_callback(),
+            )
+            return cache_fun(f)(*args, **kwargs)
+
+        return wrapper
+
+    return caching
+
+
+def cached_with_expiration(f):
+    """In-process cache function results, with optional expiration and entropy.
+
+    This decorator caches function results in-process and not in a distributed
+    cache, allowing for optional expiration.
+    Entries are based on function arguments and can include entropy to prevent
+    multiple keys from expiring simultaneously.
+    This implementation is highly inspired by the native functools.lru_cache. This
+    func can be replaced if/when lru_cache will accept an expiration time.
+
+    To tune cache ttl and entropy, the decorated function should have the following
+    kwargs:
+    :param cache_ttl (int): Expiration time in seconds. Default is 3600 seconds.
+    :param cache_entropy (bool): Add entropy to cache expiration. Default is True.
+    """
+    cache = {}
+    cache_lock = threading.Lock()
+    hits = misses = 0
+
+    @wraps(f)
+    def wrapper(*args, **kwargs):
+        """Wrapper."""
+        nonlocal hits, misses
+        cache_ttl = kwargs.pop("cache_ttl", 3600)
+        with_entropy = kwargs.pop("cache_entropy", True)
+
+        # Create a hashable key that includes args and the sorted kwargs
+        key = (args) + tuple(sorted(kwargs.items()))
+
+        entropy = 0
+        if with_entropy:
+            # calculate entropy
+            key_str = str(key)
+            # calculate 2-digits int from args/kwargs to prevent keys created
+            # at the same time from expiring simultaneously
+            entropy = int(hashlib.md5(key_str.encode()).hexdigest(), 16) % 100
+
+        now = time.time()
+        with cache_lock:
+            cache_hit = (
+                key in cache and now - cache[key][1] < cache_ttl
+            )  # exists and not expired
+            if cache_hit:
+                hits += 1
+                return cache[key][0]
+            else:
+                result = f(*args, **kwargs)
+                cache[key] = (result, now + entropy)
+                misses += 1
+                return result
+
+    def cache_info():
+        """Report cache statistics."""
+        nonlocal hits, misses
+        with cache_lock:
+            return (hits, misses)
+
+    def cache_clear():
+        """Clear the cache."""
+        nonlocal hits, misses
+        with cache_lock:
+            cache.clear()
+            hits = misses = 0
+
+    wrapper.cache_clear = cache_clear
+    wrapper.cache_info = cache_info
+    return wrapper

invenio_cache/errors.py

@@ -0,0 +1,41 @@
+# SPDX-FileCopyrightText: 2023 CERN.
+# SPDX-License-Identifier: MIT
+"""Invenio cache errors."""
+
+
+class LockError(Exception):
+    """Base error class for lock-related exceptions."""
+
+    _description = "Base lock error."
+
+    def __init__(self, lock, message=""):
+        """Constructor, a lock can be passed to provide more details on the error."""
+        self.lock = lock
+
+    def __str__(self):
+        """Return str(self)."""
+        return f"Error on lock: {self.lock}: {self._description}"
+
+
+class LockedError(LockError):
+    """Lock is locked error."""
+
+    _description = "Lock was not released yet."
+
+
+class LockReleaseFailed(LockError):
+    """Error when releasing the lock."""
+
+    _description = "Lock failed to be released."
+
+
+class LockAcquireFailed(LockError):
+    """Error when acquiring the lock."""
+
+    _description = "Lock failed to be acquired."
+
+
+class LockRenewPermissionDenied(LockError):
+    """Error when the renewal failed due to permissions."""
+
+    _description = "Lock failed to be renewed due to lack of permissions."

invenio_cache/ext.py

@@ -0,0 +1,52 @@
+# SPDX-FileCopyrightText: 2017-2018 CERN.
+# SPDX-FileCopyrightText: 2025 Graz University of Technology.
+# SPDX-License-Identifier: MIT
+
+"""Cache module for Invenio."""
+
+from __future__ import absolute_import, print_function
+
+from flask_caching import Cache
+from werkzeug.utils import import_string
+
+from . import config
+from ._compat import string_types
+
+
+class InvenioCache(object):
+    """Invenio-Cache extension."""
+
+    def __init__(self, app=None):
+        """Extension initialization."""
+        if app:
+            self.init_app(app)
+
+    def init_app(self, app):
+        """Flask application initialization."""
+        self.init_config(app)
+        self.cache = Cache(app)
+        self.is_authenticated_callback = _callback_factory(
+            app.config["CACHE_IS_AUTHENTICATED_CALLBACK"]
+        )
+        app.extensions["invenio-cache"] = self
+
+    def init_config(self, app):
+        """Initialize configuration."""
+        for k in dir(config):
+            if k.startswith("CACHE_"):
+                app.config.setdefault(k, getattr(config, k))
+
+
+def _callback_factory(callback_imp):
+    """Factory for creating a is authenticated callback."""
+    if callback_imp is None:
+        try:
+            from flask_login import current_user
+
+            return lambda: current_user.is_authenticated
+        except ImportError:
+            return lambda: False
+    elif isinstance(callback_imp, string_types):
+        return import_string(callback_imp)
+    else:
+        return callback_imp

invenio_cache/lock.py

@@ -0,0 +1,220 @@
+# SPDX-FileCopyrightText: 2023 CERN.
+# SPDX-FileCopyrightText: 2025 Graz University of Technology.
+# SPDX-License-Identifier: MIT
+"""Lock mechanisms."""
+
+from datetime import datetime, timezone
+
+from flask import current_app
+
+from invenio_cache.errors import (
+    LockAcquireFailed,
+    LockReleaseFailed,
+    LockRenewPermissionDenied,
+)
+from invenio_cache.proxies import current_cache
+
+
+class Lock:
+    """Base Lock class."""
+
+    def __init__(self, lock_id):
+        """Initialises the lock instance.
+
+        It does not grant access to the lock itself. To access the lock, call ``lock.acquire``.
+        The lock can be used in two ways:
+
+        1) inside a context:
+
+        .. code-block:: python
+
+            with lock(lock_id) as lock:
+                lock.acquire()
+                f()
+
+        2) manually calling each block / unblock mechanism:
+
+        .. code-block:: python
+
+            lock = lock(lock_id)
+            try:
+                lock.acquire()
+                f()
+                lock.release()
+            except LockAcquireFailed:
+                pass
+
+        :param lock_id: id of the lock.
+        :type lock_id: str
+        """
+        self.lock_id = lock_id
+        self._created = datetime.now(timezone.utc)
+
+    def __enter__(self):
+        """Entering the context."""
+        return self
+
+    def __exit__(self, exc_type, *args):
+        """Releases the lock."""
+        # Release the lock only when acquired the lock
+        if exc_type is not LockAcquireFailed:
+            self.release()
+
+    @property
+    def created(self):
+        """Lock creation date time."""
+        return self._created
+
+    def acquire(self, **kwargs):
+        """Attempts to acquire the lock.
+
+        .. warning:
+
+            The method to adcquire the lock must be atomic.
+
+        """
+        raise NotImplementedError
+
+    def release(self):
+        """Attempts to release the lock."""
+        raise NotImplementedError
+
+    def exists(self):
+        """Checks if the lock exists."""
+        raise NotImplementedError
+
+    def __repr__(self):
+        """Lock string representation."""
+        return f"<Lock {self.lock_id}>"
+
+
+class CachedMutex(Lock):
+    """Implements a Mutex using CacheLib API.
+
+    This lock will set a key in a cache when the lock is acquired, and delete the key when
+    the lock is to be deleted.
+    This mechanism is based on the principle that the desired cache's backend provides an atomic
+    write operation (e.g. "write if not exists").
+    """
+
+    _cache = current_cache
+
+    def acquire(self, timeout):
+        """Attempts to acquire the lock.
+
+        The method to adcquire the lock must be atomic.
+
+        If an error occurred with the backend, the exception is logged and re-raised.
+        If the lock was not released, a ``LockReleaseFailed`` exception is raised.
+
+        :returns: ``True`` if the lock was acquired, ``False`` otherwise .
+        :rtype: boolean
+        :param timeout: lock key timeout.
+        :type timeout: int
+        :raises: Exception, LockReleaseFailed
+        """
+        success = False
+        try:
+            # Atomic operation to get the lock
+            success = self._cache.add(self.lock_id, True, timeout=timeout)
+        except:
+            # Unexpected error with the cache, we just log it and re-raise
+            current_app.logger.error(
+                f"Unexpected backend failure when acquiring lock {self.lock_id}."
+            )
+            raise
+
+        if not success:
+            raise LockAcquireFailed(self)
+
+        return success
+
+    def release(self):
+        """Attempts to release the lock.
+
+        If an error occurred with the backend, the exception is logged and re-raised.
+        If the lock was not released, a ``LockReleaseFailed`` exception is raised.
+
+        :returns: ``True`` if the lock was released, ``False`` otherwise .
+        :rtype: boolean
+        :raises: Exception, LockReleaseFailed
+        """
+        success = False
+        try:
+            success = self._cache.delete(self.lock_id)
+        except:
+            # Unexpected error with the cache, we just log it and re-raise
+            current_app.logger.error(
+                f"Unexpected backend failure when releasing lock {self.lock_id}."
+            )
+            raise
+
+        if not success:
+            raise LockReleaseFailed(self)
+
+        return success
+
+    def exists(self):
+        """Checks if the lock exists.
+
+        :return: ``True``if the lock exists, ``False``otherwise.
+        :rtype: bool
+        :raises: Exception
+        """
+        exists = False
+        try:
+            # ``has``is a cheaper operation than ``get``
+            exists = self._cache.has(self.lock_id)
+        except:
+            # Unexpected error with the cache, we just log it and re-raise
+            current_app.logger.error(
+                f"Unexpected backend failure when releasing lock {self.lock_id}."
+            )
+            raise
+        return exists
+
+    def _has_permission(self):
+        """Whether the current lock instance has permission on the physical lock.
+
+        It is empty for now as it may be needed in the future when locks should be "shared" between contexts.
+        """
+        return True
+
+    def acquire_or_renew(self, timeout):
+        """Attempts to acquire the lock. If not possible, renews its timeout.
+
+        The lock's timeout is updated in the cache, effectively prolonging the lock's duration.
+
+        .. note::
+
+            This method requires that the caller has the necessary permission.
+
+        .. warning::
+
+            If the lock didn't exist before renewing, it will be created with the new timeout.
+
+        :param timeout: New timeout, in seconds.
+        :type timeout: int
+        :raises: Exception, LockAcquireFailed, LockRenewPermissionDenied
+        """
+        success = False
+        if not self._has_permission():
+            raise LockRenewPermissionDenied(self)
+
+        # Overwrites previous timeout. If it didn't exist, the lock is created.
+        try:
+            success = self.acquire(timeout=timeout)
+        except LockAcquireFailed:
+            # Renew the lock if it already existed before
+            success = self._cache.set(self.lock_id, True, timeout)
+        except:
+            # Unexpected error with the cache, we just log it and re-raise
+            current_app.logger.error(
+                f"Unexpected backend failure when releasing lock {self.lock_id}."
+            )
+            raise
+
+        if not success:
+            raise LockAcquireFailed(self)
+
+        return success

invenio_cache/proxies.py

@@ -0,0 +1,16 @@
+# SPDX-FileCopyrightText: 2017-2018 CERN.
+# SPDX-License-Identifier: MIT
+
+"""Helper proxies."""
+
+from __future__ import absolute_import, print_function
+
+from flask import current_app
+from werkzeug.local import LocalProxy
+
+current_cache_ext = LocalProxy(lambda: current_app.extensions["invenio-cache"])
+"""Helper proxy to access cache extension object."""
+
+
+current_cache = LocalProxy(lambda: current_app.extensions["invenio-cache"].cache)
+"""Helper proxy to access cache object."""

invenio_cache-3.0.1.dist-info/METADATA

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: invenio-cache
+Version: 3.0.1
+Summary: Cache module for Invenio.
+Project-URL: Repository, https://github.com/inveniosoftware/invenio-cache
+Author-email: CERN <info@inveniosoftware.org>
+License-Expression: MIT
+License-File: AUTHORS.rst
+License-File: LICENSE
+Keywords: cache,invenio
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.9
+Requires-Dist: flask-caching>=1.8.0
+Requires-Dist: invenio-base<3.0.0,>=2.0.0
+Provides-Extra: tests
+Requires-Dist: flask-login>=0.6.3; extra == 'tests'
+Requires-Dist: mock>=2.0.0; extra == 'tests'
+Requires-Dist: pytest-black>=0.6.0; extra == 'tests'
+Requires-Dist: pytest-invenio<5.0.0,>=4.0.0; extra == 'tests'
+Requires-Dist: pytest-mock>=1.6.0; extra == 'tests'
+Requires-Dist: redis>=2.10.5; extra == 'tests'
+Requires-Dist: sphinx>=3; extra == 'tests'
+Description-Content-Type: text/x-rst
+
+..
+    SPDX-FileCopyrightText: 2017-2018 CERN.
+    SPDX-License-Identifier: MIT
+
+===============
+ Invenio-Cache
+===============
+
+.. image:: https://img.shields.io/github/license/inveniosoftware/invenio-cache.svg
+        :target: https://github.com/inveniosoftware/invenio-cache/blob/master/LICENSE
+
+.. image:: https://github.com/inveniosoftware/invenio-cache/workflows/CI/badge.svg
+        :target: https://github.com/inveniosoftware/invenio-cache/actions?query=workflow%3ACI
+
+.. image:: https://img.shields.io/coveralls/inveniosoftware/invenio-cache.svg
+        :target: https://coveralls.io/r/inveniosoftware/invenio-cache
+
+.. image:: https://img.shields.io/pypi/v/invenio-cache.svg
+        :target: https://pypi.org/pypi/invenio-cache
+
+Cache module for Invenio.
+
+Further documentation is available on
+https://invenio-cache.readthedocs.io/

invenio_cache-3.0.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+invenio_cache/__init__.py,sha256=YYpWrx42JnzOkO16mDVXTgsMMRYHtBx6Hx5QY53CRpw,2364
+invenio_cache/_compat.py,sha256=p9vM33BfXEbw6SS7AO7WExSuRQd_zu24lLmmHTN7Xzk,256
+invenio_cache/bccache.py,sha256=LdLkHlNZuyB5R6Rtbn1AL7gw0jy_ofeHX5vitG01pt4,615
+invenio_cache/config.py,sha256=ygnmjnvZYBCbffKYP_N3Ef_tqXQEBgBAO_7GStx2V7E,929
+invenio_cache/decorators.py,sha256=TAFvYijBkW0493NmJXkdgfYObPPtvbuls2zfDEbGjNw,3106
+invenio_cache/errors.py,sha256=yUwb6NEeoBnTWwrZiMbBYO6GeloY24r6Lvghwq-96vQ,1050
+invenio_cache/ext.py,sha256=FjTKOkjrXyZXoWPoaSg7B73nwAuDRA7ZsW-SG7BriQk,1498
+invenio_cache/lock.py,sha256=KrPzY3Zj9kDR-yxI_QWvfX-w8NEaTs9Y8EJItYJoCAg,6567
+invenio_cache/proxies.py,sha256=azcY9VcrMmnAViM_e_bYNOfxYhTX25VQ1UmnGUu4_s8,482
+invenio_cache-3.0.1.dist-info/METADATA,sha256=aujmy7AN8YiqEP4Kbo93sLgEYopxgCpHzx6Rav6yJMo,1709
+invenio_cache-3.0.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+invenio_cache-3.0.1.dist-info/entry_points.txt,sha256=KX9eJfXQN9CEtZ-CWYmrGNRBMRh2O8xKrJfklrAt0RM,131
+invenio_cache-3.0.1.dist-info/licenses/AUTHORS.rst,sha256=cqTAHTkxSGRFSRsCTa-U1xSjGR5NQ0JVQF6_0OuVE-M,128
+invenio_cache-3.0.1.dist-info/licenses/LICENSE,sha256=bi4ieq1faFKHWB4Id2Di1YzNKRiYyy2wu8dYtq9gbNc,1067
+invenio_cache-3.0.1.dist-info/RECORD,,

invenio_cache-3.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

invenio_cache-3.0.1.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[invenio_base.api_apps]
+invenio_cache = invenio_cache:InvenioCache
+
+[invenio_base.apps]
+invenio_cache = invenio_cache:InvenioCache

invenio_cache-3.0.1.dist-info/licenses/AUTHORS.rst

@@ -0,0 +1,8 @@
+..
+    SPDX-FileCopyrightText: 2017-2018 CERN.
+    SPDX-License-Identifier: MIT
+
+Contributors
+============
+
+- Lars Holm Nielsen

invenio_cache-3.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (C) 2017-2018 CERN.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.