throttlebounce 0.1.0__tar.gz

throttlebounce-0.1.0/.gitattributes

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

throttlebounce-0.1.0/.github/FUNDING.yml

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

throttlebounce-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/

throttlebounce-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# 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: `debounce` and `throttle` decorators, thread-safe, with an
+  injectable clock and timer so tests never wait on real time.

throttlebounce-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/throttlebounce/__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.

throttlebounce-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.

throttlebounce-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.5
+Name: throttlebounce
+Version: 0.1.0
+Summary: Small, typed, zero-dependency sync debounce and throttle decorators with an injectable clock
+Project-URL: Homepage, https://lianes8studio.com
+Project-URL: Repository, https://github.com/JaviLianes8/throttlebounce
+Project-URL: Issues, https://github.com/JaviLianes8/throttlebounce/issues
+Project-URL: Changelog, https://github.com/JaviLianes8/throttlebounce/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: debounce,decorator,rate-limit,throttle,timing,typed
+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
+
+# throttlebounce
+
+Small, typed, zero-dependency sync debounce and throttle decorators with an injectable clock.
+
+## Install
+
+```
+pip install throttlebounce
+```
+
+## Usage
+
+```python
+from throttlebounce import debounce, throttle
+
+
+@debounce(0.3)
+def save(text: str) -> None:
+    write_to_disk(text)
+
+
+# Called on every keystroke, it writes once, 0.3s after typing stops.
+save("h")
+save("he")
+save("hello")        # only this one reaches disk
+
+
+@throttle(1.0)
+def ping() -> None:
+    send_heartbeat()
+
+
+# Called in a tight loop, it fires at most once per second.
+while running:
+    ping()
+```
+
+`debounce` collapses a burst of calls into a single run that happens once the
+calls go quiet (trailing edge), with the last call's arguments. The debounced
+callable returns `None`; the real run happens later on a background timer. It
+exposes `flush()` to run the pending call now and return its result, `cancel()`
+to drop it, and a `pending` flag.
+
+`throttle` runs the function at most once per interval (leading edge): the first
+call runs, and calls inside the interval are skipped and return the last result.
+`reset()` clears the window.
+
+Both decorators are thread-safe. Both take an injectable dependency so tests run
+without real waits: `throttle(interval, clock=...)` and
+`debounce(wait, timer_factory=...)`.
+
+```python
+class FakeClock:
+    def __init__(self) -> None:
+        self.now = 0.0
+
+    def __call__(self) -> float:
+        return self.now
+
+
+clock = FakeClock()
+
+
+@throttle(1.0, clock=clock)
+def tick() -> int:
+    return 1
+
+
+assert tick() == 1       # first call runs
+clock.now = 0.5
+assert tick() == 1       # skipped, returns the last result, no real sleep
+```
+
+## Why
+
+Python's standard library has no debounce or throttle, the timing helpers that
+JavaScript developers reach for constantly. The packages that exist fall short:
+
+- [`throttle`](https://pypi.org/project/throttle/) has not been released since
+  2020 and is effectively abandoned.
+- [`throttler`](https://pypi.org/project/throttler/) is an `asyncio` rate limiter,
+  not a sync decorator, and does not debounce.
+- [`call-throttle`](https://pypi.org/project/call-throttle/) throttles but has no
+  debounce.
+- [`python-debouncer`](https://pypi.org/project/python-debouncer/) debounces but
+  pulls in a runtime dependency and has not been touched since 2024.
+
+None of them offer a clean, maintained, typed, zero-dependency pair of sync
+`debounce` and `throttle` decorators that are thread-safe and testable without
+real time. That is the gap this fills. Reach for it in desktop apps, CLIs,
+background workers and GUIs: anywhere a function is triggered more often than you
+want it to run.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

throttlebounce-0.1.0/README.md

@@ -0,0 +1,102 @@
+# throttlebounce
+
+Small, typed, zero-dependency sync debounce and throttle decorators with an injectable clock.
+
+## Install
+
+```
+pip install throttlebounce
+```
+
+## Usage
+
+```python
+from throttlebounce import debounce, throttle
+
+
+@debounce(0.3)
+def save(text: str) -> None:
+    write_to_disk(text)
+
+
+# Called on every keystroke, it writes once, 0.3s after typing stops.
+save("h")
+save("he")
+save("hello")        # only this one reaches disk
+
+
+@throttle(1.0)
+def ping() -> None:
+    send_heartbeat()
+
+
+# Called in a tight loop, it fires at most once per second.
+while running:
+    ping()
+```
+
+`debounce` collapses a burst of calls into a single run that happens once the
+calls go quiet (trailing edge), with the last call's arguments. The debounced
+callable returns `None`; the real run happens later on a background timer. It
+exposes `flush()` to run the pending call now and return its result, `cancel()`
+to drop it, and a `pending` flag.
+
+`throttle` runs the function at most once per interval (leading edge): the first
+call runs, and calls inside the interval are skipped and return the last result.
+`reset()` clears the window.
+
+Both decorators are thread-safe. Both take an injectable dependency so tests run
+without real waits: `throttle(interval, clock=...)` and
+`debounce(wait, timer_factory=...)`.
+
+```python
+class FakeClock:
+    def __init__(self) -> None:
+        self.now = 0.0
+
+    def __call__(self) -> float:
+        return self.now
+
+
+clock = FakeClock()
+
+
+@throttle(1.0, clock=clock)
+def tick() -> int:
+    return 1
+
+
+assert tick() == 1       # first call runs
+clock.now = 0.5
+assert tick() == 1       # skipped, returns the last result, no real sleep
+```
+
+## Why
+
+Python's standard library has no debounce or throttle, the timing helpers that
+JavaScript developers reach for constantly. The packages that exist fall short:
+
+- [`throttle`](https://pypi.org/project/throttle/) has not been released since
+  2020 and is effectively abandoned.
+- [`throttler`](https://pypi.org/project/throttler/) is an `asyncio` rate limiter,
+  not a sync decorator, and does not debounce.
+- [`call-throttle`](https://pypi.org/project/call-throttle/) throttles but has no
+  debounce.
+- [`python-debouncer`](https://pypi.org/project/python-debouncer/) debounces but
+  pulls in a runtime dependency and has not been touched since 2024.
+
+None of them offer a clean, maintained, typed, zero-dependency pair of sync
+`debounce` and `throttle` decorators that are thread-safe and testable without
+real time. That is the gap this fills. Reach for it in desktop apps, CLIs,
+background workers and GUIs: anywhere a function is triggered more often than you
+want it to run.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

throttlebounce-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "throttlebounce"
+version = "0.1.0"
+description = "Small, typed, zero-dependency sync debounce and throttle decorators with an injectable clock"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Javier Lianes", email = "javier@lianes8studio.com" }]
+keywords = ["debounce", "throttle", "decorator", "rate-limit", "timing", "typed"]
+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/throttlebounce"
+Issues = "https://github.com/JaviLianes8/throttlebounce/issues"
+Changelog = "https://github.com/JaviLianes8/throttlebounce/blob/main/CHANGELOG.md"
+LinkedIn = "https://www.linkedin.com/in/jlianes/"
+Funding = "https://buymeacoffee.com/jlianesglrs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/throttlebounce"]
+
+[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"

throttlebounce-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]

throttlebounce-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

throttlebounce-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/throttlebounce/json" | Out-Null
+    throw "The name 'throttlebounce' 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 }

throttlebounce-0.1.0/src/throttlebounce/__init__.py

@@ -0,0 +1,17 @@
+"""Small, typed, zero-dependency sync debounce and throttle decorators."""
+
+from __future__ import annotations
+
+from ._debounce import Debounced, TimerFactory, debounce
+from ._throttle import Clock, Throttled, throttle
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Clock",
+    "Debounced",
+    "Throttled",
+    "TimerFactory",
+    "debounce",
+    "throttle",
+]

throttlebounce-0.1.0/src/throttlebounce/_debounce.py

@@ -0,0 +1,111 @@
+"""Trailing-edge debounce: run a function only after its calls go quiet."""
+
+from __future__ import annotations
+
+import functools
+import threading
+from collections.abc import Callable
+from typing import Generic, ParamSpec, Protocol, TypeVar
+
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+
+
+class _Timer(Protocol):
+    """The slice of threading.Timer the debouncer depends on."""
+
+    def start(self) -> None: ...
+
+    def cancel(self) -> None: ...
+
+
+TimerFactory = Callable[[float, Callable[[], None]], _Timer]
+"""Builds a one-shot timer that runs an action after a delay in seconds.
+
+Inject a fake factory in tests so nothing waits on real time.
+"""
+
+
+def _default_timer_factory(delay: float, action: Callable[[], None]) -> _Timer:
+    # Daemon so a still-pending call never keeps the interpreter alive on exit.
+    timer = threading.Timer(delay, action)
+    timer.daemon = True
+    return timer
+
+
+class Debounced(Generic[_P, _R]):
+    """A callable that delays ``func`` until ``wait`` seconds after the last call."""
+
+    def __init__(self, func: Callable[_P, _R], wait: float, timer_factory: TimerFactory) -> None:
+        self._func = func
+        self._wait = wait
+        self._new_timer = timer_factory
+        self._lock = threading.Lock()
+        self._timer: _Timer | None = None
+        self._pending: functools.partial[_R] | None = None
+        self._result: _R | None = None
+        functools.update_wrapper(self, func)
+
+    def __call__(self, *args: _P.args, **kwargs: _P.kwargs) -> None:
+        call = functools.partial(self._func, *args, **kwargs)
+        with self._lock:
+            if self._timer is not None:
+                self._timer.cancel()
+            self._pending = call
+            timer = self._new_timer(self._wait, self._fire)
+            self._timer = timer
+        timer.start()
+
+    def _fire(self) -> None:
+        with self._lock:
+            call = self._pending
+            self._pending = None
+            self._timer = None
+        if call is not None:
+            self._result = call()
+
+    def cancel(self) -> None:
+        """Drop any pending call so it will never run."""
+        with self._lock:
+            if self._timer is not None:
+                self._timer.cancel()
+                self._timer = None
+            self._pending = None
+
+    def flush(self) -> _R | None:
+        """Run any pending call right now and return its result, else None."""
+        with self._lock:
+            if self._timer is not None:
+                self._timer.cancel()
+                self._timer = None
+            call = self._pending
+            self._pending = None
+        if call is None:
+            return None
+        self._result = call()
+        return self._result
+
+    @property
+    def pending(self) -> bool:
+        """Whether a call is waiting to run."""
+        with self._lock:
+            return self._pending is not None
+
+
+def debounce(
+    wait: float, *, timer_factory: TimerFactory = _default_timer_factory
+) -> Callable[[Callable[_P, _R]], Debounced[_P, _R]]:
+    """Return a decorator that debounces a function by ``wait`` seconds.
+
+    Rapid calls collapse into one: the wrapped function runs ``wait`` seconds
+    after the final call, with that call's arguments. The debounced callable
+    returns None (the real run happens later); use ``flush`` to force it now,
+    ``cancel`` to drop it, and ``pending`` to check for a waiting call.
+    """
+    if wait < 0:
+        raise ValueError("wait must be non-negative")
+
+    def decorator(func: Callable[_P, _R]) -> Debounced[_P, _R]:
+        return Debounced(func, wait, timer_factory)
+
+    return decorator

throttlebounce-0.1.0/src/throttlebounce/_throttle.py

@@ -0,0 +1,64 @@
+"""Leading-edge throttle: run a function at most once per interval."""
+
+from __future__ import annotations
+
+import functools
+import threading
+import time
+from collections.abc import Callable
+from typing import Generic, ParamSpec, TypeVar
+
+_P = ParamSpec("_P")
+_R = TypeVar("_R")
+
+Clock = Callable[[], float]
+"""Returns a monotonically increasing time in seconds.
+
+Inject a fake clock in tests so nothing waits on real time.
+"""
+
+
+class Throttled(Generic[_P, _R]):
+    """A callable that runs ``func`` at most once per ``interval`` seconds."""
+
+    def __init__(self, func: Callable[_P, _R], interval: float, clock: Clock) -> None:
+        self._func = func
+        self._interval = interval
+        self._clock = clock
+        self._lock = threading.Lock()
+        self._last: float | None = None
+        self._result: _R | None = None
+        functools.update_wrapper(self, func)
+
+    def __call__(self, *args: _P.args, **kwargs: _P.kwargs) -> _R | None:
+        with self._lock:
+            now = self._clock()
+            if self._last is not None and now - self._last < self._interval:
+                return self._result
+            self._last = now
+        result = self._func(*args, **kwargs)
+        with self._lock:
+            self._result = result
+        return result
+
+    def reset(self) -> None:
+        """Forget the last run so the next call fires immediately."""
+        with self._lock:
+            self._last = None
+
+
+def throttle(
+    interval: float, *, clock: Clock = time.monotonic
+) -> Callable[[Callable[_P, _R]], Throttled[_P, _R]]:
+    """Return a decorator that throttles a function to once per ``interval`` seconds.
+
+    The first call runs immediately; any call within ``interval`` of the last
+    run is skipped and returns the last result (None before the first run).
+    """
+    if interval < 0:
+        raise ValueError("interval must be non-negative")
+
+    def decorator(func: Callable[_P, _R]) -> Throttled[_P, _R]:
+        return Throttled(func, interval, clock)
+
+    return decorator

throttlebounce-0.1.0/tests/test_contract.py

@@ -0,0 +1,33 @@
+import importlib.resources
+
+import throttlebounce
+
+# 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] = [
+    "Clock",
+    "Debounced",
+    "Throttled",
+    "TimerFactory",
+    "debounce",
+    "throttle",
+]
+
+
+def test_all_lists_exactly_the_public_api() -> None:
+    assert sorted(throttlebounce.__all__) == sorted(PUBLIC_API)
+
+
+def test_every_exported_name_resolves() -> None:
+    for name in throttlebounce.__all__:
+        assert hasattr(throttlebounce, name)
+
+
+def test_version_is_a_three_part_string() -> None:
+    parts = throttlebounce.__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("throttlebounce").joinpath("py.typed").is_file()

throttlebounce-0.1.0/tests/test_debounce.py

@@ -0,0 +1,123 @@
+"""Behaviour tests for the debounce decorator, with a fake timer (no real waits)."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import pytest
+
+from throttlebounce import debounce
+
+
+class FakeTimer:
+    """A one-shot timer that fires only when the test tells it to."""
+
+    def __init__(self, delay: float, action: Callable[[], None]) -> None:
+        self.delay = delay
+        self.action = action
+        self.cancelled = False
+
+    def start(self) -> None:
+        pass
+
+    def cancel(self) -> None:
+        self.cancelled = True
+
+    def fire(self) -> None:
+        if not self.cancelled:
+            self.action()
+
+
+class TimerSpy:
+    """Records every timer it builds so a test can fire the live one."""
+
+    def __init__(self) -> None:
+        self.timers: list[FakeTimer] = []
+
+    def __call__(self, delay: float, action: Callable[[], None]) -> FakeTimer:
+        timer = FakeTimer(delay, action)
+        self.timers.append(timer)
+        return timer
+
+
+def test_rapid_calls_collapse_into_one_run_with_the_last_arguments() -> None:
+    spy = TimerSpy()
+    seen: list[int] = []
+
+    @debounce(0.5, timer_factory=spy)
+    def record(value: int) -> None:
+        seen.append(value)
+
+    record(1)
+    record(2)
+    record(3)
+    assert seen == []
+    spy.timers[-1].fire()
+    assert seen == [3]
+
+
+def test_every_earlier_timer_is_cancelled() -> None:
+    spy = TimerSpy()
+
+    @debounce(0.5, timer_factory=spy)
+    def noop() -> None:
+        pass
+
+    noop()
+    noop()
+    noop()
+    assert [t.cancelled for t in spy.timers] == [True, True, False]
+
+
+def test_the_delay_is_passed_to_the_timer() -> None:
+    spy = TimerSpy()
+
+    @debounce(0.25, timer_factory=spy)
+    def noop() -> None:
+        pass
+
+    noop()
+    assert spy.timers[0].delay == 0.25
+
+
+def test_cancel_drops_the_pending_call() -> None:
+    spy = TimerSpy()
+    seen: list[int] = []
+
+    @debounce(0.5, timer_factory=spy)
+    def record(value: int) -> None:
+        seen.append(value)
+
+    record(1)
+    record.cancel()
+    spy.timers[-1].fire()
+    assert seen == []
+    assert record.pending is False
+
+
+def test_flush_runs_the_pending_call_now_and_returns_its_result() -> None:
+    spy = TimerSpy()
+
+    @debounce(0.5, timer_factory=spy)
+    def double(value: int) -> int:
+        return value * 2
+
+    double(21)
+    assert double.pending is True
+    assert double.flush() == 42
+    assert double.pending is False
+
+
+def test_flush_with_nothing_pending_returns_none() -> None:
+    spy = TimerSpy()
+
+    @debounce(0.5, timer_factory=spy)
+    def identity(value: int) -> int:
+        return value
+
+    assert identity.flush() is None
+
+
+def test_a_negative_wait_is_rejected() -> None:
+    with pytest.raises(ValueError):
+        debounce(-1.0)

throttlebounce-0.1.0/tests/test_throttle.py

@@ -0,0 +1,94 @@
+"""Behaviour tests for the throttle decorator, with a fake clock (no real waits)."""
+
+from __future__ import annotations
+
+import pytest
+
+from throttlebounce import throttle
+
+
+class FakeClock:
+    """A clock the test advances by hand."""
+
+    def __init__(self) -> None:
+        self.now = 0.0
+
+    def __call__(self) -> float:
+        return self.now
+
+    def advance(self, seconds: float) -> None:
+        self.now += seconds
+
+
+def test_the_first_call_runs_immediately() -> None:
+    clock = FakeClock()
+    calls: list[int] = []
+
+    @throttle(1.0, clock=clock)
+    def record(value: int) -> int:
+        calls.append(value)
+        return value
+
+    assert record(1) == 1
+    assert calls == [1]
+
+
+def test_calls_within_the_interval_are_skipped() -> None:
+    clock = FakeClock()
+    calls: list[int] = []
+
+    @throttle(1.0, clock=clock)
+    def record(value: int) -> None:
+        calls.append(value)
+
+    record(1)
+    clock.advance(0.4)
+    record(2)
+    clock.advance(0.4)
+    record(3)
+    assert calls == [1]
+
+
+def test_a_call_after_the_interval_runs_again() -> None:
+    clock = FakeClock()
+    calls: list[int] = []
+
+    @throttle(1.0, clock=clock)
+    def record(value: int) -> None:
+        calls.append(value)
+
+    record(1)
+    clock.advance(1.0)
+    record(2)
+    assert calls == [1, 2]
+
+
+def test_a_skipped_call_returns_the_last_result() -> None:
+    clock = FakeClock()
+
+    @throttle(1.0, clock=clock)
+    def double(value: int) -> int:
+        return value * 2
+
+    assert double(10) == 20
+    clock.advance(0.5)
+    assert double(999) == 20
+
+
+def test_reset_lets_the_next_call_fire_immediately() -> None:
+    clock = FakeClock()
+    calls: list[int] = []
+
+    @throttle(1.0, clock=clock)
+    def record(value: int) -> None:
+        calls.append(value)
+
+    record(1)
+    record.reset()
+    record(2)
+    assert calls == [1, 2]
+
+
+def test_a_negative_interval_is_rejected() -> None:
+    with pytest.raises(ValueError):
+        throttle(-1.0)