lago-python-client 1.46.0__tar.gz → 1.47.0__tar.gz

{lago_python_client-1.46.0 → lago_python_client-1.47.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lago-python-client
-Version: 1.46.0
+Version: 1.47.0
 Summary: Lago Python API Client
 Home-page: https://github.com/getlago/lago-python-client
 Author: Lovro Colic

{lago_python_client-1.46.0 → lago_python_client-1.47.0}/lago_python_client/client.py

@@ -1,3 +1,4 @@
+from typing import Optional
 from urllib.parse import urljoin
 
 from .activity_logs.clients import ActivityLogClient
@@ -32,7 +33,7 @@ from .payments.clients import PaymentClient
 from .plans.charges_client import PlanChargesClient
 from .plans.clients import PlanClient
 from .plans.fixed_charges_client import PlanFixedChargesClient
-from .services.rate_limit import RateLimitRetryConfig
+from .services.rate_limit import RateLimitCallback, RateLimitRetryConfig
 from .subscriptions.charges_client import SubscriptionChargesClient
 from .subscriptions.clients import SubscriptionClient
 from .subscriptions.fixed_charges_client import SubscriptionFixedChargesClient
@@ -61,6 +62,7 @@ class Client:
         ingest_api_url: str = "",
         max_retries: int = 3,
         retry_on_rate_limit: bool = True,
+        on_rate_limit_info: Optional[RateLimitCallback] = None,
     ) -> None:
         self.api_key: str = api_key
         self.api_url: str = api_url
@@ -69,6 +71,7 @@ class Client:
         self.rate_limit_retry_config: RateLimitRetryConfig = RateLimitRetryConfig(
             max_retries=max_retries,
             retry_on_rate_limit=retry_on_rate_limit,
+            on_rate_limit_info=on_rate_limit_info,
         )
 
     @property

lago_python_client-1.47.0/lago_python_client/observability.py

@@ -0,0 +1,67 @@
+"""
+Optional observability helpers for Lago rate limits.
+
+Provides ready-to-use ``on_rate_limit_info`` callbacks so callers can opt into
+rate limit observability without writing one themselves.
+
+Example:
+    from lago_python_client import Client
+    from lago_python_client.observability import LoggingRateLimitObserver
+
+    client = Client(
+        api_key="...",
+        on_rate_limit_info=LoggingRateLimitObserver(),
+    )
+"""
+
+import logging
+from typing import Optional, Sequence
+
+from .services.rate_limit import RateLimitInfo
+
+DEFAULT_THRESHOLDS: Sequence[float] = (0.80, 0.90, 0.95)
+
+
+class LoggingRateLimitObserver:
+    """
+    Emits a log line each time rate limit usage crosses a configured threshold.
+
+    Stateless across calls: every response that lands above any threshold logs.
+    If you want one-shot crossings, wrap it with your own state.
+
+    Args:
+        thresholds: Usage fractions (0.0 - 1.0) that should produce a log line.
+            Defaults to 80%, 90%, 95%.
+        logger: Logger to emit on. Defaults to ``lago_python_client.rate_limit``.
+        level: Log level used when a threshold is crossed. Defaults to WARNING.
+    """
+
+    def __init__(
+        self,
+        thresholds: Sequence[float] = DEFAULT_THRESHOLDS,
+        logger: Optional[logging.Logger] = None,
+        level: int = logging.WARNING,
+    ) -> None:
+        # Sort descending so we report the highest matching threshold first.
+        self.thresholds = tuple(sorted(thresholds, reverse=True))
+        self.logger = logger or logging.getLogger("lago_python_client.rate_limit")
+        self.level = level
+
+    def __call__(self, info: RateLimitInfo) -> None:
+        pct = info.usage_pct
+        if pct is None:
+            return
+
+        for threshold in self.thresholds:
+            if pct >= threshold:
+                self.logger.log(
+                    self.level,
+                    "Lago rate limit at %.0f%% (limit=%s, remaining=%s, reset=%ss, %s %s)",
+                    pct * 100,
+                    info.limit,
+                    info.remaining,
+                    info.reset,
+                    info.method,
+                    info.url,
+                )
+                return

{lago_python_client-1.46.0 → lago_python_client-1.47.0}/lago_python_client/services/rate_limit.py

@@ -1,11 +1,87 @@
+import logging
 import time
-from typing import TYPE_CHECKING, Optional
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Callable, Optional
 
 if TYPE_CHECKING:
     from httpx import Response
 
 from ..exceptions import LagoRateLimitError
 
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class RateLimitInfo:
+    """
+    Parsed rate limit headers from a Lago API response.
+
+    Provided to ``on_rate_limit_info`` callbacks after every successful request
+    so callers can build their own observability (metrics, logs, alerts).
+    """
+
+    limit: Optional[int]
+    remaining: Optional[int]
+    reset: Optional[int]
+    url: str
+    method: str
+
+    @property
+    def usage_pct(self) -> Optional[float]:
+        """
+        Fraction of the rate limit currently used, between 0.0 and 1.0.
+
+        Returns None when the headers aren't usable (missing, zero limit, etc.).
+        """
+        if self.limit is None or self.remaining is None or self.limit <= 0:
+            return None
+        return 1.0 - (self.remaining / self.limit)
+
+
+RateLimitCallback = Callable[[RateLimitInfo], None]
+
+
+def parse_rate_limit_info(
+    response: "Response",
+    method: str,
+    url: str,
+) -> Optional[RateLimitInfo]:
+    """
+    Parse ``x-ratelimit-*`` headers from a response into a RateLimitInfo.
+
+    Returns ``None`` when no rate limit headers are present (for example, on a
+    self-hosted Lago instance that doesn't enforce limits) so callers can skip
+    emission entirely.
+    """
+    headers = response.headers
+    limit: Optional[int] = None
+    remaining: Optional[int] = None
+    reset: Optional[int] = None
+
+    try:
+        limit = int(headers["x-ratelimit-limit"])
+    except (KeyError, ValueError, TypeError):
+        pass
+    try:
+        remaining = int(headers["x-ratelimit-remaining"])
+    except (KeyError, ValueError, TypeError):
+        pass
+    try:
+        reset = int(headers["x-ratelimit-reset"])
+    except (KeyError, ValueError, TypeError):
+        pass
+
+    if limit is None and remaining is None and reset is None:
+        return None
+
+    return RateLimitInfo(
+        limit=limit,
+        remaining=remaining,
+        reset=reset,
+        url=url,
+        method=method,
+    )
+
 
 class RateLimitRetryConfig:
     """Configuration for rate limit retry behavior."""
@@ -17,6 +93,7 @@ class RateLimitRetryConfig:
         base_backoff_seconds: float = 1.0,
         backoff_multiplier: float = 2.0,
         max_retry_delay: float = 20.0,
+        on_rate_limit_info: Optional[RateLimitCallback] = None,
     ):
         """
         Initialize rate limit retry configuration.
@@ -27,12 +104,18 @@ class RateLimitRetryConfig:
             base_backoff_seconds: Initial backoff duration in seconds for exponential backoff.
             backoff_multiplier: Multiplier for exponential backoff between retries.
             max_retry_delay: Maximum delay in seconds before a retry (default: 20).
+            on_rate_limit_info: Optional callback invoked after every successful
+                response with parsed rate limit headers. Use this to build
+                observability around the rate limit (warn at 80%, emit metrics,
+                etc.). Exceptions raised from the callback are logged and
+                swallowed so they never break the request flow.
         """
         self.max_retries = max_retries
         self.retry_on_rate_limit = retry_on_rate_limit
         self.base_backoff_seconds = base_backoff_seconds
         self.backoff_multiplier = backoff_multiplier
         self.max_retry_delay = max_retry_delay
+        self.on_rate_limit_info = on_rate_limit_info
 
     def calculate_backoff(self, retry_attempt: int) -> float:
         """
@@ -47,6 +130,32 @@ class RateLimitRetryConfig:
         return self.base_backoff_seconds * (self.backoff_multiplier**retry_attempt)
 
 
+def emit_rate_limit_info(
+    response: "Response",
+    config: "RateLimitRetryConfig",
+    method: str,
+    url: str,
+) -> None:
+    """
+    Invoke the ``on_rate_limit_info`` callback if configured.
+
+    Parses rate limit headers off the response and hands them to the user's
+    callback. Any exception raised from the callback is logged and swallowed so
+    a buggy observer never breaks the underlying request.
+    """
+    if config.on_rate_limit_info is None:
+        return
+
+    info = parse_rate_limit_info(response, method=method, url=url)
+    if info is None:
+        return
+
+    try:
+        config.on_rate_limit_info(info)
+    except Exception:
+        logger.exception("on_rate_limit_info callback raised; suppressing")
+
+
 def handle_rate_limit_response(
     response: "Response",
     config: RateLimitRetryConfig,

{lago_python_client-1.46.0 → lago_python_client-1.47.0}/lago_python_client/services/request.py

@@ -12,6 +12,7 @@ import httpx
 from ..version import LAGO_VERSION
 from .rate_limit import (
     RateLimitRetryConfig,
+    emit_rate_limit_info,
     handle_rate_limit_response,
     is_rate_limit_response,
     wait_for_retry,
@@ -92,12 +93,20 @@ def _create_retry_wrapper(
         if rate_limit_retry_config is None:
             rate_limit_retry_config = RateLimitRetryConfig()
 
+        method_name = http_method.__name__.upper()
+
         retry_attempt = 0
         while True:
             response = http_method(url, **kwargs)
 
-            # If not rate limited, return the response
+            # If not rate limited, emit observability info and return the response
             if not is_rate_limit_response(response):
+                emit_rate_limit_info(
+                    response,
+                    rate_limit_retry_config,
+                    method=method_name,
+                    url=url,
+                )
                 return response
 
             # Handle rate limit - may raise LagoRateLimitError or return wait duration

lago_python_client-1.47.0/lago_python_client/version.py

@@ -0,0 +1 @@
+LAGO_VERSION = "1.47.0"

{lago_python_client-1.46.0 → lago_python_client-1.47.0}/lago_python_client.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lago-python-client
-Version: 1.46.0
+Version: 1.47.0
 Summary: Lago Python API Client
 Home-page: https://github.com/getlago/lago-python-client
 Author: Lovro Colic

{lago_python_client-1.46.0 → lago_python_client-1.47.0}/lago_python_client.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ setup.cfg
 ./lago_python_client/exceptions.py
 ./lago_python_client/functools_ext.py
 ./lago_python_client/mixins.py
+./lago_python_client/observability.py
 ./lago_python_client/py.typed
 ./lago_python_client/version.py
 ./lago_python_client/activity_logs/__init__.py
@@ -185,6 +186,7 @@ lago_python_client/client.py
 lago_python_client/exceptions.py
 lago_python_client/functools_ext.py
 lago_python_client/mixins.py
+lago_python_client/observability.py
 lago_python_client/py.typed
 lago_python_client/version.py
 lago_python_client.egg-info/PKG-INFO

{lago_python_client-1.46.0 → lago_python_client-1.47.0}/tests/test_rate_limit.py

@@ -1,3 +1,4 @@
+import logging
 import os
 
 import pytest
@@ -5,7 +6,12 @@ from pytest_httpx import HTTPXMock
 
 from lago_python_client.client import Client
 from lago_python_client.exceptions import LagoApiError, LagoRateLimitError
-from lago_python_client.services.rate_limit import RateLimitRetryConfig
+from lago_python_client.observability import LoggingRateLimitObserver
+from lago_python_client.services.rate_limit import (
+    RateLimitInfo,
+    RateLimitRetryConfig,
+    parse_rate_limit_info,
+)
 
 ENDPOINT = "https://api.getlago.com/api/v1/api_logs"
 
@@ -318,3 +324,279 @@ class TestRateLimitResponses:
         error = exc_info.value
         assert isinstance(error, LagoApiError)
         assert not isinstance(error, LagoRateLimitError)
+
+
+class TestRateLimitInfo:
+    def test_usage_pct_basic(self):
+        info = RateLimitInfo(
+            limit=100,
+            remaining=20,
+            reset=30,
+            url="u",
+            method="GET",
+        )
+        assert info.usage_pct == pytest.approx(0.80)
+
+    def test_usage_pct_full(self):
+        info = RateLimitInfo(
+            limit=100,
+            remaining=0,
+            reset=30,
+            url="u",
+            method="GET",
+        )
+        assert info.usage_pct == pytest.approx(1.0)
+
+    def test_usage_pct_none_when_limit_missing(self):
+        info = RateLimitInfo(
+            limit=None,
+            remaining=20,
+            reset=30,
+            url="u",
+            method="GET",
+        )
+        assert info.usage_pct is None
+
+    def test_usage_pct_none_when_remaining_missing(self):
+        info = RateLimitInfo(
+            limit=100,
+            remaining=None,
+            reset=30,
+            url="u",
+            method="GET",
+        )
+        assert info.usage_pct is None
+
+    def test_usage_pct_none_when_limit_zero(self):
+        info = RateLimitInfo(
+            limit=0,
+            remaining=0,
+            reset=30,
+            url="u",
+            method="GET",
+        )
+        assert info.usage_pct is None
+
+
+class TestParseRateLimitInfo:
+    def _make_response(self, headers):
+        class _R:
+            def __init__(self, h):
+                self.headers = h
+
+        return _R(headers)
+
+    def test_parse_full_headers(self):
+        resp = self._make_response(
+            {
+                "x-ratelimit-limit": "100",
+                "x-ratelimit-remaining": "42",
+                "x-ratelimit-reset": "5",
+            }
+        )
+
+        info = parse_rate_limit_info(resp, method="GET", url="https://x")
+
+        assert info is not None
+        assert info.limit == 100
+        assert info.remaining == 42
+        assert info.reset == 5
+        assert info.method == "GET"
+        assert info.url == "https://x"
+
+    def test_parse_returns_none_when_headers_absent(self):
+        resp = self._make_response({})
+        assert parse_rate_limit_info(resp, method="GET", url="https://x") is None
+
+    def test_parse_partial_headers(self):
+        resp = self._make_response({"x-ratelimit-limit": "100"})
+
+        info = parse_rate_limit_info(resp, method="GET", url="https://x")
+
+        assert info is not None
+        assert info.limit == 100
+        assert info.remaining is None
+        assert info.reset is None
+
+    def test_parse_invalid_headers(self):
+        resp = self._make_response(
+            {
+                "x-ratelimit-limit": "not-a-number",
+                "x-ratelimit-remaining": "nope",
+                "x-ratelimit-reset": "bad",
+            }
+        )
+
+        # All fields fail to parse -> all None -> treated as no rate limit info
+        assert parse_rate_limit_info(resp, method="GET", url="https://x") is None
+
+
+class TestRateLimitInfoCallback:
+    def test_callback_fires_on_success(self, httpx_mock: HTTPXMock):
+        """Callback receives rate limit info after a 2xx response."""
+        captured = []
+
+        client = Client(api_key="test-key", on_rate_limit_info=captured.append)
+        request_id = "test-id"
+
+        httpx_mock.add_response(
+            method="GET",
+            url=ENDPOINT + f"/{request_id}",
+            status_code=200,
+            headers={
+                "x-ratelimit-limit": "100",
+                "x-ratelimit-remaining": "20",
+                "x-ratelimit-reset": "5",
+            },
+            content=mock_response("fixtures/api_log.json"),
+        )
+
+        client.api_logs.find(request_id)
+
+        assert len(captured) == 1
+        info = captured[0]
+        assert info.limit == 100
+        assert info.remaining == 20
+        assert info.reset == 5
+        assert info.usage_pct == pytest.approx(0.80)
+        assert info.method == "GET"
+
+    def test_callback_not_called_when_headers_absent(self, httpx_mock: HTTPXMock):
+        """Self-hosted-style response with no rate limit headers must not call back."""
+        captured = []
+
+        client = Client(api_key="test-key", on_rate_limit_info=captured.append)
+        request_id = "test-id"
+
+        httpx_mock.add_response(
+            method="GET",
+            url=ENDPOINT + f"/{request_id}",
+            status_code=200,
+            content=mock_response("fixtures/api_log.json"),
+        )
+
+        client.api_logs.find(request_id)
+
+        assert captured == []
+
+    def test_callback_exception_is_swallowed(self, httpx_mock: HTTPXMock, caplog):
+        """A buggy callback must not break the request."""
+
+        def boom(info):
+            raise RuntimeError("intentional")
+
+        client = Client(api_key="test-key", on_rate_limit_info=boom)
+        request_id = "test-id"
+
+        httpx_mock.add_response(
+            method="GET",
+            url=ENDPOINT + f"/{request_id}",
+            status_code=200,
+            headers={
+                "x-ratelimit-limit": "100",
+                "x-ratelimit-remaining": "1",
+                "x-ratelimit-reset": "5",
+            },
+            content=mock_response("fixtures/api_log.json"),
+        )
+
+        with caplog.at_level(logging.ERROR, logger="lago_python_client.services.rate_limit"):
+            result = client.api_logs.find(request_id)
+
+        assert result is not None
+        assert any("on_rate_limit_info callback raised" in rec.message for rec in caplog.records)
+
+    def test_callback_fires_only_once_after_429_retry_resolves(
+        self,
+        httpx_mock: HTTPXMock,
+        monkeypatch,
+    ):
+        """After a 429 retry sequence resolves to 2xx, callback fires once for the success."""
+        monkeypatch.setattr("lago_python_client.services.rate_limit.time.sleep", lambda _: None)
+
+        captured = []
+        client = Client(api_key="test-key", on_rate_limit_info=captured.append)
+        request_id = "test-id"
+
+        httpx_mock.add_response(
+            method="GET",
+            url=ENDPOINT + f"/{request_id}",
+            status_code=429,
+            headers={"x-ratelimit-reset": "1"},
+        )
+        httpx_mock.add_response(
+            method="GET",
+            url=ENDPOINT + f"/{request_id}",
+            status_code=200,
+            headers={
+                "x-ratelimit-limit": "100",
+                "x-ratelimit-remaining": "50",
+                "x-ratelimit-reset": "5",
+            },
+            content=mock_response("fixtures/api_log.json"),
+        )
+
+        client.api_logs.find(request_id)
+
+        assert len(captured) == 1
+        assert captured[0].remaining == 50
+
+    def test_callback_not_called_when_429_exhausts(
+        self,
+        httpx_mock: HTTPXMock,
+        monkeypatch,
+    ):
+        """Exhausted 429 retries raise without ever invoking the success callback."""
+        monkeypatch.setattr("lago_python_client.services.rate_limit.time.sleep", lambda _: None)
+
+        captured = []
+        client = Client(api_key="test-key", on_rate_limit_info=captured.append)
+        request_id = "test-id"
+
+        for _ in range(4):
+            httpx_mock.add_response(
+                method="GET",
+                url=ENDPOINT + f"/{request_id}",
+                status_code=429,
+                headers={"x-ratelimit-reset": "1"},
+            )
+
+        with pytest.raises(LagoRateLimitError):
+            client.api_logs.find(request_id)
+
+        assert captured == []
+
+
+class TestLoggingRateLimitObserver:
+    def _info(self, *, limit, remaining):
+        return RateLimitInfo(
+            limit=limit,
+            remaining=remaining,
+            reset=10,
+            url="https://x",
+            method="GET",
+        )
+
+    def test_logs_above_threshold(self, caplog):
+        observer = LoggingRateLimitObserver(thresholds=(0.80, 0.90, 0.95))
+
+        with caplog.at_level(logging.WARNING, logger="lago_python_client.rate_limit"):
+            observer(self._info(limit=100, remaining=4))  # 96% used
+
+        assert any("96%" in rec.getMessage() for rec in caplog.records)
+
+    def test_silent_below_threshold(self, caplog):
+        observer = LoggingRateLimitObserver(thresholds=(0.80,))
+
+        with caplog.at_level(logging.WARNING, logger="lago_python_client.rate_limit"):
+            observer(self._info(limit=100, remaining=50))  # 50% used
+
+        assert caplog.records == []
+
+    def test_silent_when_usage_pct_unavailable(self, caplog):
+        observer = LoggingRateLimitObserver()
+
+        with caplog.at_level(logging.WARNING, logger="lago_python_client.rate_limit"):
+            observer(self._info(limit=None, remaining=None))
+
+        assert caplog.records == []

lago_python_client-1.46.0/lago_python_client/version.py

@@ -1 +0,0 @@
-LAGO_VERSION = "1.46.0"