structlog-throttling 1.0.2__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.2.dist-info/METADATA

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: structlog-throttling
+Version: 1.0.2
+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: Codeberg, https://codeberg.org/tomasfarias/structlog-throttling
+Description-Content-Type: text/markdown
+
+# *structlog-throttling*: Throttling for *[structlog](https://www.structlog.org/)* loggers
+
+<a href="https://pypi.org/project/structlog-throttling/"><img src="https://img.shields.io/pypi/pyversions/structlog-throttling.svg" alt="Supported Python versions from PyPI." /></a>
+
+Logging offers a trade-off between visibility and performance. A particularly high performance cost can be incurred when logging in each iteration of a loop, common [hot spots](https://en.wikipedia.org/wiki/Hot_spot_%28computer_programming%29) in most programs. A solution to this problem is to space out the log calls such that they only happen every some time instead of on every iteration of the loop. By tweaking the time in between log calls we can move within the visibility-performance trade-off.
+
+*structlog-throttling* brings this solution to *[structlog](https://www.structlog.org/)* in the form of processors to throttle log calls based on time.
+
+## Getting started
+
+### Installation
+
+Install *structlog-throttling* from PyPI:
+
+```sh
+pip install structlog-throttling
+```
+
+### Configure
+
+When configuring *structlog*, use one of the processors offered by *structlog-throttling*. I recommend putting the processor close to the beginning of your processor chain, to avoid processing logs that will ultimately be dropped:
+
+```python
+import structlog
+from structlog_throttling.processors import LogTimeThrottler
+
+
+structlog.configure(
+    processors=[
+        # Logs with the same 'event' will only be allowed through every 5 seconds.
+        LogTimeThrottler("event", every_seconds=5),
+        ...
+    ]
+)
+```
+
+## Examples
+
+Throttle logs based on log level:
+
+```python
+import structlog
+from structlog_throttling.processors import LogTimeThrottler
+
+
+structlog.configure(
+    processors=[
+        structlog.processors.add_log_level,
+        LogTimeThrottler("level", every_seconds=5),
+        ...
+    ],
+)
+```

structlog_throttling-1.0.2.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.2.dist-info/WHEEL,sha256=DpNsHFUm_gffZe1FgzmqwuqiuPC6Y-uBCzibcJcdupM,78
+structlog_throttling-1.0.2.dist-info/METADATA,sha256=68LnuIrwOh_TkZv7b6qYeOwi2PJ0zpZlT5atL1LlKFw,2797
+structlog_throttling-1.0.2.dist-info/RECORD,,

structlog_throttling-1.0.2.dist-info/WHEEL

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