taplimit 0.1.0__tar.gz

taplimit-0.1.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

taplimit-0.1.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+buy_me_a_coffee: jlianesglrs

taplimit-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/

taplimit-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0]
+
+- First release: `rate_limit` decorator, `RateLimiter` object, and `RateLimitExceeded`.
+- Sliding-window algorithm, thread-safe, zero dependencies.
+- Block-or-raise behaviour, with injectable clock and sleep for tests.

taplimit-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+Thanks for taking the time. This project keeps a small, predictable shape.
+
+## Setup
+
+```
+pip install -r requirements-dev.txt
+```
+
+## Before you open a pull request
+
+- Keep public API in `src/ratekeeper/__init__.py`; internals live in `_`-prefixed modules.
+- Add a test for the behaviour you change. Tests inject time, disk and network; they
+  never touch the real thing.
+- Run `scripts/check.ps1` (format, lint, types, tests) and make sure it passes.
+- One logical change per commit, imperative subject line.
+
+Open an issue first if the change is large or shifts the public API.

taplimit-0.1.0/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.

taplimit-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,114 @@
+# 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/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "taplimit"
+version = "0.1.0"
+description = "Small, typed, thread-safe in-process rate-limit decorator: N calls per period, block or raise"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Javier Lianes", email = "javier@lianes8studio.com" }]
+keywords = ["rate-limit", "ratelimit", "throttle", "decorator", "thread-safe", "sliding-window"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["ruff", "mypy", "pytest", "build", "twine"]
+
+[project.urls]
+Homepage = "https://lianes8studio.com"
+Repository = "https://github.com/JaviLianes8/taplimit"
+Issues = "https://github.com/JaviLianes8/taplimit/issues"
+Changelog = "https://github.com/JaviLianes8/taplimit/blob/main/CHANGELOG.md"
+LinkedIn = "https://www.linkedin.com/in/jlianes/"
+Funding = "https://buymeacoffee.com/jlianesglrs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/taplimit"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-q"

taplimit-0.1.0/requirements-dev.txt

@@ -0,0 +1,3 @@
+# Development dependencies: the package in editable mode plus its dev extras
+# (ruff, mypy, pytest, build, twine). Install with:  pip install -r requirements-dev.txt
+-e .[dev]

taplimit-0.1.0/scripts/check.ps1

@@ -0,0 +1,7 @@
+# Local quality gate. Run before every commit. No CI runs in the cloud.
+$ErrorActionPreference = "Stop"
+
+ruff format --check src tests
+ruff check src tests
+mypy src tests
+pytest

taplimit-0.1.0/scripts/release.ps1

@@ -0,0 +1,26 @@
+# Build and upload to PyPI. Run scripts/check.ps1 first.
+# The name must not already exist on PyPI; the token is read from a secret store, never git.
+$ErrorActionPreference = "Stop"
+
+try {
+    Invoke-WebRequest -UseBasicParsing "https://pypi.org/pypi/taplimit/json" | Out-Null
+    throw "The name 'taplimit' already exists on PyPI. Choose another before publishing."
+} catch [System.Net.WebException], [Microsoft.PowerShell.Commands.HttpResponseException] {
+    if ($_.Exception.Response.StatusCode.value__ -ne 404) { throw }
+}
+
+$token = $env:PYPI_TOKEN
+if (-not $token -and (Test-Path "C:\secrets\pypi-token.txt")) {
+    $token = (Get-Content "C:\secrets\pypi-token.txt" -Raw).Trim()
+}
+if (-not $token) {
+    throw "No PyPI token. Set `$env:PYPI_TOKEN or save it to C:\secrets\pypi-token.txt (never commit it)."
+}
+
+Remove-Item -Recurse -Force dist -ErrorAction SilentlyContinue
+python -m build
+python -m twine check dist/*
+
+$env:TWINE_USERNAME = "__token__"
+$env:TWINE_PASSWORD = $token
+try { python -m twine upload dist/* } finally { Remove-Item Env:\TWINE_PASSWORD -ErrorAction SilentlyContinue }

taplimit-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/tests/_fakeclock.py

@@ -0,0 +1,21 @@
+"""A deterministic clock and sleep pair so tests never wait on real time."""
+
+from __future__ import annotations
+
+
+class FakeClock:
+    """A fake monotonic clock whose ``sleep`` simply advances the clock."""
+
+    def __init__(self, start: float = 0.0) -> None:
+        self.now = start
+        self.slept: list[float] = []
+
+    def time(self) -> float:
+        return self.now
+
+    def sleep(self, seconds: float) -> None:
+        self.slept.append(seconds)
+        self.now += seconds
+
+    def advance(self, seconds: float) -> None:
+        self.now += seconds

taplimit-0.1.0/tests/test_contract.py

@@ -0,0 +1,26 @@
+import importlib.resources
+
+import taplimit
+
+# The public API. Add every exported name here as the library grows; this list is the
+# contract and the test below fails if the module and this list disagree.
+PUBLIC_API: list[str] = ["RateLimitExceeded", "RateLimiter", "rate_limit"]
+
+
+def test_all_lists_exactly_the_public_api() -> None:
+    assert sorted(taplimit.__all__) == sorted(PUBLIC_API)
+
+
+def test_every_exported_name_resolves() -> None:
+    for name in taplimit.__all__:
+        assert hasattr(taplimit, name)
+
+
+def test_version_is_a_three_part_string() -> None:
+    parts = taplimit.__version__.split(".")
+    assert len(parts) == 3
+    assert all(part.isdigit() for part in parts)
+
+
+def test_the_package_ships_type_information() -> None:
+    assert importlib.resources.files("taplimit").joinpath("py.typed").is_file()

taplimit-0.1.0/tests/test_decorator.py

@@ -0,0 +1,59 @@
+"""Behaviour tests for the rate_limit decorator."""
+
+from __future__ import annotations
+
+import pytest
+from _fakeclock import FakeClock
+
+from taplimit import RateLimitExceeded, rate_limit
+
+
+def test_blocks_by_default_until_a_slot_frees() -> None:
+    clock = FakeClock()
+
+    @rate_limit(2, 10, clock=clock.time, sleep=clock.sleep)
+    def work() -> str:
+        return "ok"
+
+    assert work() == "ok"
+    assert work() == "ok"
+    assert work() == "ok"  # third call waits
+    assert clock.slept == [10.0]
+
+
+def test_raise_mode_raises_instead_of_waiting() -> None:
+    clock = FakeClock()
+
+    @rate_limit(1, 10, on_limit="raise", clock=clock.time, sleep=clock.sleep)
+    def work() -> str:
+        return "ok"
+
+    assert work() == "ok"
+    with pytest.raises(RateLimitExceeded):
+        work()
+    assert clock.slept == []
+
+
+def test_preserves_arguments_and_return_value() -> None:
+    clock = FakeClock()
+
+    @rate_limit(10, 10, clock=clock.time, sleep=clock.sleep)
+    def add(a: int, b: int = 0) -> int:
+        return a + b
+
+    assert add(2, b=3) == 5
+
+
+def test_preserves_the_wrapped_name_and_docstring() -> None:
+    @rate_limit(1, 1)
+    def greet() -> str:
+        """Say hello."""
+        return "hi"
+
+    assert greet.__name__ == "greet"
+    assert greet.__doc__ == "Say hello."
+
+
+def test_rejects_an_unknown_on_limit_value() -> None:
+    with pytest.raises(ValueError):
+        rate_limit(1, 10, on_limit="explode")

taplimit-0.1.0/tests/test_limiter.py

@@ -0,0 +1,146 @@
+"""Behaviour tests for the RateLimiter primitive."""
+
+from __future__ import annotations
+
+import threading
+
+import pytest
+from _fakeclock import FakeClock
+
+from taplimit import RateLimiter, RateLimitExceeded
+
+
+def test_allows_up_to_the_limit_without_waiting() -> None:
+    clock = FakeClock()
+    limiter = RateLimiter(3, 60, clock=clock.time, sleep=clock.sleep)
+
+    for _ in range(3):
+        limiter.acquire()
+
+    assert clock.slept == []
+
+
+def test_blocks_until_the_oldest_slot_frees() -> None:
+    clock = FakeClock()
+    limiter = RateLimiter(2, 10, clock=clock.time, sleep=clock.sleep)
+
+    limiter.acquire()  # t=0
+    clock.advance(4)
+    limiter.acquire()  # t=4, window now full
+    limiter.acquire()  # must wait for the t=0 slot to free at t=10
+
+    assert clock.slept == [6.0]
+    assert clock.now == 10.0
+
+
+def test_try_acquire_reports_free_and_full() -> None:
+    clock = FakeClock()
+    limiter = RateLimiter(1, 10, clock=clock.time, sleep=clock.sleep)
+
+    assert limiter.try_acquire() is True
+    assert limiter.try_acquire() is False
+    clock.advance(10)
+    assert limiter.try_acquire() is True
+
+
+def test_try_acquire_does_not_wait() -> None:
+    clock = FakeClock()
+    limiter = RateLimiter(1, 10, clock=clock.time, sleep=clock.sleep)
+
+    limiter.try_acquire()
+    limiter.try_acquire()
+
+    assert clock.slept == []
+
+
+def test_non_blocking_acquire_raises_with_retry_after() -> None:
+    clock = FakeClock()
+    limiter = RateLimiter(1, 10, clock=clock.time, sleep=clock.sleep)
+
+    limiter.acquire()
+    clock.advance(3)
+    with pytest.raises(RateLimitExceeded) as info:
+        limiter.acquire(blocking=False)
+
+    assert info.value.retry_after == pytest.approx(7.0)
+
+
+def test_rejected_call_does_not_consume_a_slot() -> None:
+    clock = FakeClock()
+    limiter = RateLimiter(1, 10, clock=clock.time, sleep=clock.sleep)
+
+    limiter.acquire()
+    with pytest.raises(RateLimitExceeded):
+        limiter.acquire(blocking=False)
+    clock.advance(10)
+
+    assert limiter.try_acquire() is True
+
+
+def test_window_slides_rather_than_resetting() -> None:
+    clock = FakeClock()
+    limiter = RateLimiter(2, 10, clock=clock.time, sleep=clock.sleep)
+
+    limiter.acquire()  # t=0
+    limiter.acquire()  # t=0
+    clock.advance(10)  # the two slots free exactly now
+    assert limiter.try_acquire() is True
+    assert limiter.try_acquire() is True
+
+
+def test_works_as_a_decorator() -> None:
+    clock = FakeClock()
+    limiter = RateLimiter(1, 10, clock=clock.time, sleep=clock.sleep)
+    calls = 0
+
+    @limiter
+    def ping() -> int:
+        nonlocal calls
+        calls += 1
+        return calls
+
+    assert ping() == 1
+    clock.advance(10)
+    assert ping() == 2
+
+
+def test_works_as_a_context_manager() -> None:
+    clock = FakeClock()
+    limiter = RateLimiter(1, 10, clock=clock.time, sleep=clock.sleep)
+
+    with limiter:
+        pass
+    clock.advance(10)
+    with limiter:
+        pass
+
+    assert clock.slept == []
+
+
+def test_rejects_non_positive_configuration() -> None:
+    with pytest.raises(ValueError):
+        RateLimiter(0, 10)
+    with pytest.raises(ValueError):
+        RateLimiter(1, 0)
+
+
+def test_is_thread_safe_under_contention() -> None:
+    clock = FakeClock()
+    # Real sleep of zero keeps the test fast while exercising the lock.
+    limiter = RateLimiter(50, 1000, clock=clock.time)
+    taken = 0
+    lock = threading.Lock()
+
+    def worker() -> None:
+        nonlocal taken
+        if limiter.try_acquire():
+            with lock:
+                taken += 1
+
+    threads = [threading.Thread(target=worker) for _ in range(200)]
+    for thread in threads:
+        thread.start()
+    for thread in threads:
+        thread.join()
+
+    assert taken == 50