taplimit 0.1.0__py3-none-any.whl

taplimit/__init__.py

@@ -0,0 +1,11 @@
+"""Small, typed, thread-safe in-process rate-limit decorator: N calls per period."""
+
+from __future__ import annotations
+
+from ._decorator import rate_limit
+from ._errors import RateLimitExceeded
+from ._limiter import RateLimiter
+
+__version__ = "0.1.0"
+
+__all__ = ["RateLimitExceeded", "RateLimiter", "rate_limit"]

taplimit/_decorator.py

@@ -0,0 +1,44 @@
+"""The ``rate_limit`` decorator: the small, obvious entry point."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from functools import wraps
+from typing import ParamSpec, TypeVar
+
+from ._limiter import RateLimiter
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def rate_limit(
+    calls: int,
+    period: float,
+    *,
+    on_limit: str = "block",
+    clock: Callable[[], float] = time.monotonic,
+    sleep: Callable[[float], None] = time.sleep,
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Limit the decorated function to ``calls`` invocations per ``period`` seconds.
+
+    With ``on_limit="block"`` (the default) a call over the limit waits until a slot
+    frees; with ``on_limit="raise"`` it raises RateLimitExceeded instead. All calls
+    to the decorated function share one sliding window. Inject ``clock`` and ``sleep``
+    to drive it from tests without real time passing.
+    """
+    if on_limit not in ("block", "raise"):
+        raise ValueError('on_limit must be "block" or "raise"')
+    blocking = on_limit == "block"
+    limiter = RateLimiter(calls, period, clock=clock, sleep=sleep)
+
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        @wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            limiter.acquire(blocking=blocking)
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

taplimit/_errors.py

@@ -0,0 +1,15 @@
+"""The error raised when a call would exceed the configured rate."""
+
+from __future__ import annotations
+
+
+class RateLimitExceeded(Exception):
+    """Raised when a call would exceed the rate and blocking is turned off.
+
+    The ``retry_after`` attribute holds the seconds until the next slot frees,
+    so a caller can decide how long to wait before trying again.
+    """
+
+    def __init__(self, retry_after: float) -> None:
+        self.retry_after = retry_after
+        super().__init__(f"rate limit exceeded, retry after {retry_after:.3f}s")

taplimit/_limiter.py

@@ -0,0 +1,103 @@
+"""A thread-safe, in-process, sliding-window rate limiter."""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections import deque
+from collections.abc import Callable
+from functools import wraps
+from types import TracebackType
+from typing import ParamSpec, TypeVar
+
+from ._errors import RateLimitExceeded
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+class RateLimiter:
+    """Allow at most ``calls`` acquisitions per ``period`` seconds.
+
+    The window slides: a slot frees exactly ``period`` seconds after the call that
+    took it, not on a shared clock boundary, so a burst never carries over. The
+    limiter is safe to share across threads and across functions, which lets several
+    callables draw on a single budget.
+
+    Inject ``clock`` (returns seconds) and ``sleep`` (waits seconds) to drive the
+    limiter from tests without real time passing.
+    """
+
+    def __init__(
+        self,
+        calls: int,
+        period: float,
+        *,
+        clock: Callable[[], float] = time.monotonic,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        if calls < 1:
+            raise ValueError("calls must be at least 1")
+        if period <= 0:
+            raise ValueError("period must be greater than 0")
+        self._calls = calls
+        self._period = period
+        self._clock = clock
+        self._sleep = sleep
+        self._lock = threading.Lock()
+        self._hits: deque[float] = deque()
+
+    def _purge(self, now: float) -> None:
+        horizon = now - self._period
+        hits = self._hits
+        while hits and hits[0] <= horizon:
+            hits.popleft()
+
+    def try_acquire(self) -> bool:
+        """Take a slot without waiting. Return True if one was free, else False."""
+        with self._lock:
+            now = self._clock()
+            self._purge(now)
+            if len(self._hits) < self._calls:
+                self._hits.append(now)
+                return True
+            return False
+
+    def acquire(self, *, blocking: bool = True) -> None:
+        """Take a slot, waiting for one when ``blocking`` is True.
+
+        When ``blocking`` is False and every slot is taken, raise RateLimitExceeded
+        carrying the seconds until the next slot opens. A rejected call never
+        consumes a slot.
+        """
+        while True:
+            with self._lock:
+                now = self._clock()
+                self._purge(now)
+                if len(self._hits) < self._calls:
+                    self._hits.append(now)
+                    return
+                wait = self._hits[0] + self._period - now
+            if not blocking:
+                raise RateLimitExceeded(wait)
+            self._sleep(wait if wait > 0 else 0.0)
+
+    def __enter__(self) -> RateLimiter:
+        self.acquire()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        return None
+
+    def __call__(self, func: Callable[P, R]) -> Callable[P, R]:
+        @wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            self.acquire()
+            return func(*args, **kwargs)
+
+        return wrapper

taplimit-0.1.0.dist-info/METADATA

@@ -0,0 +1,141 @@
+Metadata-Version: 2.5
+Name: taplimit
+Version: 0.1.0
+Summary: Small, typed, thread-safe in-process rate-limit decorator: N calls per period, block or raise
+Project-URL: Homepage, https://lianes8studio.com
+Project-URL: Repository, https://github.com/JaviLianes8/taplimit
+Project-URL: Issues, https://github.com/JaviLianes8/taplimit/issues
+Project-URL: Changelog, https://github.com/JaviLianes8/taplimit/blob/main/CHANGELOG.md
+Project-URL: LinkedIn, https://www.linkedin.com/in/jlianes/
+Project-URL: Funding, https://buymeacoffee.com/jlianesglrs
+Author-email: Javier Lianes <javier@lianes8studio.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: decorator,rate-limit,ratelimit,sliding-window,thread-safe,throttle
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# taplimit
+
+Small, typed, thread-safe in-process rate-limit decorator: N calls per period, block or raise.
+
+Zero dependencies, one obvious decorator, and a reusable limiter object when you need to
+share a budget. The clock and sleep are injectable, so tests never wait on real time.
+
+## Install
+
+```
+pip install taplimit
+```
+
+## Usage
+
+Cap a function at N calls per period. By default a call over the limit blocks until a
+slot frees:
+
+```python
+from taplimit import rate_limit
+
+@rate_limit(calls=15, period=60)
+def call_api() -> None:
+    ...
+```
+
+Prefer to fail fast instead of waiting? Ask it to raise:
+
+```python
+from taplimit import rate_limit, RateLimitExceeded
+
+@rate_limit(calls=15, period=60, on_limit="raise")
+def call_api() -> None:
+    ...
+
+try:
+    call_api()
+except RateLimitExceeded as exc:
+    print(f"slow down, retry in {exc.retry_after:.1f}s")
+```
+
+Share one budget across several functions, or control slots by hand, with the limiter
+object. It is a decorator, a context manager, and exposes `acquire` / `try_acquire`:
+
+```python
+from taplimit import RateLimiter
+
+limiter = RateLimiter(calls=100, period=60)
+
+@limiter
+def read() -> None: ...
+
+@limiter
+def write() -> None: ...  # read and write draw on the same 100-per-minute budget
+
+with limiter:            # guard a block of code
+    do_work()
+
+if limiter.try_acquire():  # never blocks; returns False when full
+    do_work()
+```
+
+### Testing without real time
+
+`clock` (returns seconds) and `sleep` (waits seconds) are injectable, so a limiter runs
+instantly under a fake clock:
+
+```python
+now = [0.0]
+slept: list[float] = []
+
+limiter = RateLimiter(
+    calls=1, period=10,
+    clock=lambda: now[0],
+    sleep=lambda s: (slept.append(s), now.__setitem__(0, now[0] + s)),
+)
+```
+
+## How it limits
+
+taplimit uses a **sliding window**: it keeps the timestamps of recent calls and a slot
+frees exactly `period` seconds after the call that took it. A burst never carries over a
+fixed boundary the way a reset-every-minute counter does, so the rate you ask for is the
+rate you get. All state is guarded by a lock, so one decorator or limiter is safe to share
+across threads.
+
+## Why
+
+The simple niche of "let this function run at most N times per period, in one process,
+synchronously" is oddly unserved:
+
+- [`ratelimit`](https://pypi.org/project/ratelimit/) popularised the `@limits(calls, period)`
+  shape and is still downloaded millions of times a month, but it has been **abandoned since
+  2018** (last release 2.2.1). It also uses a fixed window and its threading story is thin.
+- [`pyrate-limiter`](https://pypi.org/project/pyrate-limiter/) and
+  [`limits`](https://pypi.org/project/limits/) are maintained and capable, but they are
+  **backend-oriented and heavy**: buckets, optional SQLite / Redis stores, async machinery.
+  Overkill when all you want is a decorator on one function.
+- [`limiter`](https://pypi.org/project/limiter/) is a token-bucket library with a different
+  `rate` / `capacity` API, not the plain calls-per-period shape.
+
+taplimit is the small, modern, typed take: one decorator, a sliding window, thread-safe,
+no dependencies, and a clock you can fake in tests. Reach for it when a single process needs
+to stay under a rate and a full rate-limiting backend would be too much.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

taplimit-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+taplimit/__init__.py,sha256=nsOeDJxTsbZ1PU5TiVFhiLG2t4PNkfQiHHXgTG5XQi0,315
+taplimit/_decorator.py,sha256=tjDTtAnMqFEuxnixm1SY13eBVygksJ4xfv44zAHeqkM,1417
+taplimit/_errors.py,sha256=cVbmGNbJf17FpkV5J4zj7xbpBJ7o6JtnDDfJNBh92MA,545
+taplimit/_limiter.py,sha256=cWGRz3E7Ip07bICPz42_TX4480Cepy9H6L2zw6WXYl0,3229
+taplimit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+taplimit-0.1.0.dist-info/METADATA,sha256=X1nSHRmsSb7QwZqwSbik5stcD7dbwqf0MLKWPe430Ks,4606
+taplimit-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+taplimit-0.1.0.dist-info/licenses/LICENSE,sha256=wirD5nCA2aQa5UusK_1YHLBogI3CGcw23xAnulp3L_U,1091
+taplimit-0.1.0.dist-info/RECORD,,

taplimit-0.1.0.dist-info/WHEEL

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

taplimit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Lianes
+
+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.