throttlebounce 0.1.0__py3-none-any.whl

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/_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/_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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+throttlebounce/__init__.py,sha256=I5KKJ9Axp5CnPUM11AxokJ9w5ZteNedubNckiPk21OE,356
+throttlebounce/_debounce.py,sha256=YMfa1pWV7-wFG8pHjwCoQ8pwgA79_Jae8ap9yfv7HZU,3610
+throttlebounce/_throttle.py,sha256=NuMPxLnyF3B5HUbIrlo4dd6o4bOWz2WZ9t9Pq2dshNE,2023
+throttlebounce/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+throttlebounce-0.1.0.dist-info/METADATA,sha256=Oc5sUrf5Zj1svVJye0ukXh7KEB65CIa9imUh3UjeuZU,4000
+throttlebounce-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+throttlebounce-0.1.0.dist-info/licenses/LICENSE,sha256=wirD5nCA2aQa5UusK_1YHLBogI3CGcw23xAnulp3L_U,1091
+throttlebounce-0.1.0.dist-info/RECORD,,

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

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