structlog-throttling 1.0.0__py3-none-any.whl

structlog_throttling/__init__.py

@@ -0,0 +1,3 @@
+__title__ = "structlog-throttling"
+__author__ = "Tomás Farías Santana"
+__copyright__ = "Copyright (c) 2025 Tomás Farías Santana"

structlog_throttling/processors.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import logging
+import typing
+
+from structlog import DropEvent
+from structlog.typing import EventDict
+
+from .throttlers import ThrottlerProtocol, TimeThrottler
+
+_T = typing.TypeVar("_T", bound=ThrottlerProtocol)
+
+__all__ = [
+    "LogTimeThrottler",
+]
+
+
+class LogTimeThrottler:
+    """Drop logs when throttled based on time in between calls.
+
+    This should generally be close to the top of your processor chain so that processors
+    run in a log that will ultimately be throttled.
+
+    Args:
+        key: Unique key in the ``event_dict`` to determine if log should be throttled.
+        every_seconds: How long to throttle logs for, in seconds.
+    """
+
+    def __init__(self, key: str, every_seconds: int | float) -> None:
+        self.key = key
+        self.throttler = TimeThrottler(every_seconds)
+
+    def __call__(self, _: logging.Logger, __: str, event_dict: EventDict) -> EventDict:
+        if self.throttler.is_throttled(event_dict[self.key]):
+            raise DropEvent
+        return event_dict

structlog_throttling/throttlers.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import time
+import typing
+import weakref
+
+
+class _Hashable(typing.Protocol):
+    def __hash__(self) -> int: ...
+
+
+class ThrottlerProtocol(typing.Protocol):
+    def is_throttled(self, key: str) -> bool: ...
+
+
+class _Link:
+    """A link in a doubly-linked list"""
+
+    __slots__ = "at", "previous", "next", "__weakref__"
+    previous: "_Link" | None
+    next: "_Link" | None
+    at: float | None
+
+
+class TimeThrottler:
+    """A throttler for time-based throttling."""
+
+    def __init__(self, every_seconds: int | float) -> None:
+        self.every = every_seconds
+
+        self._last: _Link | None = None
+        self._indexes = weakref.WeakValueDictionary()
+
+    def is_throttled(self, key: _Hashable) -> bool:
+        """Determine whether ``key`` is throttled.
+
+        Examples:
+            >>> tt = TimeThrottler(every_seconds=1)
+            >>> tt.is_throttled("event")
+            False
+            >>> tt.is_throttled("event")
+            True
+            >>> tt.is_throttled("another-event")
+            False
+            >>> tt.is_throttled("another-event")
+            True
+            >>> time.sleep(1)
+            >>> tt.is_throttled("event")
+            False
+            >>> tt.is_throttled("another-event")
+            False
+        """
+        now = time.monotonic()
+
+        if key not in self._indexes:
+            new = _Link()
+            new.at = now
+            # Stores a weak reference
+            self._indexes[key] = new
+
+            if self._last:
+                # 'next' is a weak reference
+                self._last.next = self._indexes[key]
+                # 'previous' is not
+                new.previous = self._last
+
+            self._last = new
+
+            return False
+
+        link = self._indexes[key]
+        if (now - link.at) >= self.every:
+            del link
+            return False
+
+        return True

structlog_throttling-1.0.0.dist-info/METADATA

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: structlog-throttling
+Version: 1.0.0
+Summary: Log throttling utilities for structlog.
+Keywords: structlog,throttling,throttle
+License-Expression: MIT OR Apache-2.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Dist: structlog>=25.5.0
+Requires-Python: >=3.9
+Project-URL: GitHub, https://github.com/tomasfarias/structlog-throttling
+Description-Content-Type: text/markdown
+
+# *structlog-throttling*: Throttling for [structlog](https://www.structlog.org/) loggers

structlog_throttling-1.0.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+structlog_throttling/__init__.py,sha256=KtJ2XWBLHTNeOBHq5r6OR7-m8Kmk570EEXItCTineco,133
+structlog_throttling/processors.py,sha256=b61N6jsAOYno4usPuRxtDYxe6gjEsGl4wCqCaF3LPX8,1043
+structlog_throttling/throttlers.py,sha256=hLqWLNp7OGRswy480C8YcwqDD04cRAeahwO5ezFZeOo,1885
+structlog_throttling-1.0.0.dist-info/WHEEL,sha256=DpNsHFUm_gffZe1FgzmqwuqiuPC6Y-uBCzibcJcdupM,78
+structlog_throttling-1.0.0.dist-info/METADATA,sha256=SioRAzLRDnXn4HqJh5VVBW5tBUMKwj5lZkkuIPnQdyk,992
+structlog_throttling-1.0.0.dist-info/RECORD,,

structlog_throttling-1.0.0.dist-info/WHEEL

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