limits 4.7.3__py3-none-any.whl → 5.0.0__py3-none-any.whl

limits/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2025-04-12T18:43:47-0700",
+ "date": "2025-04-15T17:28:21-0700",
  "dirty": false,
  "error": null,
- "full-revisionid": "58af4445a2d0b1de9251cd60e847d25267b4830d",
- "version": "4.7.3"
+ "full-revisionid": "eeb02fd85c146292dd70fb798ac90a486ba163bd",
+ "version": "5.0.0"
 }
 '''  # END VERSION_JSON
 

limits/aio/storage/__init__.py

@@ -6,14 +6,12 @@ Implementations of storage backends to be used with
 from __future__ import annotations
 
 from .base import MovingWindowSupport, SlidingWindowCounterSupport, Storage
-from .etcd import EtcdStorage
 from .memcached import MemcachedStorage
 from .memory import MemoryStorage
 from .mongodb import MongoDBStorage
 from .redis import RedisClusterStorage, RedisSentinelStorage, RedisStorage
 
 __all__ = [
-    "EtcdStorage",
     "MemcachedStorage",
     "MemoryStorage",
     "MongoDBStorage",

limits/aio/storage/base.py

@@ -75,16 +75,12 @@ class Storage(LazyDependency, metaclass=StorageRegistry):
         raise NotImplementedError
 
     @abstractmethod
-    async def incr(
-        self, key: str, expiry: int, elastic_expiry: bool = False, amount: int = 1
-    ) -> int:
+    async def incr(self, key: str, expiry: int, 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 elastic_expiry: whether to keep extending the rate limit
-         window every hit.
         :param amount: the number to increment by
         """
         raise NotImplementedError

limits/aio/storage/memcached/__init__.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+import time
+from math import floor
+
+from deprecated.sphinx import versionadded, versionchanged
+from packaging.version import Version
+
+from limits.aio.storage import SlidingWindowCounterSupport, Storage
+from limits.aio.storage.memcached.bridge import MemcachedBridge
+from limits.aio.storage.memcached.emcache import EmcacheBridge
+from limits.aio.storage.memcached.memcachio import MemcachioBridge
+from limits.storage.base import TimestampedSlidingWindow
+from limits.typing import Literal
+
+
+@versionadded(version="2.1")
+@versionchanged(
+    version="5.0",
+    reason="Switched default implementation to :pypi:`memcachio`",
+)
+class MemcachedStorage(Storage, SlidingWindowCounterSupport, TimestampedSlidingWindow):
+    """
+    Rate limit storage with memcached as backend.
+
+    Depends on :pypi:`memcachio`
+    """
+
+    STORAGE_SCHEME = ["async+memcached"]
+    """The storage scheme for memcached to be used in an async context"""
+
+    DEPENDENCIES = {
+        "memcachio": Version("0.3"),
+        "emcache": Version("0.0"),
+    }
+
+    bridge: MemcachedBridge
+    storage_exceptions: tuple[Exception, ...]
+
+    def __init__(
+        self,
+        uri: str,
+        wrap_exceptions: bool = False,
+        implementation: Literal["memcachio", "emcache"] = "memcachio",
+        **options: 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 implementation: Whether to use the client implementation from
+
+         - ``memcachio``: :class:`memcachio.Client`
+         - ``emcache``: :class:`emcache.Client`
+        :param options: all remaining keyword arguments are passed
+         directly to the constructor of :class:`memcachio.Client`
+        :raise ConfigurationError: when :pypi:`memcachio` is not available
+        """
+        if implementation == "emcache":
+            self.bridge = EmcacheBridge(
+                uri, self.dependencies["emcache"].module, **options
+            )
+        else:
+            self.bridge = MemcachioBridge(
+                uri, self.dependencies["memcachio"].module, **options
+            )
+        super().__init__(uri, wrap_exceptions=wrap_exceptions, **options)
+
+    @property
+    def base_exceptions(
+        self,
+    ) -> type[Exception] | tuple[type[Exception], ...]:  # pragma: no cover
+        return self.bridge.base_exceptions
+
+    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
+        """
+        await self.bridge.clear(key)
+
+    async def incr(
+        self,
+        key: str,
+        expiry: float,
+        amount: int = 1,
+        set_expiration_key: bool = True,
+    ) -> 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
+         window every hit.
+        :param amount: the number to increment by
+        :param set_expiration_key: if set to False, the expiration time won't be stored but the key will still expire
+        """
+        return await self.bridge.incr(
+            key, expiry, amount, set_expiration_key=set_expiration_key
+        )
+
+    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 reset(self) -> int | None:
+        raise NotImplementedError
+
+    async def check(self) -> bool:
+        return await self.bridge.check()
+
+    async def acquire_sliding_window_entry(
+        self,
+        key: str,
+        limit: int,
+        expiry: int,
+        amount: int = 1,
+    ) -> bool:
+        if amount > limit:
+            return False
+        now = time.time()
+        previous_key, current_key = self.sliding_window_keys(key, expiry, now)
+        (
+            previous_count,
+            previous_ttl,
+            current_count,
+            _,
+        ) = await self._get_sliding_window_info(previous_key, current_key, expiry, now)
+        t0 = time.time()
+        weighted_count = previous_count * previous_ttl / expiry + current_count
+        if floor(weighted_count) + amount > limit:
+            return False
+        else:
+            # Hit, increase the current counter.
+            # If the counter doesn't exist yet, set twice the theorical expiry.
+            # We don't need the expiration key as it is estimated with the timestamps directly.
+            current_count = await self.incr(
+                current_key, 2 * expiry, amount=amount, set_expiration_key=False
+            )
+            t1 = time.time()
+            actualised_previous_ttl = max(0, previous_ttl - (t1 - t0))
+            weighted_count = (
+                previous_count * actualised_previous_ttl / expiry + current_count
+            )
+            if floor(weighted_count) > limit:
+                # Another hit won the race condition: revert the increment and refuse this hit
+                # Limitation: during high concurrency at the end of the window,
+                # the counter is shifted and cannot be decremented, so less requests than expected are allowed.
+                await self.bridge.decr(current_key, amount, noreply=True)
+                return False
+            return True
+
+    async def get_sliding_window(
+        self, key: str, expiry: int
+    ) -> tuple[int, float, int, float]:
+        now = time.time()
+        previous_key, current_key = self.sliding_window_keys(key, expiry, now)
+        return await self._get_sliding_window_info(
+            previous_key, current_key, expiry, now
+        )
+
+    async def _get_sliding_window_info(
+        self, previous_key: str, current_key: str, expiry: int, now: float
+    ) -> tuple[int, float, int, float]:
+        result = await self.bridge.get_many([previous_key, current_key])
+
+        previous_count = result.get(previous_key.encode("utf-8"), 0)
+        current_count = result.get(current_key.encode("utf-8"), 0)
+
+        if previous_count == 0:
+            previous_ttl = float(0)
+        else:
+            previous_ttl = (1 - (((now - expiry) / expiry) % 1)) * expiry
+        current_ttl = (1 - ((now / expiry) % 1)) * expiry + expiry
+
+        return previous_count, previous_ttl, current_count, current_ttl

limits/aio/storage/memcached/bridge.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import urllib
+from abc import ABC, abstractmethod
+from types import ModuleType
+
+from limits.typing import Iterable
+
+
+class MemcachedBridge(ABC):
+    def __init__(
+        self,
+        uri: str,
+        dependency: ModuleType,
+        **options: float | str | bool,
+    ) -> None:
+        self.uri = uri
+        self.parsed_uri = urllib.parse.urlparse(self.uri)
+        self.dependency = dependency
+        self.hosts = []
+        self.options = options
+
+        sep = self.parsed_uri.netloc.strip().find("@") + 1
+        for loc in self.parsed_uri.netloc.strip()[sep:].split(","):
+            host, port = loc.split(":")
+            self.hosts.append((host, int(port)))
+
+        if self.parsed_uri.username:
+            self.options["username"] = self.parsed_uri.username
+        if self.parsed_uri.password:
+            self.options["password"] = self.parsed_uri.password
+
+    def _expiration_key(self, key: str) -> str:
+        """
+        Return the expiration key for the given counter key.
+
+        Memcached doesn't natively return the expiration time or TTL for a given key,
+        so we implement the expiration time on a separate key.
+        """
+        return key + "/expires"
+
+    @property
+    @abstractmethod
+    def base_exceptions(
+        self,
+    ) -> type[Exception] | tuple[type[Exception], ...]: ...
+
+    @abstractmethod
+    async def get(self, key: str) -> int: ...
+
+    @abstractmethod
+    async def get_many(self, keys: Iterable[str]) -> dict[bytes, int]: ...
+
+    @abstractmethod
+    async def clear(self, key: str) -> None: ...
+
+    @abstractmethod
+    async def decr(self, key: str, amount: int = 1, noreply: bool = False) -> int: ...
+
+    @abstractmethod
+    async def incr(
+        self,
+        key: str,
+        expiry: float,
+        amount: int = 1,
+        set_expiration_key: bool = True,
+    ) -> int: ...
+
+    @abstractmethod
+    async def get_expiry(self, key: str) -> float: ...
+
+    @abstractmethod
+    async def check(self) -> bool: ...

limits/aio/storage/memcached/emcache.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import time
+from math import ceil
+from types import ModuleType
+
+from limits.typing import TYPE_CHECKING, Iterable
+
+from .bridge import MemcachedBridge
+
+if TYPE_CHECKING:
+    import emcache
+
+
+class EmcacheBridge(MemcachedBridge):
+    def __init__(
+        self,
+        uri: str,
+        dependency: ModuleType,
+        **options: float | str | bool,
+    ) -> None:
+        super().__init__(uri, dependency, **options)
+        self._storage = None
+
+    async def get_storage(self) -> emcache.Client:
+        if not self._storage:
+            self._storage = await self.dependency.create_client(
+                [self.dependency.MemcachedHostAddress(h, p) for h, p in self.hosts],
+                **self.options,
+            )
+        assert self._storage
+        return self._storage
+
+    async def get(self, key: str) -> int:
+        item = await (await self.get_storage()).get(key.encode("utf-8"))
+        return item and int(item.value) or 0
+
+    async def get_many(self, keys: Iterable[str]) -> dict[bytes, int]:
+        results = await (await self.get_storage()).get_many(
+            [k.encode("utf-8") for k in keys]
+        )
+        return {k: int(item.value) if item else 0 for k, item in results.items()}
+
+    async def clear(self, key: str) -> None:
+        try:
+            await (await self.get_storage()).delete(key.encode("utf-8"))
+        except self.dependency.NotFoundCommandError:
+            pass
+
+    async def decr(self, key: str, amount: int = 1, noreply: bool = False) -> int:
+        storage = await self.get_storage()
+        limit_key = key.encode("utf-8")
+        try:
+            value = await storage.decrement(limit_key, amount, noreply=noreply) or 0
+        except self.dependency.NotFoundCommandError:
+            value = 0
+        return value
+
+    async def incr(
+        self, key: str, expiry: float, amount: int = 1, set_expiration_key: bool = True
+    ) -> int:
+        storage = await self.get_storage()
+        limit_key = key.encode("utf-8")
+        expire_key = self._expiration_key(key).encode()
+        try:
+            return await storage.increment(limit_key, amount) or amount
+        except self.dependency.NotFoundCommandError:
+            storage = await self.get_storage()
+            try:
+                await storage.add(limit_key, f"{amount}".encode(), exptime=ceil(expiry))
+                if set_expiration_key:
+                    await storage.set(
+                        expire_key,
+                        str(expiry + time.time()).encode("utf-8"),
+                        exptime=ceil(expiry),
+                        noreply=False,
+                    )
+                value = amount
+            except self.dependency.NotStoredStorageCommandError:
+                # Coult not add the key, probably because a concurrent call has added it
+                storage = await self.get_storage()
+                value = await storage.increment(limit_key, amount) or amount
+            return value
+
+    async def get_expiry(self, key: str) -> float:
+        storage = await self.get_storage()
+        item = await storage.get(self._expiration_key(key).encode("utf-8"))
+
+        return item and float(item.value) or time.time()
+        pass
+
+    @property
+    def base_exceptions(
+        self,
+    ) -> type[Exception] | tuple[type[Exception], ...]:  # pragma: no cover
+        return (
+            self.dependency.ClusterNoAvailableNodes,
+            self.dependency.CommandError,
+        )
+
+    async def check(self) -> bool:
+        """
+        Check if storage is healthy by calling the ``get`` command
+        on the key ``limiter-check``
+        """
+        try:
+            storage = await self.get_storage()
+            await storage.get(b"limiter-check")
+
+            return True
+        except:  # noqa
+            return False

limits/aio/storage/memcached/memcachio.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import time
+from math import ceil
+from types import ModuleType
+from typing import TYPE_CHECKING, Iterable
+
+from .bridge import MemcachedBridge
+
+if TYPE_CHECKING:
+    import memcachio
+
+
+class MemcachioBridge(MemcachedBridge):
+    def __init__(
+        self,
+        uri: str,
+        dependency: ModuleType,
+        **options: float | str | bool,
+    ) -> None:
+        super().__init__(uri, dependency, **options)
+        self._storage: memcachio.Client[bytes] | None = None
+
+    @property
+    def base_exceptions(
+        self,
+    ) -> type[Exception] | tuple[type[Exception], ...]:
+        return (
+            self.dependency.errors.NoAvailableNodes,
+            self.dependency.errors.MemcachioConnectionError,
+        )
+
+    async def get_storage(self) -> memcachio.Client[bytes]:
+        if not self._storage:
+            self._storage = self.dependency.Client(
+                [(h, p) for h, p in self.hosts],
+                **self.options,
+            )
+        assert self._storage
+        return self._storage
+
+    async def get(self, key: str) -> int:
+        return (await self.get_many([key])).get(key.encode("utf-8"), 0)
+
+    async def get_many(self, keys: Iterable[str]) -> dict[bytes, int]:
+        """
+        Return multiple counters at once
+
+        :param keys: the keys to get the counter values for
+        """
+        results = await (await self.get_storage()).get(
+            *[k.encode("utf-8") for k in keys]
+        )
+        return {k: int(v.value) for k, v in results.items()}
+
+    async def clear(self, key: str) -> None:
+        await (await self.get_storage()).delete(key.encode("utf-8"))
+
+    async def decr(self, key: str, amount: int = 1, noreply: bool = False) -> int:
+        storage = await self.get_storage()
+        limit_key = key.encode("utf-8")
+        return await storage.decr(limit_key, amount, noreply=noreply) or 0
+
+    async def incr(
+        self, key: str, expiry: float, amount: int = 1, set_expiration_key: bool = True
+    ) -> int:
+        storage = await self.get_storage()
+        limit_key = key.encode("utf-8")
+        expire_key = self._expiration_key(key).encode()
+        if (value := (await storage.incr(limit_key, amount))) is None:
+            storage = await self.get_storage()
+            if await storage.add(limit_key, f"{amount}".encode(), expiry=ceil(expiry)):
+                if set_expiration_key:
+                    await storage.set(
+                        expire_key,
+                        str(expiry + time.time()).encode("utf-8"),
+                        expiry=ceil(expiry),
+                        noreply=False,
+                    )
+                return amount
+            else:
+                storage = await self.get_storage()
+                return await storage.incr(limit_key, amount) or amount
+        return value
+
+    async def get_expiry(self, key: str) -> float:
+        storage = await self.get_storage()
+        expiration_key = self._expiration_key(key).encode("utf-8")
+        item = (await storage.get(expiration_key)).get(expiration_key, None)
+
+        return item and float(item.value) or time.time()
+
+    async def check(self) -> bool:
+        """
+        Check if storage is healthy by calling the ``get`` command
+        on the key ``limiter-check``
+        """
+        try:
+            storage = await self.get_storage()
+            await storage.get(b"limiter-check")
+
+            return True
+        except:  # noqa
+            return False

limits/aio/storage/memory.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import bisect
 import time
 from collections import Counter, defaultdict
 from math import floor
@@ -28,7 +29,7 @@ class MemoryStorage(
 ):
     """
     rate limit storage using :class:`collections.Counter`
-    as an in memory storage for fixed and elastic window strategies,
+    as an in memory storage for fixed & sliding window strategies,
     and a simple list to implement moving window strategy.
     """
 
@@ -61,20 +62,29 @@ class MemoryStorage(
         asyncio.ensure_future(self.__schedule_expiry())
 
     async def __expire_events(self) -> None:
-        for key in list(self.events.keys()):
-            async with self.locks[key]:
-                for event in list(self.events[key]):
-                    if event.expiry <= time.time() and event in self.events[key]:
-                        self.events[key].remove(event)
-                if not self.events.get(key, None):
-                    self.events.pop(key, None)
+        try:
+            now = time.time()
+            for key in list(self.events.keys()):
+                cutoff = await asyncio.to_thread(
+                    lambda evts: bisect.bisect_left(
+                        evts, -now, key=lambda event: -event.expiry
+                    ),
+                    self.events[key],
+                )
+                async with self.locks[key]:
+                    if self.events.get(key, []):
+                        self.events[key] = self.events[key][:cutoff]
+                    if not self.events.get(key, None):
+                        self.events.pop(key, None)
+                        self.locks.pop(key, None)
+
+            for key in list(self.expirations.keys()):
+                if self.expirations[key] <= time.time():
+                    self.storage.pop(key, None)
+                    self.expirations.pop(key, None)
                     self.locks.pop(key, None)
-
-        for key in list(self.expirations.keys()):
-            if self.expirations[key] <= time.time():
-                self.storage.pop(key, None)
-                self.expirations.pop(key, None)
-                self.locks.pop(key, None)
+        except asyncio.CancelledError:
+            return
 
     async def __schedule_expiry(self) -> None:
         if not self.timer or self.timer.done():
@@ -86,26 +96,20 @@ class MemoryStorage(
     ) -> type[Exception] | tuple[type[Exception], ...]:  # pragma: no cover
         return ValueError
 
-    async def incr(
-        self, key: str, expiry: float, elastic_expiry: bool = False, amount: int = 1
-    ) -> int:
+    async def incr(self, key: str, expiry: float, 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 elastic_expiry: whether to keep extending the rate limit
-         window every hit.
         :param amount: the number to increment by
         """
         await self.get(key)
         await self.__schedule_expiry()
         async with self.locks[key]:
             self.storage[key] += amount
-
-            if elastic_expiry or self.storage[key] == amount:
+            if self.storage[key] == amount:
                 self.expirations[key] = time.time() + expiry
-
         return self.storage.get(key, amount)
 
     async def decr(self, key: str, amount: int = 1) -> int:
@@ -165,8 +169,7 @@ class MemoryStorage(
             if entry and entry.atime >= timestamp - expiry:
                 return False
             else:
-                self.events[key][:0] = [Entry(expiry) for _ in range(amount)]
-
+                self.events[key][:0] = [Entry(expiry)] * amount
             return True
 
     async def get_expiry(self, key: str) -> float:
@@ -176,22 +179,6 @@ class MemoryStorage(
 
         return self.expirations.get(key, time.time())
 
-    async def get_num_acquired(self, key: str, expiry: int) -> int:
-        """
-        returns the number of entries already acquired
-
-        :param key: rate limit key to acquire an entry in
-        :param expiry: expiry of the entry
-        """
-        timestamp = time.time()
-
-        return (
-            len([k for k in self.events.get(key, []) if k.atime >= timestamp - expiry])
-            if self.events.get(key)
-            else 0
-        )
-
-    # FIXME: arg limit is not used
     async def get_moving_window(
         self, key: str, limit: int, expiry: int
     ) -> tuple[float, int]:
@@ -203,14 +190,14 @@ class MemoryStorage(
         :param expiry: expiry of entry
         :return: (start of window, number of acquired entries)
         """
-        timestamp = time.time()
-        acquired = await self.get_num_acquired(key, expiry)
-
-        for item in self.events.get(key, [])[::-1]:
-            if item.atime >= timestamp - expiry:
-                return item.atime, acquired
 
-        return timestamp, acquired
+        timestamp = time.time()
+        if events := self.events.get(key, []):
+            oldest = bisect.bisect_left(
+                events, -(timestamp - expiry), key=lambda entry: -entry.atime
+            )
+            return events[oldest - 1].atime, oldest
+        return timestamp, 0
 
     async def acquire_sliding_window_entry(
         self,
@@ -242,7 +229,6 @@ class MemoryStorage(
                 # Limitation: during high concurrency at the end of the window,
                 # the counter is shifted and cannot be decremented, so less requests than expected are allowed.
                 await self.decr(current_key, amount)
-                # print("Concurrent call, reverting the counter increase")
                 return False
             return True
 
@@ -286,3 +272,10 @@ class MemoryStorage(
         self.locks.clear()
 
         return num_items
+
+    def __del__(self) -> None:
+        try:
+            if self.timer and not self.timer.done():
+                self.timer.cancel()
+        except RuntimeError:  # noqa
+            pass