limits 3.7.0__tar.gz → 3.8.0__tar.gz

{limits-3.7.0 → limits-3.8.0}/HISTORY.rst

@@ -3,6 +3,16 @@
 Changelog
 =========
 
+v3.8.0
+------
+Release Date: 2024-02-14
+
+* Features
+
+  * Add option to wrap storage errors with a ``StorageError``
+    exception
+
+
 v3.7.0
 ------
 Release Date: 2023-11-24
@@ -638,5 +648,6 @@ Release Date: 2015-01-08
 
 
 
+
 
 

{limits-3.7.0 → limits-3.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: limits
-Version: 3.7.0
+Version: 3.8.0
 Summary: Rate limiting utilities
 Home-page: https://limits.readthedocs.org
 Author: Ali-Akber Saifee
@@ -76,12 +76,6 @@ limits
 
 **limits** is a python library to perform rate limiting with commonly used storage backends (Redis, Memcached, MongoDB & Etcd).
 
-----
-
-Sponsored by Zuplo - fully-managed, programmable API Management platform.
-Add rate limiting and more to your public API in minutes, try it at `zuplo.com <https://zuplo.link/3DZM9Ej>`_
-
-----
 
 Supported Strategies
 ====================

{limits-3.7.0 → limits-3.8.0}/README.rst

@@ -18,12 +18,6 @@ limits
 
 **limits** is a python library to perform rate limiting with commonly used storage backends (Redis, Memcached, MongoDB & Etcd).
 
-----
-
-Sponsored by Zuplo - fully-managed, programmable API Management platform.
-Add rate limiting and more to your public API in minutes, try it at `zuplo.com <https://zuplo.link/3DZM9Ej>`_
-
-----
 
 Supported Strategies
 ====================

{limits-3.7.0 → limits-3.8.0}/doc/source/api.rst

@@ -203,3 +203,5 @@ Exceptions
    :no-inherited-members:
 .. autoexception:: limits.errors.ConcurrentUpdateError
    :no-inherited-members:
+.. autoexception:: limits.errors.StorageError
+   :no-inherited-members:

{limits-3.7.0 → limits-3.8.0}/limits/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2023-11-24T14:02:38-0800",
+ "date": "2024-02-14T15:45:28-0800",
  "dirty": false,
  "error": null,
- "full-revisionid": "0946fdcd3b9509041a823d3bb1b63ea1de9ab6ee",
- "version": "3.7.0"
+ "full-revisionid": "f1fe9f3efffef2f4c5975a93a069a8b759d3a240",
+ "version": "3.8.0"
 }
 '''  # END VERSION_JSON
 

{limits-3.7.0 → limits-3.8.0}/limits/aio/storage/base.py

@@ -1,12 +1,43 @@
+from __future__ import annotations
+
+import functools
 from abc import ABC, abstractmethod
+from typing import Any, cast
 
 from deprecated.sphinx import versionadded
 
+from limits import errors
 from limits.storage.registry import StorageRegistry
-from limits.typing import List, Optional, Tuple, Union
+from limits.typing import (
+    Awaitable,
+    Callable,
+    List,
+    Optional,
+    P,
+    R,
+    Tuple,
+    Type,
+    Union,
+)
 from limits.util import LazyDependency
 
 
+def _wrap_errors(
+    storage: Storage,
+    fn: Callable[P, Awaitable[R]],
+) -> Callable[P, Awaitable[R]]:
+    @functools.wraps(fn)
+    async def inner(*args: P.args, **kwargs: P.kwargs) -> R:
+        try:
+            return await fn(*args, **kwargs)
+        except storage.base_exceptions as exc:
+            if storage.wrap_exceptions:
+                raise errors.StorageError(exc) from exc
+            raise
+
+    return inner
+
+
 @versionadded(version="2.1")
 class Storage(LazyDependency, metaclass=StorageRegistry):
     """
@@ -16,10 +47,38 @@ class Storage(LazyDependency, metaclass=StorageRegistry):
     STORAGE_SCHEME: Optional[List[str]]
     """The storage schemes to register against this implementation"""
 
+    def __new__(cls, *args: Any, **kwargs: Any) -> Storage:  # type: ignore[misc]
+        inst = super().__new__(cls)
+
+        for method in {
+            "incr",
+            "get",
+            "get_expiry",
+            "check",
+            "reset",
+            "clear",
+        }:
+            setattr(inst, method, _wrap_errors(inst, getattr(inst, method)))
+
+        return inst
+
     def __init__(
-        self, uri: Optional[str] = None, **options: Union[float, str, bool]
+        self,
+        uri: Optional[str] = None,
+        wrap_exceptions: bool = False,
+        **options: Union[float, str, bool],
     ) -> None:
+        """
+        :param wrap_exceptions: Whether to wrap storage exceptions in
+         :exc:`limits.errors.StorageError` before raising it.
+        """
         super().__init__()
+        self.wrap_exceptions = wrap_exceptions
+
+    @property
+    @abstractmethod
+    def base_exceptions(self) -> Union[Type[Exception], Tuple[Type[Exception], ...]]:
+        raise NotImplementedError
 
     @abstractmethod
     async def incr(
@@ -80,6 +139,22 @@ class MovingWindowSupport(ABC):
     the moving window strategy
     """
 
+    def __new__(cls, *args: Any, **kwargs: Any) -> MovingWindowSupport:  # type: ignore[misc]
+        inst = super().__new__(cls)
+
+        for method in {
+            "acquire_entry",
+            "get_moving_window",
+        }:
+            setattr(
+                inst,
+                method,
+                _wrap_errors(cast(Storage, inst), getattr(inst, method)),
+            )
+
+        return inst
+
+    @abstractmethod
     async def acquire_entry(
         self, key: str, limit: int, expiry: int, amount: int = 1
     ) -> bool:
@@ -91,6 +166,7 @@ class MovingWindowSupport(ABC):
         """
         raise NotImplementedError
 
+    @abstractmethod
     async def get_moving_window(
         self, key: str, limit: int, expiry: int
     ) -> Tuple[int, int]:

{limits-3.7.0 → limits-3.8.0}/limits/aio/storage/etcd.py

@@ -1,7 +1,7 @@
 import asyncio
 import time
 import urllib.parse
-from typing import TYPE_CHECKING, Optional
+from typing import TYPE_CHECKING, Optional, Tuple, Type, Union
 
 from limits.aio.storage.base import Storage
 from limits.errors import ConcurrentUpdateError
@@ -46,6 +46,12 @@ class EtcdStorage(Storage):
         )
         self.max_retries = max_retries
 
+    @property
+    def base_exceptions(
+        self,
+    ) -> Union[Type[Exception], Tuple[Type[Exception], ...]]:  # pragma: no cover
+        return self.lib.ClientError  # type: ignore[no-any-return]
+
     def prefixed_key(self, key: str) -> bytes:
         return f"{self.PREFIX}/{key}".encode()
 

{limits-3.7.0 → limits-3.8.0}/limits/aio/storage/memcached.py

@@ -4,7 +4,7 @@ import urllib.parse
 from deprecated.sphinx import versionadded
 
 from limits.aio.storage.base import Storage
-from limits.typing import EmcacheClientP, Optional, Union
+from limits.typing import EmcacheClientP, Optional, Tuple, Type, Union
 
 
 @versionadded(version="2.1")
@@ -20,10 +20,17 @@ class MemcachedStorage(Storage):
 
     DEPENDENCIES = ["emcache"]
 
-    def __init__(self, uri: str, **options: Union[float, str, bool]) -> None:
+    def __init__(
+        self,
+        uri: str,
+        wrap_exceptions: bool = False,
+        **options: Union[float, str, bool],
+    ) -> None:
         """
         :param uri: memcached location of the form
          ``async+memcached://host:port,host:port``
+        :param wrap_exceptions: Whether to wrap storage exceptions in
+         :exc:`limits.errors.StorageError` before raising it.
         :param options: all remaining keyword arguments are passed
          directly to the constructor of :class:`emcache.Client`
         :raise ConfigurationError: when :pypi:`emcache` is not available
@@ -38,9 +45,18 @@ class MemcachedStorage(Storage):
 
         self._options = options
         self._storage = None
-        super().__init__(uri, **options)
+        super().__init__(uri, wrap_exceptions=wrap_exceptions, **options)
         self.dependency = self.dependencies["emcache"].module
 
+    @property
+    def base_exceptions(
+        self,
+    ) -> Union[Type[Exception], Tuple[Type[Exception], ...]]:  # pragma: no cover
+        return (
+            self.dependency.ClusterNoAvailableNodes,
+            self.dependency.CommandError,
+        )
+
     async def get_storage(self) -> EmcacheClientP:
         if not self._storage:
             self._storage = await self.dependency.create_client(

{limits-3.7.0 → limits-3.8.0}/limits/aio/storage/memory.py

@@ -6,7 +6,7 @@ from deprecated.sphinx import versionadded
 
 import limits.typing
 from limits.aio.storage.base import MovingWindowSupport, Storage
-from limits.typing import Dict, List, Optional, Tuple
+from limits.typing import Dict, List, Optional, Tuple, Type, Union
 
 
 class LockableEntry(asyncio.Lock):
@@ -30,12 +30,20 @@ class MemoryStorage(Storage, MovingWindowSupport):
     async context
     """
 
-    def __init__(self, uri: Optional[str] = None, **_: str) -> None:
+    def __init__(
+        self, uri: Optional[str] = None, wrap_exceptions: bool = False, **_: str
+    ) -> None:
         self.storage: limits.typing.Counter[str] = Counter()
         self.expirations: Dict[str, float] = {}
         self.events: Dict[str, List[LockableEntry]] = {}
         self.timer: Optional[asyncio.Task[None]] = None
-        super().__init__(uri, **_)
+        super().__init__(uri, wrap_exceptions=wrap_exceptions, **_)
+
+    @property
+    def base_exceptions(
+        self,
+    ) -> Union[Type[Exception], Tuple[Type[Exception], ...]]:  # pragma: no cover
+        return ValueError
 
     async def __expire_events(self) -> None:
         for key in self.events.keys():

{limits-3.7.0 → limits-3.8.0}/limits/aio/storage/mongodb.py

@@ -9,7 +9,8 @@ from typing import Any, cast
 from deprecated.sphinx import versionadded
 
 from limits.aio.storage.base import MovingWindowSupport, Storage
-from limits.typing import Dict, Optional, ParamSpec, Tuple, TypeVar, Union
+from limits.typing import Dict, Optional, ParamSpec, Tuple, Type, TypeVar, Union
+from limits.util import get_dependency
 
 P = ParamSpec("P")
 R = TypeVar("R")
@@ -40,6 +41,7 @@ class MongoDBStorage(Storage, MovingWindowSupport):
         self,
         uri: str,
         database_name: str = "limits",
+        wrap_exceptions: bool = False,
         **options: Union[float, str, bool],
     ) -> None:
         """
@@ -47,6 +49,8 @@ class MongoDBStorage(Storage, MovingWindowSupport):
          This uri is passed directly to :class:`~motor.motor_asyncio.AsyncIOMotorClient`
         :param database_name: The database to use for storing the rate limit
          collections.
+        :param wrap_exceptions: Whether to wrap storage exceptions in
+         :exc:`limits.errors.StorageError` before raising it.
         :param options: all remaining keyword arguments are merged with
          :data:`DEFAULT_OPTIONS` and passed to the constructor of
          :class:`~motor.motor_asyncio.AsyncIOMotorClient`
@@ -58,10 +62,11 @@ class MongoDBStorage(Storage, MovingWindowSupport):
         [mongo_opts.setdefault(k, v) for k, v in self.DEFAULT_OPTIONS.items()]
         uri = uri.replace("async+mongodb", "mongodb", 1)
 
-        super().__init__(uri, **options)
+        super().__init__(uri, wrap_exceptions=wrap_exceptions, **options)
 
         self.dependency = self.dependencies["motor.motor_asyncio"]
         self.proxy_dependency = self.dependencies["pymongo"]
+        self.lib_errors, _ = get_dependency("pymongo.errors")
 
         self.storage = self.dependency.module.AsyncIOMotorClient(uri, **mongo_opts)
         # TODO: Fix this hack. It was noticed when running a benchmark
@@ -72,6 +77,12 @@ class MongoDBStorage(Storage, MovingWindowSupport):
         self.__database_name = database_name
         self.__indices_created = False
 
+    @property
+    def base_exceptions(
+        self,
+    ) -> Union[Type[Exception], Tuple[Type[Exception], ...]]:  # pragma: no cover
+        return self.lib_errors.PyMongoError  # type: ignore
+
     @property
     def database(self):  # type: ignore
         return self.storage.get_database(self.__database_name)
@@ -257,8 +268,9 @@ class MongoDBStorage(Storage, MovingWindowSupport):
             await self.database.windows.update_one(
                 {
                     "_id": key,
-                    "entries.%d"
-                    % (limit - amount): {"$not": {"$gte": timestamp - expiry}},
+                    "entries.%d" % (limit - amount): {
+                        "$not": {"$gte": timestamp - expiry}
+                    },
                 },
                 updates,
                 upsert=True,

{limits-3.7.0 → limits-3.8.0}/limits/aio/storage/redis.py

@@ -7,7 +7,7 @@ from packaging.version import Version
 
 from limits.aio.storage.base import MovingWindowSupport, Storage
 from limits.errors import ConfigurationError
-from limits.typing import AsyncRedisClient, Dict, Optional, Tuple, Union
+from limits.typing import AsyncRedisClient, Dict, Optional, Tuple, Type, Union
 from limits.util import get_package_data
 
 if TYPE_CHECKING:
@@ -159,6 +159,7 @@ class RedisStorage(RedisInteractor, Storage, MovingWindowSupport):
         self,
         uri: str,
         connection_pool: Optional["coredis.ConnectionPool"] = None,
+        wrap_exceptions: bool = False,
         **options: Union[float, str, bool],
     ) -> None:
         """
@@ -167,13 +168,15 @@ class RedisStorage(RedisInteractor, Storage, MovingWindowSupport):
          - ``async+redis://[:password]@host:port``
          - ``async+redis://[:password]@host:port/db``
          - ``async+rediss://[:password]@host:port``
-         - ``async+unix:///path/to/sock`` etc...
+         - ``async+redis+unix:///path/to/sock?db=0`` etc...
 
          This uri is passed directly to :meth:`coredis.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 options: all remaining keyword arguments are passed
          directly to the constructor of :class:`coredis.Redis`
         :raise ConfigurationError: when the redis library is not available
@@ -181,7 +184,7 @@ class RedisStorage(RedisInteractor, Storage, MovingWindowSupport):
         uri = uri.replace("async+redis", "redis", 1)
         uri = uri.replace("redis+unix", "unix")
 
-        super().__init__(uri, **options)
+        super().__init__(uri, wrap_exceptions=wrap_exceptions, **options)
 
         self.dependency = self.dependencies["coredis"].module
 
@@ -194,6 +197,12 @@ class RedisStorage(RedisInteractor, Storage, MovingWindowSupport):
 
         self.initialize_storage(uri)
 
+    @property
+    def base_exceptions(
+        self,
+    ) -> Union[Type[Exception], Tuple[Type[Exception], ...]]:  # pragma: no cover
+        return self.dependency.RedisError  # type: ignore[no-any-return]
+
     def initialize_storage(self, _uri: str) -> None:
         # all these methods are coroutines, so must be called with await
         self.lua_moving_window = self.storage.register_script(self.SCRIPT_MOVING_WINDOW)
@@ -268,8 +277,8 @@ class RedisStorage(RedisInteractor, Storage, MovingWindowSupport):
 
     async def reset(self) -> Optional[int]:
         """
-        This function calls a Lua Script to delete keys prefixed with `self.PREFIX`
-        in block of 5000.
+        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
@@ -298,7 +307,12 @@ class RedisClusterStorage(RedisStorage):
     }
     "Default options passed to :class:`coredis.RedisCluster`"
 
-    def __init__(self, uri: str, **options: Union[float, str, bool]) -> None:
+    def __init__(
+        self,
+        uri: str,
+        wrap_exceptions: bool = False,
+        **options: Union[float, str, bool],
+    ) -> None:
         """
         :param uri: url of the form
          ``async+redis+cluster://[:password]@host:port,host:port``
@@ -322,7 +336,9 @@ class RedisClusterStorage(RedisStorage):
             host, port = loc.split(":")
             cluster_hosts.append({"host": host, "port": int(port)})
 
-        super(RedisStorage, self).__init__(uri, **options)
+        super(RedisStorage, self).__init__(
+            uri, wrap_exceptions=wrap_exceptions, **options
+        )
 
         self.dependency = self.dependencies["coredis"].module
 
@@ -336,7 +352,7 @@ class RedisClusterStorage(RedisStorage):
         """
         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,
+        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.

{limits-3.7.0 → limits-3.8.0}/limits/errors.py

@@ -17,3 +17,12 @@ class ConcurrentUpdateError(Exception):
 
     def __init__(self, key: str, attempts: int) -> None:
         super().__init__(f"Unable to update {key} after {attempts} retries")
+
+
+class StorageError(Exception):
+    """
+    Error raised when an error is encountered in a storage
+    """
+
+    def __init__(self, storage_error: Exception) -> None:
+        self.storage_error = storage_error

{limits-3.7.0 → limits-3.8.0}/limits/limits.py

@@ -1,6 +1,7 @@
 """
 
 """
+
 from __future__ import annotations
 
 from functools import total_ordering

{limits-3.7.0 → limits-3.8.0}/limits/storage/base.py

@@ -1,11 +1,38 @@
+from __future__ import annotations
+
+import functools
 import threading
 from abc import ABC, abstractmethod
+from typing import Any, cast
 
+from limits import errors
 from limits.storage.registry import StorageRegistry
-from limits.typing import List, Optional, Tuple, Union
+from limits.typing import (
+    Callable,
+    List,
+    Optional,
+    P,
+    R,
+    Tuple,
+    Type,
+    Union,
+)
 from limits.util import LazyDependency
 
 
+def _wrap_errors(storage: Storage, fn: Callable[P, R]) -> Callable[P, R]:
+    @functools.wraps(fn)
+    def inner(*args: P.args, **kwargs: P.kwargs) -> R:
+        try:
+            return fn(*args, **kwargs)
+        except storage.base_exceptions as exc:
+            if storage.wrap_exceptions:
+                raise errors.StorageError(exc) from exc
+            raise
+
+    return inner
+
+
 class Storage(LazyDependency, metaclass=StorageRegistry):
     """
     Base class to extend when implementing a storage backend.
@@ -14,9 +41,40 @@ class Storage(LazyDependency, metaclass=StorageRegistry):
     STORAGE_SCHEME: Optional[List[str]]
     """The storage schemes to register against this implementation"""
 
-    def __init__(self, uri: Optional[str] = None, **options: Union[float, str, bool]):
+    def __new__(cls, *args: Any, **kwargs: Any) -> Storage:  # type: ignore[misc]
+        inst = super().__new__(cls)
+
+        for method in {
+            "incr",
+            "get",
+            "get_expiry",
+            "check",
+            "reset",
+            "clear",
+        }:
+            setattr(inst, method, _wrap_errors(inst, getattr(inst, method)))
+
+        return inst
+
+    def __init__(
+        self,
+        uri: Optional[str] = None,
+        wrap_exceptions: bool = False,
+        **options: Union[float, str, bool],
+    ):
+        """
+        :param wrap_exceptions: Whether to wrap storage exceptions in
+         :exc:`limits.errors.StorageError` before raising it.
+        """
+
         self.lock = threading.RLock()
         super().__init__()
+        self.wrap_exceptions = wrap_exceptions
+
+    @property
+    @abstractmethod
+    def base_exceptions(self) -> Union[Type[Exception], Tuple[Type[Exception], ...]]:
+        raise NotImplementedError
 
     @abstractmethod
     def incr(
@@ -77,6 +135,22 @@ class MovingWindowSupport(ABC):
     the moving window strategy
     """
 
+    def __new__(cls, *args: Any, **kwargs: Any) -> MovingWindowSupport:  # type: ignore[misc]
+        inst = super().__new__(cls)
+
+        for method in {
+            "acquire_entry",
+            "get_moving_window",
+        }:
+            setattr(
+                inst,
+                method,
+                _wrap_errors(cast(Storage, inst), getattr(inst, method)),
+            )
+
+        return inst
+
+    @abstractmethod
     def acquire_entry(self, key: str, limit: int, expiry: int, amount: int = 1) -> bool:
         """
         :param key: rate limit key to acquire an entry in
@@ -86,6 +160,7 @@ class MovingWindowSupport(ABC):
         """
         raise NotImplementedError
 
+    @abstractmethod
     def get_moving_window(self, key: str, limit: int, expiry: int) -> Tuple[int, int]:
         """
         returns the starting point and the number of entries in the moving

{limits-3.7.0 → limits-3.8.0}/limits/storage/etcd.py

@@ -1,6 +1,6 @@
 import time
 import urllib.parse
-from typing import TYPE_CHECKING, Optional
+from typing import TYPE_CHECKING, Optional, Tuple, Type, Union
 
 from limits.errors import ConcurrentUpdateError
 from limits.storage.base import Storage
@@ -44,6 +44,12 @@ class EtcdStorage(Storage):
         )
         self.max_retries = max_retries
 
+    @property
+    def base_exceptions(
+        self,
+    ) -> Union[Type[Exception], Tuple[Type[Exception], ...]]:  # pragma: no cover
+        return self.lib.Etcd3Exception  # type: ignore[no-any-return]
+
     def prefixed_key(self, key: str) -> bytes:
         return f"{self.PREFIX}/{key}".encode()