staleflight 0.1.0__py3-none-any.whl

staleflight/__init__.py

@@ -0,0 +1,6 @@
+"""staleflight: serve-stale singleflight caching (RFC 5861 for callables)."""
+
+from staleflight.core import SWRCache, Snapshot, swr
+
+__all__ = ["SWRCache", "Snapshot", "swr"]
+__version__ = "0.1.0"

staleflight/core.py

@@ -0,0 +1,187 @@
+"""Serve-stale singleflight caching for expensive zero-argument callables.
+
+This module implements the semantics of RFC 5861 (``stale-while-revalidate``
+and ``stale-if-error``) for plain Python callables:
+
+fresh
+    The cached snapshot is served; no work happens.
+stale
+    Exactly one caller recomputes. Every caller that arrives while the
+    recomputation is in flight is served the previous snapshot immediately
+    instead of waiting (``stale-while-revalidate``).
+refresh failure
+    The previous snapshot keeps being served and keeps aging
+    (``stale-if-error``). The error is recorded and optionally reported.
+empty
+    The very first caller computes; callers that arrive during that first
+    computation receive ``None`` and decide for themselves what "not yet"
+    means in their domain.
+
+The design is intentionally the opposite of a blocking dogpile lock: under
+load, no caller is ever parked behind another caller's slow recomputation.
+That trade -- bounded staleness in exchange for bounded latency -- is the
+right one for readiness gates, dashboards, and feature-flag style lookups,
+and the wrong one when every caller must observe the newest value.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+__all__ = ["SWRCache", "Snapshot", "swr"]
+
+T = TypeVar("T")
+
+Clock = Callable[[], float]
+ErrorCallback = Callable[[BaseException], None]
+
+
+@dataclass(frozen=True, slots=True)
+class Snapshot(Generic[T]):
+    """An immutable value paired with the instant it was computed.
+
+    ``created_at`` is expressed on the cache's clock (monotonic by
+    default), so it is suitable for measuring age, not for display.
+    """
+
+    value: T
+    created_at: float
+
+
+class SWRCache(Generic[T]):
+    """A serve-stale singleflight cache around one zero-argument callable.
+
+    One instance guards one value. Publication is a single reference
+    assignment of an immutable :class:`Snapshot`, so readers in other
+    threads always observe either the previous snapshot or the new one,
+    never a partially built value.
+
+    Thread-safety: safe under CPython's GIL, which every current supported
+    runtime has. A free-threaded (PEP 703) deployment should wrap
+    ``get``/``peek`` in a lock of its own; reference-swap atomicity is
+    implementation behaviour there, not a documented guarantee.
+
+    Args:
+        source: The expensive callable producing the value.
+        ttl: Seconds a snapshot is considered fresh. Must be positive.
+        on_error: Called with the exception when a refresh triggered by
+            :meth:`get` fails. Failures never propagate out of ``get``;
+            they surface here and on :attr:`last_error`.
+        clock: Monotonic time source; injectable for tests.
+    """
+
+    def __init__(
+        self,
+        source: Callable[[], T],
+        *,
+        ttl: float,
+        on_error: ErrorCallback | None = None,
+        clock: Clock = time.monotonic,
+    ) -> None:
+        """See the class docstring for parameter semantics."""
+        if ttl <= 0:
+            raise ValueError(f"ttl must be positive, got {ttl!r}")
+        self._source = source
+        self._ttl = float(ttl)
+        self._on_error = on_error
+        self._clock = clock
+        self._snapshot: Snapshot[T] | None = None
+        self._refresh_lock = threading.Lock()
+        #: The exception from the most recent failed refresh, cleared by the
+        #: next successful one. Advisory: read it for diagnostics, not logic.
+        self.last_error: BaseException | None = None
+
+    @property
+    def ttl(self) -> float:
+        """Seconds a snapshot is served without triggering a refresh."""
+        return self._ttl
+
+    def get(self) -> Snapshot[T] | None:
+        """Return a snapshot, refreshing at most once per staleness.
+
+        Never blocks on another caller's refresh and never raises on a
+        failed refresh; see the module docstring for the full semantics.
+        Returns ``None`` only while the very first computation has not yet
+        completed.
+        """
+        snapshot = self._snapshot
+        if snapshot is not None and self._clock() - snapshot.created_at < self._ttl:
+            return snapshot
+        if self._refresh_lock.acquire(blocking=False):
+            try:
+                return self._refresh_locked()
+            # Broad on purpose: stale-if-error is the contract.
+            except Exception as error:
+                self.last_error = error
+                if self._on_error is not None:
+                    self._on_error(error)
+            finally:
+                self._refresh_lock.release()
+        # Lock was busy (another caller is refreshing) or the refresh
+        # failed: the previous snapshot -- possibly None -- is the answer.
+        return self._snapshot
+
+    def refresh(self) -> Snapshot[T]:
+        """Recompute synchronously and publish, regardless of freshness.
+
+        Unlike :meth:`get`, a failure here propagates: an explicit refresh
+        is a command, not a read. Explicit refreshes serialize on the
+        refresh lock, so a slow older computation can never overwrite a
+        newer snapshot.
+        """
+        with self._refresh_lock:
+            return self._refresh_locked()
+
+    def _refresh_locked(self) -> Snapshot[T]:
+        snapshot = Snapshot(value=self._source(), created_at=self._clock())
+        self._snapshot = snapshot
+        self.last_error = None
+        return snapshot
+
+    def peek(self) -> Snapshot[T] | None:
+        """Return the current snapshot, fresh or stale, without any work."""
+        return self._snapshot
+
+    def age(self) -> float:
+        """Seconds since the current snapshot was computed.
+
+        Returns ``float('inf')`` when nothing has been computed yet, so the
+        result is always comparable against a TTL or staleness budget.
+        """
+        snapshot = self._snapshot
+        if snapshot is None:
+            return float("inf")
+        return self._clock() - snapshot.created_at
+
+    def invalidate(self) -> None:
+        """Drop the snapshot; the next :meth:`get` recomputes from empty."""
+        self._snapshot = None
+
+
+def swr(
+    *,
+    ttl: float,
+    on_error: ErrorCallback | None = None,
+    clock: Clock = time.monotonic,
+) -> Callable[[Callable[[], T]], SWRCache[T]]:
+    """Build an :class:`SWRCache` in decorator position.
+
+    The decorated name is *replaced by the cache instance*, which makes the
+    call-site semantics explicit -- ``config.get()`` returns a
+    :class:`Snapshot`, not a bare value::
+
+        @swr(ttl=5.0)
+        def mesh_health() -> dict[str, bool]:
+            return probe_everything()
+
+        snapshot = mesh_health.get()
+    """
+
+    def wrap(source: Callable[[], T]) -> SWRCache[T]:
+        return SWRCache(source, ttl=ttl, on_error=on_error, clock=clock)
+
+    return wrap

staleflight-0.1.0.dist-info/METADATA

@@ -0,0 +1,90 @@
+Metadata-Version: 2.5
+Name: staleflight
+Version: 0.1.0
+Summary: Serve-stale singleflight caching: RFC 5861 stale-while-revalidate and stale-if-error for plain Python callables.
+Project-URL: Homepage, https://github.com/jaeger123/staleflight
+Project-URL: Repository, https://github.com/jaeger123/staleflight
+Project-URL: Changelog, https://github.com/jaeger123/staleflight/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/jaeger123/staleflight/issues
+Author: Akarsh Sharma
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cache,dogpile,rfc5861,singleflight,stale-if-error,stale-while-revalidate,swr,ttl
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# staleflight
+
+**Serve-stale singleflight caching for Python — RFC 5861's `stale-while-revalidate` and `stale-if-error`, for plain callables instead of HTTP.**
+
+Zero dependencies. Fully typed (PEP 561). Python 3.11+.
+
+```python
+from staleflight import swr
+
+
+@swr(ttl=5.0)
+def mesh_health() -> dict:
+    return probe_all_the_things()  # expensive: network calls, big queries…
+
+
+snapshot = mesh_health.get()  # Snapshot(value=..., created_at=...) or None
+```
+
+## The semantics, precisely
+
+| State | What a caller gets |
+|---|---|
+| **fresh** (age < ttl) | the cached snapshot, ~0 cost |
+| **stale** | exactly **one** caller recomputes; every concurrent caller is served the **previous snapshot immediately** — nobody waits behind the refresh |
+| **refresh fails** | the previous snapshot keeps being served and keeps aging; the error lands on `cache.last_error` and your `on_error` callback |
+| **empty** (first ever call) | the first caller computes; concurrent callers get `None` and decide what "not yet" means for them |
+
+This is the **non-blocking** flavor of stampede protection. Most caching libraries offer the blocking flavor — losers park behind the winner's lock until the new value exists. That is the right choice when every reader must see the newest value, and the wrong one when bounded *latency* matters more than bounded *staleness*: readiness gates, dashboards, feature flags, config lookups. staleflight is for the second family.
+
+## Why not …
+
+*(Survey of 17 caching libraries, 2026. Corrections welcome.)*
+
+- **dogpile.cache** — the one mature library with this exact serve-stale semantic (`get_or_create`). Adopt it if you want regions, backends and invalidation strategies; staleflight is for when you want the 150-line version with no dependencies and stale-if-error built in (dogpile propagates creator failures to the winning caller).
+- **cachetools** — TTL only; its stampede options make concurrent callers *wait*. No stale-serving.
+- **PyPI `singleflight` ports** — deduplicate concurrent calls but block the losers, and cache nothing.
+- **cachier / diskcache / requests-cache** — respectively: immature memory backend; probabilistic *early* refresh that still blocks after full expiry; SWR for HTTP responses only.
+
+## API
+
+```python
+from staleflight import SWRCache, Snapshot, swr
+
+cache = SWRCache(source, ttl=5.0, on_error=log_it, clock=time.monotonic)
+
+cache.get()  # Snapshot | None — refreshes at most singleflight-once, never raises
+cache.peek()  # Snapshot | None — never triggers work
+cache.refresh()  # force recompute now; raises on failure (a command, not a read)
+cache.age()  # seconds since compute; float('inf') when empty
+cache.invalidate()  # drop the snapshot
+cache.last_error  # BaseException | None from the most recent failed get()-refresh
+```
+
+`Snapshot` is a frozen dataclass `(value, created_at)`; `created_at` is on the cache's (monotonic) clock. The `clock` parameter makes every behavior testable without sleeps — see the test suite.
+
+## Thread-safety
+
+Publication is a single reference assignment of an immutable `Snapshot`: readers observe the old snapshot or the new one, never a torn value. Safe under CPython's GIL (every currently supported default build). On free-threaded builds (PEP 703) reference-swap visibility is implementation behavior, not contract — wrap access in your own lock there.
+
+## Non-goals
+
+Keyed/memoizing caches, async, eviction policies, external backends, background refresh threads. One value, one callable, one file. If you need more, you want dogpile.cache.
+
+## License
+
+MIT

staleflight-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+staleflight/__init__.py,sha256=FVg1fVYf1LT_Un0RAwqam-5bzPmmihr_ZzTUHaQPcpk,197
+staleflight/core.py,sha256=pBTY6JrMfr5kv7ZWca2z4YyFoTurmzKMaDQVNtrpY00,6888
+staleflight/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+staleflight-0.1.0.dist-info/METADATA,sha256=qgP96vLNNu6H6bkFOKykgsbFdLifoyPWoMKree-LR2w,4714
+staleflight-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+staleflight-0.1.0.dist-info/licenses/LICENSE,sha256=K9kfzteXibjTOhXPG7bWZH6qKxbnHwVKF3mLhcv2O1o,1070
+staleflight-0.1.0.dist-info/RECORD,,

staleflight-0.1.0.dist-info/WHEEL

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

staleflight-0.1.0.dist-info/licenses/LICENSE

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