limits 4.1__tar.gz → 4.2__tar.gz

{limits-4.1 → limits-4.2}/HISTORY.rst

@@ -3,6 +3,15 @@
 Changelog
 =========
 
+v4.2
+----
+Release Date: 2025-03-11
+
+  * Feature
+
+    * Add support for using ``redis-py`` instead of ``coredis``
+      which asyncio + redis storages
+
 v4.1
 ----
 Release Date: 2025-03-07
@@ -782,5 +791,6 @@ Release Date: 2015-01-08
 
 
 
+
 
 

{limits-4.1 → limits-4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: limits
-Version: 4.1
+Version: 4.2
 Summary: Rate limiting utilities
 Home-page: https://limits.readthedocs.org
 Author: Ali-Akber Saifee

{limits-4.1 → limits-4.2}/doc/source/async.rst

@@ -10,7 +10,10 @@ A new namespace ``limits.aio`` is available which mirrors the original
 The following async storage backends are implemented:
 
 - In-Memory
-- Redis (via `coredis <https://coredis.readthedocs.org>`_)
+- Redis (via `coredis <https://coredis.readthedocs.org>`_
+  or `redis-py <https://redis-py.readthedocs.io>`_. Refer to
+  :paramref:`limits.aio.storage.RedisStorage.implementation` for
+  details on selecting the dependency)
 - Memcached (via `emcache <https://emcache.readthedocs.org>`_)
 - MongoDB (via `motor <https://motor.readthedocs.org>`_)
 - Etcd (via `aetcd <https://aetcd.readthedocs.org>`_)

{limits-4.1 → limits-4.2}/doc/source/installation.rst

@@ -79,6 +79,12 @@ along with the package using the following extras:
 
    .. literalinclude:: ../../requirements/storage/async-redis.txt
 
+   .. versionadded:: 4.2
+      :pypi:`redis` if installed can be used instead of :pypi:`coredis` by setting
+      :paramref:`~limits.aio.storage.Redis.implementation` to ``redispy``.
+      See :class:`limits.aio.storage.RedisStorage` for more details.
+
+
 .. tab:: Memcached
 
    .. code:: console

{limits-4.1 → limits-4.2}/doc/source/storage.rst

@@ -31,6 +31,11 @@ the results in `github <https://github.com/alisaifee/limits/actions/workflows/co
 
    .. literalinclude:: ../../requirements/storage/async-redis.txt
 
+   .. note::
+     .. versionadded:: 4.2
+        :pypi:`redis` can be used instead of :pypi:`coredis` by setting
+        :paramref:`limits.aio.storage.RedisStorage.implementation` to ``redispy``
+
    `Redis <https://redis.io>`_
 
    .. program-output:: bash -c "cat ../../.github/workflows/compatibility.yml | grep -o -P 'LIMITS_REDIS_SERVER_VERSION=[\d\.]+' | cut -d = -f 2"
@@ -53,6 +58,11 @@ the results in `github <https://github.com/alisaifee/limits/actions/workflows/co
 
    .. literalinclude:: ../../requirements/storage/async-redis.txt
 
+   .. note::
+      .. versionadded:: 4.2
+         :pypi:`redis` can be used instead of :pypi:`coredis` by setting
+         :paramref:`limits.aio.storage.RedisClusterStorage.implementation` to ``redispy``
+
    `Redis cluster <https://redis.io/topics/cluster-tutorial>`_
 
    .. program-output:: bash -c "cat ../../.github/workflows/compatibility.yml | grep -o -P 'LIMITS_REDIS_SERVER_VERSION=[\d\.]+' | cut -d = -f 2"

{limits-4.1 → limits-4.2}/limits/__init__.py

@@ -2,6 +2,8 @@
 Rate limiting with commonly used storage backends
 """
 
+from __future__ import annotations
+
 from . import _version, aio, storage, strategies
 from .limits import (
     RateLimitItem,
@@ -30,4 +32,4 @@ __all__ = [
     "WindowStats",
 ]
 
-__version__ = _version.get_versions()["version"]  # type: ignore
+__version__ = _version.get_versions()["version"]

{limits-4.1 → limits-4.2}/limits/_version.py

@@ -1,5 +1,5 @@
 
-# This file was generated by 'versioneer.py' (0.22) from
+# This file was generated by 'versioneer.py' (0.29) from
 # revision-control system data, or from the parent directory name of an
 # unpacked source archive. Distribution tarballs contain a pre-generated copy
 # of this file.
@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2025-03-07T12:07:00-0800",
+ "date": "2025-03-11T11:27:52-0700",
  "dirty": false,
  "error": null,
- "full-revisionid": "aff8ca13e30c9d754690a2931498f023d35dc62f",
- "version": "4.1"
+ "full-revisionid": "ef5c0911dd6e0c1a412b3f467d0d1503a2fa24ce",
+ "version": "4.2"
 }
 '''  # END VERSION_JSON
 

{limits-4.1 → limits-4.2}/limits/aio/__init__.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from . import storage, strategies
 
 __all__ = [

{limits-4.1 → limits-4.2}/limits/aio/storage/__init__.py

@@ -3,6 +3,8 @@ Implementations of storage backends to be used with
 :class:`limits.aio.strategies.RateLimiter` strategies
 """
 
+from __future__ import annotations
+
 from .base import MovingWindowSupport, SlidingWindowCounterSupport, Storage
 from .etcd import EtcdStorage
 from .memcached import MemcachedStorage

{limits-4.1 → limits-4.2}/limits/aio/storage/etcd.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import asyncio
 import time
 import urllib.parse

{limits-4.1 → limits-4.2}/limits/aio/storage/memcached.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import time
 import urllib.parse
 from collections.abc import Iterable

{limits-4.1 → limits-4.2}/limits/aio/storage/memory.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import asyncio
 import time
 from collections import Counter, defaultdict

limits-4.2/limits/aio/storage/redis/__init__.py

@@ -0,0 +1,341 @@
+from __future__ import annotations
+
+from typing import Optional, Type, Union
+
+from deprecated.sphinx import versionadded, versionchanged
+from packaging.version import Version
+
+from limits.aio.storage import MovingWindowSupport, SlidingWindowCounterSupport, Storage
+from limits.aio.storage.redis.bridge import RedisBridge
+from limits.aio.storage.redis.coredis import CoredisBridge
+from limits.aio.storage.redis.redispy import RedispyBridge
+from limits.typing import Literal
+
+
+@versionadded(version="2.1")
+@versionchanged(
+    version="4.2",
+    reason=(
+        "Added support for using the asyncio redis client from :pypi:`redis`"
+        " through :paramref:`implementation`"
+    ),
+)
+class RedisStorage(Storage, MovingWindowSupport, SlidingWindowCounterSupport):
+    """
+    Rate limit storage with redis as backend.
+
+    Depends on :pypi:`coredis` or :pypi:`redis`
+    """
+
+    STORAGE_SCHEME = ["async+redis", "async+rediss", "async+redis+unix"]
+    """
+    The storage schemes for redis to be used in an async context
+    """
+    DEPENDENCIES = {"redis": Version("5.2.0"), "coredis": Version("3.4.0")}
+    MODE: Literal["BASIC", "CLUSTER", "SENTINEL"] = "BASIC"
+    bridge: RedisBridge
+    storage_exceptions: tuple[Exception, ...]
+
+    def __init__(
+        self,
+        uri: str,
+        wrap_exceptions: bool = False,
+        implementation: Literal["redispy", "coredis"] = "coredis",
+        **options: Union[float, str, bool],
+    ) -> None:
+        """
+        :param uri: uri of the form:
+
+         - ``async+redis://[:password]@host:port``
+         - ``async+redis://[:password]@host:port/db``
+         - ``async+rediss://[:password]@host:port``
+         - ``async+redis+unix:///path/to/sock?db=0`` etc...
+
+         This uri is passed directly to :meth:`coredis.Redis.from_url` or
+          :meth:`redis.asyncio.client.Redis.from_url` with the initial ``async`` removed,
+          except for the case of ``async+redis+unix`` where it is replaced with ``unix``.
+        :param connection_pool: if provided, the redis client is initialized with
+         the connection pool and any other params passed as :paramref:`options`
+        :param wrap_exceptions: Whether to wrap storage exceptions in
+         :exc:`limits.errors.StorageError` before raising it.
+        :param implementation: Whether to use the client implementation from
+         :class:`coredis.Redis` (``coredis``) or :class:`redis.asyncio.client.Redis` (``redispy``).
+        :param options: all remaining keyword arguments are passed
+         directly to the constructor of :class:`coredis.Redis` or :class:`redis.asyncio.client.Redis`
+        :raise ConfigurationError: when the redis library is not available
+        """
+        uri = uri.replace("async+redis", "redis", 1)
+        uri = uri.replace("redis+unix", "unix")
+
+        super().__init__(uri, wrap_exceptions=wrap_exceptions)
+        self.options = options
+        if implementation == "redispy":
+            self.bridge = RedispyBridge(uri, self.dependencies["redis"].module)
+        else:
+            self.bridge = CoredisBridge(uri, self.dependencies["coredis"].module)
+        self.configure_bridge()
+        self.bridge.register_scripts()
+
+    def _current_window_key(self, key: str) -> str:
+        """
+        Return the current window's storage key (Sliding window strategy)
+
+        Contrary to other strategies that have one key per rate limit item,
+        this strategy has two keys per rate limit item than must be on the same machine.
+        To keep the current key and the previous key on the same Redis cluster node,
+        curly braces are added.
+
+        Eg: "{constructed_key}"
+        """
+        return f"{{{key}}}"
+
+    def _previous_window_key(self, key: str) -> str:
+        """
+        Return the previous window's storage key (Sliding window strategy).
+
+        Curvy braces are added on the common pattern with the current window's key,
+        so the current and the previous key are stored on the same Redis cluster node.
+
+        Eg: "{constructed_key}/-1"
+        """
+        return f"{self._current_window_key(key)}/-1"
+
+    def configure_bridge(self) -> None:
+        self.bridge.use_basic(**self.options)
+
+    @property
+    def base_exceptions(
+        self,
+    ) -> Union[Type[Exception], tuple[Type[Exception], ...]]:  # pragma: no cover
+        return self.bridge.base_exceptions
+
+    async def incr(
+        self, key: str, expiry: int, elastic_expiry: bool = False, amount: int = 1
+    ) -> int:
+        """
+        increments the counter for a given rate limit key
+
+        :param key: the key to increment
+        :param expiry: amount in seconds for the key to expire in
+        :param amount: the number to increment by
+        """
+
+        return await self.bridge.incr(key, expiry, elastic_expiry, amount)
+
+    async def get(self, key: str) -> int:
+        """
+        :param key: the key to get the counter value for
+        """
+
+        return await self.bridge.get(key)
+
+    async def clear(self, key: str) -> None:
+        """
+        :param key: the key to clear rate limits for
+        """
+
+        return await self.bridge.clear(key)
+
+    async def acquire_entry(
+        self, key: str, limit: int, expiry: int, amount: int = 1
+    ) -> bool:
+        """
+        :param key: rate limit key to acquire an entry in
+        :param limit: amount of entries allowed
+        :param expiry: expiry of the entry
+        :param amount: the number of entries to acquire
+        """
+
+        return await self.bridge.acquire_entry(key, limit, expiry, amount)
+
+    async def get_moving_window(
+        self, key: str, limit: int, expiry: int
+    ) -> tuple[float, int]:
+        """
+        returns the starting point and the number of entries in the moving
+        window
+
+        :param key: rate limit key
+        :param expiry: expiry of entry
+        :return: (previous count, previous TTL, current count, current TTL)
+        """
+        return await self.bridge.get_moving_window(key, limit, expiry)
+
+    async def acquire_sliding_window_entry(
+        self,
+        key: str,
+        limit: int,
+        expiry: int,
+        amount: int = 1,
+    ) -> bool:
+        current_key = self._current_window_key(key)
+        previous_key = self._previous_window_key(key)
+        return await self.bridge.acquire_sliding_window_entry(
+            previous_key, current_key, limit, expiry, amount
+        )
+
+    async def get_sliding_window(
+        self, key: str, expiry: int
+    ) -> tuple[int, float, int, float]:
+        previous_key = self._previous_window_key(key)
+        current_key = self._current_window_key(key)
+        return await self.bridge.get_sliding_window(previous_key, current_key, expiry)
+
+    async def get_expiry(self, key: str) -> float:
+        """
+        :param key: the key to get the expiry for
+        """
+
+        return await self.bridge.get_expiry(key)
+
+    async def check(self) -> bool:
+        """
+        Check if storage is healthy by calling ``PING``
+        """
+
+        return await self.bridge.check()
+
+    async def reset(self) -> Optional[int]:
+        """
+        This function calls a Lua Script to delete keys prefixed with
+        ``self.PREFIX`` in blocks of 5000.
+
+        .. warning:: This operation was designed to be fast, but was not tested
+           on a large production based system. Be careful with its usage as it
+           could be slow on very large data sets.
+        """
+
+        return await self.bridge.lua_reset()
+
+
+@versionadded(version="2.1")
+@versionchanged(
+    version="4.2",
+    reason="Added support for using the asyncio redis client from :pypi:`redis` ",
+)
+class RedisClusterStorage(RedisStorage):
+    """
+    Rate limit storage with redis cluster as backend
+
+    Depends on :pypi:`coredis` or :pypi:`redis`
+    """
+
+    STORAGE_SCHEME = ["async+redis+cluster"]
+    """
+    The storage schemes for redis cluster to be used in an async context
+    """
+
+    MODE = "CLUSTER"
+
+    def __init__(
+        self,
+        uri: str,
+        wrap_exceptions: bool = False,
+        implementation: Literal["redispy", "coredis"] = "coredis",
+        **options: Union[float, str, bool],
+    ) -> None:
+        """
+        :param uri: url of the form
+         ``async+redis+cluster://[:password]@host:port,host:port``
+        :param wrap_exceptions: Whether to wrap storage exceptions in
+         :exc:`limits.errors.StorageError` before raising it.
+        :param implementation: Whether to use the client implementation from
+         :class:`coredis.RedisCluster` (``coredis``) or :class:`redis.asyncio.cluster.RedisCluster` (``redispy``).
+        :param options: all remaining keyword arguments are passed
+         directly to the constructor of :class:`coredis.RedisCluster` or
+         :class:`redis.asyncio.RedisCluster`
+        :raise ConfigurationError: when the redis library is not
+         available or if the redis host cannot be pinged.
+        """
+        super().__init__(
+            uri,
+            wrap_exceptions=wrap_exceptions,
+            implementation=implementation,
+            **options,
+        )
+
+    def configure_bridge(self) -> None:
+        self.bridge.use_cluster(**self.options)
+
+    async def reset(self) -> Optional[int]:
+        """
+        Redis Clusters are sharded and deleting across shards
+        can't be done atomically. Because of this, this reset loops over all
+        keys that are prefixed with ``self.PREFIX`` and calls delete on them,
+        one at a time.
+
+        .. warning:: This operation was not tested with extremely large data sets.
+           On a large production based system, care should be taken with its
+           usage as it could be slow on very large data sets
+        """
+
+        return await self.bridge.reset()
+
+
+@versionadded(version="2.1")
+@versionchanged(
+    version="4.2",
+    reason="Added support for using the asyncio redis client from :pypi:`redis` ",
+)
+class RedisSentinelStorage(RedisStorage):
+    """
+    Rate limit storage with redis sentinel as backend
+
+    Depends on :pypi:`coredis` or :pypi:`redis`
+    """
+
+    STORAGE_SCHEME = ["async+redis+sentinel"]
+    """The storage scheme for redis accessed via a redis sentinel installation"""
+
+    MODE = "SENTINEL"
+
+    DEPENDENCIES = {
+        "redis": Version("5.2.0"),
+        "coredis": Version("3.4.0"),
+        "coredis.sentinel": Version("3.4.0"),
+    }
+
+    def __init__(
+        self,
+        uri: str,
+        wrap_exceptions: bool = False,
+        implementation: Literal["redispy", "coredis"] = "coredis",
+        service_name: Optional[str] = None,
+        use_replicas: bool = True,
+        sentinel_kwargs: Optional[dict[str, Union[float, str, bool]]] = None,
+        **options: Union[float, str, bool],
+    ):
+        """
+        :param uri: url of the form
+         ``async+redis+sentinel://host:port,host:port/service_name``
+        :param wrap_exceptions: Whether to wrap storage exceptions in
+         :exc:`limits.errors.StorageError` before raising it.
+        :param implementation: Whether to use the client implementation from
+         :class:`coredis.sentinel.Sentinel` (``coredis``) or
+         :class:`redis.asyncio.sentinel.Sentinel` (``redispy``)
+        :param service_name: sentinel service name (if not provided in `uri`)
+        :param use_replicas: Whether to use replicas for read only operations
+        :param sentinel_kwargs: optional arguments to pass as
+         `sentinel_kwargs`` to :class:`coredis.sentinel.Sentinel` or
+         :class:`redis.asyncio.Sentinel`
+        :param options: all remaining keyword arguments are passed
+         directly to the constructor of :class:`coredis.sentinel.Sentinel` or
+         :class:`redis.asyncio.sentinel.Sentinel`
+        :raise ConfigurationError: when the redis library is not available
+         or if the redis primary host cannot be pinged.
+        """
+
+        self.service_name = service_name
+        self.use_replicas = use_replicas
+        self.sentinel_kwargs = sentinel_kwargs
+        super().__init__(
+            uri,
+            wrap_exceptions=wrap_exceptions,
+            implementation=implementation,
+            **options,
+        )
+
+    def configure_bridge(self) -> None:
+        self.bridge.use_sentinel(
+            self.service_name, self.use_replicas, self.sentinel_kwargs, **self.options
+        )

limits-4.2/limits/aio/storage/redis/bridge.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+import urllib
+from abc import ABC, abstractmethod
+from types import ModuleType
+
+from limits.typing import Optional, Type, Union
+from limits.util import get_package_data
+
+
+class RedisBridge(ABC):
+    PREFIX = "LIMITS"
+    RES_DIR = "resources/redis/lua_scripts"
+
+    SCRIPT_MOVING_WINDOW = get_package_data(f"{RES_DIR}/moving_window.lua")
+    SCRIPT_ACQUIRE_MOVING_WINDOW = get_package_data(
+        f"{RES_DIR}/acquire_moving_window.lua"
+    )
+    SCRIPT_CLEAR_KEYS = get_package_data(f"{RES_DIR}/clear_keys.lua")
+    SCRIPT_INCR_EXPIRE = get_package_data(f"{RES_DIR}/incr_expire.lua")
+    SCRIPT_SLIDING_WINDOW = get_package_data(f"{RES_DIR}/sliding_window.lua")
+    SCRIPT_ACQUIRE_SLIDING_WINDOW = get_package_data(
+        f"{RES_DIR}/acquire_sliding_window.lua"
+    )
+
+    def __init__(
+        self,
+        uri: str,
+        dependency: ModuleType,
+    ) -> None:
+        self.uri = uri
+        self.parsed_uri = urllib.parse.urlparse(self.uri)
+        self.dependency = dependency
+        self.parsed_auth = {}
+        if self.parsed_uri.username:
+            self.parsed_auth["username"] = self.parsed_uri.username
+        if self.parsed_uri.password:
+            self.parsed_auth["password"] = self.parsed_uri.password
+
+    def prefixed_key(self, key: str) -> str:
+        return f"{self.PREFIX}:{key}"
+
+    @abstractmethod
+    def register_scripts(self) -> None: ...
+
+    @abstractmethod
+    def use_sentinel(
+        self,
+        service_name: Optional[str],
+        use_replicas: bool,
+        sentinel_kwargs: Optional[dict[str, Union[str, float, bool]]],
+        **options: Union[str, float, bool],
+    ) -> None: ...
+
+    @abstractmethod
+    def use_basic(self, **options: Union[str, float, bool]) -> None: ...
+
+    @abstractmethod
+    def use_cluster(self, **options: Union[str, float, bool]) -> None: ...
+
+    @property
+    @abstractmethod
+    def base_exceptions(
+        self,
+    ) -> Union[Type[Exception], tuple[Type[Exception], ...]]: ...
+
+    @abstractmethod
+    async def incr(
+        self,
+        key: str,
+        expiry: int,
+        elastic_expiry: bool = False,
+        amount: int = 1,
+    ) -> int: ...
+
+    @abstractmethod
+    async def get(self, key: str) -> int: ...
+
+    @abstractmethod
+    async def clear(self, key: str) -> None: ...
+
+    @abstractmethod
+    async def get_moving_window(
+        self, key: str, limit: int, expiry: int
+    ) -> tuple[float, int]: ...
+
+    @abstractmethod
+    async def get_sliding_window(
+        self, previous_key: str, current_key: str, expiry: int
+    ) -> tuple[int, float, int, float]: ...
+
+    @abstractmethod
+    async def acquire_entry(
+        self,
+        key: str,
+        limit: int,
+        expiry: int,
+        amount: int = 1,
+    ) -> bool: ...
+
+    @abstractmethod
+    async def acquire_sliding_window_entry(
+        self,
+        previous_key: str,
+        current_key: str,
+        limit: int,
+        expiry: int,
+        amount: int = 1,
+    ) -> bool: ...
+
+    @abstractmethod
+    async def get_expiry(self, key: str) -> float: ...
+
+    @abstractmethod
+    async def check(self) -> bool: ...
+
+    @abstractmethod
+    async def reset(self) -> Optional[int]: ...
+
+    @abstractmethod
+    async def lua_reset(self) -> Optional[int]: ...