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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lago-python-client
-Version: 1.45.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.45.0 → lago_python_client-1.47.0}/lago_python_client/base_client.py

@@ -1,16 +1,24 @@
 from abc import ABC, abstractmethod
-from typing import Type
+from typing import Optional, Type
 
 from lago_python_client.base_model import BaseModel
+from lago_python_client.services.rate_limit import RateLimitRetryConfig
 
 
 class BaseClient(ABC):
     """The base class used for each collection client."""
 
-    def __init__(self, base_url: str, api_key: str, base_ingest_url: str = ""):
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        base_ingest_url: str = "",
+        rate_limit_retry_config: Optional[RateLimitRetryConfig] = None,
+    ):
         self.base_url = base_url
         self.api_key = api_key
         self.base_ingest_url = base_ingest_url
+        self.rate_limit_retry_config = rate_limit_retry_config or RateLimitRetryConfig()
 
     @property
     @classmethod

{lago_python_client-1.45.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,6 +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 RateLimitCallback, RateLimitRetryConfig
 from .subscriptions.charges_client import SubscriptionChargesClient
 from .subscriptions.clients import SubscriptionClient
 from .subscriptions.fixed_charges_client import SubscriptionFixedChargesClient
@@ -53,12 +55,24 @@ class Client:
     API_PATH: Final[str] = "api/v1/"
 
     def __init__(
-        self, api_key: str = "", api_url: str = "", use_ingest_service: bool = False, ingest_api_url: str = ""
+        self,
+        api_key: str = "",
+        api_url: str = "",
+        use_ingest_service: bool = False,
+        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
         self.use_ingest_service: bool = use_ingest_service
         self.ingest_api_url: str = ingest_api_url
+        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
     def base_api_url(self) -> str:
@@ -76,166 +90,172 @@ class Client:
 
         return urljoin(ingest_url, Client.API_PATH)
 
+    def _create_client(self, client_class, base_url, api_key, base_ingest_url=""):
+        """Create a client instance with rate limit config."""
+        if base_ingest_url:
+            return client_class(base_url, api_key, base_ingest_url, self.rate_limit_retry_config)
+        return client_class(base_url, api_key, rate_limit_retry_config=self.rate_limit_retry_config)
+
     @callable_cached_property
     def add_ons(self) -> AddOnClient:
-        return AddOnClient(self.base_api_url, self.api_key)
+        return self._create_client(AddOnClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def billable_metrics(self) -> BillableMetricClient:
-        return BillableMetricClient(self.base_api_url, self.api_key)
+        return self._create_client(BillableMetricClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def billing_entities(self) -> BillingEntityClient:
-        return BillingEntityClient(self.base_api_url, self.api_key)
+        return self._create_client(BillingEntityClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def coupons(self) -> CouponClient:
-        return CouponClient(self.base_api_url, self.api_key)
+        return self._create_client(CouponClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def applied_coupons(self) -> AppliedCouponClient:
-        return AppliedCouponClient(self.base_api_url, self.api_key)
+        return self._create_client(AppliedCouponClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def credit_notes(self) -> CreditNoteClient:
-        return CreditNoteClient(self.base_api_url, self.api_key)
+        return self._create_client(CreditNoteClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def customers(self) -> CustomerClient:
-        return CustomerClient(self.base_api_url, self.api_key)
+        return self._create_client(CustomerClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def customer_applied_coupons(self) -> CustomerAppliedCouponsClient:
-        return CustomerAppliedCouponsClient(self.base_api_url, self.api_key)
+        return self._create_client(CustomerAppliedCouponsClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def customer_credit_notes(self) -> CustomerCreditNotesClient:
-        return CustomerCreditNotesClient(self.base_api_url, self.api_key)
+        return self._create_client(CustomerCreditNotesClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def customer_invoices(self) -> CustomerInvoicesClient:
-        return CustomerInvoicesClient(self.base_api_url, self.api_key)
+        return self._create_client(CustomerInvoicesClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def customer_payment_methods(self) -> CustomerPaymentMethodsClient:
-        return CustomerPaymentMethodsClient(self.base_api_url, self.api_key)
+        return self._create_client(CustomerPaymentMethodsClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def customer_payments(self) -> CustomerPaymentsClient:
-        return CustomerPaymentsClient(self.base_api_url, self.api_key)
+        return self._create_client(CustomerPaymentsClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def customer_payment_requests(self) -> CustomerPaymentRequestsClient:
-        return CustomerPaymentRequestsClient(self.base_api_url, self.api_key)
+        return self._create_client(CustomerPaymentRequestsClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def customer_subscriptions(self) -> CustomerSubscriptionsClient:
-        return CustomerSubscriptionsClient(self.base_api_url, self.api_key)
+        return self._create_client(CustomerSubscriptionsClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def customer_wallets(self) -> CustomerWalletsClient:
-        return CustomerWalletsClient(self.base_api_url, self.api_key)
+        return self._create_client(CustomerWalletsClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def events(self) -> EventClient:
-        return EventClient(self.base_api_url, self.api_key, self.base_ingest_api_url)
+        return self._create_client(EventClient, self.base_api_url, self.api_key, self.base_ingest_api_url)
 
     @callable_cached_property
     def fees(self) -> FeeClient:
-        return FeeClient(self.base_api_url, self.api_key)
+        return self._create_client(FeeClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def gross_revenues(self) -> GrossRevenueClient:
-        return GrossRevenueClient(self.base_api_url, self.api_key)
+        return self._create_client(GrossRevenueClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def invoices(self) -> InvoiceClient:
-        return InvoiceClient(self.base_api_url, self.api_key)
+        return self._create_client(InvoiceClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def invoiced_usages(self) -> InvoicedUsageClient:
-        return InvoicedUsageClient(self.base_api_url, self.api_key)
+        return self._create_client(InvoicedUsageClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def mrrs(self) -> MrrClient:
-        return MrrClient(self.base_api_url, self.api_key)
+        return self._create_client(MrrClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def organizations(self) -> OrganizationClient:
-        return OrganizationClient(self.base_api_url, self.api_key)
+        return self._create_client(OrganizationClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def overdue_balances(self) -> OverdueBalanceClient:
-        return OverdueBalanceClient(self.base_api_url, self.api_key)
+        return self._create_client(OverdueBalanceClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def payment_receipts(self) -> PaymentReceiptClient:
-        return PaymentReceiptClient(self.base_api_url, self.api_key)
+        return self._create_client(PaymentReceiptClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def payment_requests(self) -> PaymentRequestClient:
-        return PaymentRequestClient(self.base_api_url, self.api_key)
+        return self._create_client(PaymentRequestClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def payments(self) -> PaymentClient:
-        return PaymentClient(self.base_api_url, self.api_key)
+        return self._create_client(PaymentClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def invoice_collections(self) -> InvoiceCollectionClient:
-        return InvoiceCollectionClient(self.base_api_url, self.api_key)
+        return self._create_client(InvoiceCollectionClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def plans(self) -> PlanClient:
-        return PlanClient(self.base_api_url, self.api_key)
+        return self._create_client(PlanClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def plan_charges(self) -> PlanChargesClient:
-        return PlanChargesClient(self.base_api_url, self.api_key)
+        return self._create_client(PlanChargesClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def plan_fixed_charges(self) -> PlanFixedChargesClient:
-        return PlanFixedChargesClient(self.base_api_url, self.api_key)
+        return self._create_client(PlanFixedChargesClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def subscriptions(self) -> SubscriptionClient:
-        return SubscriptionClient(self.base_api_url, self.api_key)
+        return self._create_client(SubscriptionClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def subscription_charges(self) -> SubscriptionChargesClient:
-        return SubscriptionChargesClient(self.base_api_url, self.api_key)
+        return self._create_client(SubscriptionChargesClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def subscription_fixed_charges(self) -> SubscriptionFixedChargesClient:
-        return SubscriptionFixedChargesClient(self.base_api_url, self.api_key)
+        return self._create_client(SubscriptionFixedChargesClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def taxes(self) -> TaxClient:
-        return TaxClient(self.base_api_url, self.api_key)
+        return self._create_client(TaxClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def usages(self) -> UsageClient:
-        return UsageClient(self.base_api_url, self.api_key)
+        return self._create_client(UsageClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def wallets(self) -> WalletClient:
-        return WalletClient(self.base_api_url, self.api_key)
+        return self._create_client(WalletClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def wallet_transactions(self) -> WalletTransactionClient:
-        return WalletTransactionClient(self.base_api_url, self.api_key)
+        return self._create_client(WalletTransactionClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def webhooks(self) -> WebhookClient:
-        return WebhookClient(self.base_api_url, self.api_key)
+        return self._create_client(WebhookClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def webhook_endpoints(self) -> WebhookEndpointClient:
-        return WebhookEndpointClient(self.base_api_url, self.api_key)
+        return self._create_client(WebhookEndpointClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def activity_logs(self) -> ActivityLogClient:
-        return ActivityLogClient(self.base_api_url, self.api_key)
+        return self._create_client(ActivityLogClient, self.base_api_url, self.api_key)
 
     @callable_cached_property
     def api_logs(self) -> ApiLogClient:
-        return ApiLogClient(self.base_api_url, self.api_key)
+        return self._create_client(ApiLogClient, self.base_api_url, self.api_key)

lago_python_client-1.47.0/lago_python_client/exceptions.py

@@ -0,0 +1,69 @@
+from collections.abc import MutableMapping
+from http import HTTPStatus
+from typing import Any, Optional
+
+
+class LagoApiError(Exception):
+    def __init__(
+        self,
+        status_code: int,
+        url: Optional[str],
+        response: Any,
+        detail: Optional[str] = None,
+        headers: Optional[MutableMapping[str, str]] = None,
+    ) -> None:
+        if detail is None:
+            detail = HTTPStatus(status_code).phrase
+        self.status_code = status_code
+        self.url = url
+        self.response = response
+        self.detail = detail
+        self.headers = headers
+        super().__init__(self.response)
+
+    def __repr__(self) -> str:
+        class_name = self.__class__.__name__
+        return f"{class_name}(response={self.response!r}"
+
+
+class LagoRateLimitError(LagoApiError):
+    """Exception raised when rate limit is exceeded (HTTP 429)."""
+
+    def __init__(
+        self,
+        status_code: int,
+        url: Optional[str],
+        response: Any,
+        detail: Optional[str] = None,
+        headers: Optional[MutableMapping[str, str]] = None,
+    ) -> None:
+        super().__init__(
+            status_code=status_code,
+            url=url,
+            response=response,
+            detail=detail,
+            headers=headers,
+        )
+        # Parse rate limit headers
+        self.limit: Optional[int] = None
+        self.remaining: Optional[int] = None
+        self.reset: Optional[int] = None
+
+        if headers:
+            try:
+                self.limit = int(headers["x-ratelimit-limit"])
+            except (KeyError, ValueError, TypeError):
+                pass
+            try:
+                self.remaining = int(headers["x-ratelimit-remaining"])
+            except (KeyError, ValueError, TypeError):
+                pass
+            try:
+                self.reset = int(headers["x-ratelimit-reset"])
+            except (KeyError, ValueError, TypeError):
+                pass
+
+    def __repr__(self) -> str:
+        return (
+            f"LagoRateLimitError(limit={self.limit}, remaining={self.remaining}, reset={self.reset}, url={self.url!r})"
+        )

{lago_python_client-1.45.0 → lago_python_client-1.47.0}/lago_python_client/mixins.py

@@ -10,6 +10,7 @@ except ImportError:  # Python 3.7
 from collections.abc import Mapping
 
 from lago_python_client.base_model import BaseModel
+from lago_python_client.services.rate_limit import RateLimitRetryConfig
 
 from .services.json import to_json
 from .services.request import (
@@ -47,6 +48,8 @@ class _ClientMixin(Protocol[_PM_co]):
     def api_key(self) -> str: ...
     @property
     def base_url(self) -> str: ...
+    @property
+    def rate_limit_retry_config(self) -> RateLimitRetryConfig: ...
 
 
 class CreateCommandMixin(Generic[_M]):
@@ -71,6 +74,7 @@ class CreateCommandMixin(Generic[_M]):
             ),
             headers=make_headers(api_key=self.api_key),
             timeout=timeout,
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         # Process response data
@@ -105,6 +109,7 @@ class DestroyCommandMixin(Generic[_M]):
             ),
             headers=make_headers(api_key=self.api_key),
             timeout=timeout,
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         # Process response data
@@ -134,6 +139,7 @@ class FindAllCommandMixin(Generic[_M]):
             ),
             headers=make_headers(api_key=self.api_key),
             timeout=timeout,
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         # Process response data
@@ -167,6 +173,7 @@ class FindAllChildrenCommandMixin(Generic[_M]):
                 ),
                 query_pairs=options,
             ),
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         return prepare_index_response(
@@ -200,6 +207,7 @@ class FindChildCommandMixin(Generic[_M]):
                 query_pairs=options,
             ),
             headers=make_headers(api_key=self.api_key),
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         return prepare_object_response(
@@ -232,6 +240,7 @@ class CreateChildCommandMixin(Generic[_M]):
             ),
             content=to_json({self.ROOT_NAME: input_object.dict(exclude_none=True)}),
             headers=make_headers(api_key=self.api_key),
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         return prepare_object_response(
@@ -266,6 +275,7 @@ class UpdateChildCommandMixin(Generic[_M]):
             ),
             content=to_json({self.ROOT_NAME: input_object.dict(exclude_none=True)}),
             headers=make_headers(api_key=self.api_key),
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         return prepare_object_response(
@@ -298,6 +308,7 @@ class DestroyChildCommandMixin(Generic[_M]):
                 query_pairs=options,
             ),
             headers=make_headers(api_key=self.api_key),
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         return prepare_object_response(
@@ -327,6 +338,7 @@ class FindCommandMixin(Generic[_M]):
             ),
             headers=make_headers(api_key=self.api_key),
             timeout=timeout,
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         # Process response data
@@ -359,6 +371,7 @@ class UpdateCommandMixin(Generic[_M]):
             ),
             headers=make_headers(api_key=self.api_key),
             timeout=timeout,
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         # Process response data
@@ -389,6 +402,7 @@ class NestedCreateCommandMixin(Generic[_M]):
             ),
             headers=make_headers(api_key=self.api_key),
             timeout=timeout,
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         # Process response data
@@ -426,6 +440,7 @@ class NestedUpdateCommandMixin(Generic[_M]):
             ),
             headers=make_headers(api_key=self.api_key),
             timeout=timeout,
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         # Process response data
@@ -454,6 +469,7 @@ class NestedDestroyCommandMixin(Generic[_M]):
             ),
             headers=make_headers(api_key=self.api_key),
             timeout=timeout,
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         # Process response data
@@ -482,6 +498,7 @@ class NestedFindCommandMixin(Generic[_M]):
             ),
             headers=make_headers(api_key=self.api_key),
             timeout=timeout,
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         # Process response data
@@ -510,6 +527,7 @@ class NestedFindAllCommandMixin(Generic[_M]):
             ),
             headers=make_headers(api_key=self.api_key),
             timeout=timeout,
+            rate_limit_retry_config=self.rate_limit_retry_config,
         )
 
         # Process response data

{lago_python_client-1.45.0 → lago_python_client-1.47.0}/lago_python_client/models/fee.py

@@ -53,6 +53,8 @@ class FeeResponse(BaseResponseModel):
     total_amount_cents: Optional[int]
     unit_amount_cents: Optional[int]  # deprecated
     precise_unit_amount: Optional[str]
+    sub_total_excluding_taxes_amount_cents: Optional[int]
+    sub_total_excluding_taxes_precise_amount_cents: Optional[str]
     precise_amount: Optional[str]
     precise_total_amount: Optional[str]
     taxes_precise_amount: Optional[str]

{lago_python_client-1.45.0 → lago_python_client-1.47.0}/lago_python_client/models/invoice_custom_section.py

@@ -10,16 +10,6 @@ class InvoiceCustomSectionInput(BaseModel):
     invoice_custom_section_codes: Optional[List[str]]
 
 
-class AppliedInvoiceCustomSection(BaseResponseModel):
-    lago_id: Optional[str]
-    invoice_custom_section_id: Optional[str]
-    created_at: Optional[str]
-
-
-class AppliedInvoiceCustomSections(BaseResponseModel):
-    __root__: List[AppliedInvoiceCustomSection]
-
-
 class InvoiceCustomSectionResponse(BaseResponseModel):
     lago_id: Optional[str]
     code: Optional[str]
@@ -30,5 +20,16 @@ class InvoiceCustomSectionResponse(BaseResponseModel):
     applied_to_organization: Optional[bool]  # Deprecated
 
 
+class AppliedInvoiceCustomSection(BaseResponseModel):
+    lago_id: Optional[str]
+    invoice_custom_section_id: Optional[str]
+    created_at: Optional[str]
+    invoice_custom_section: Optional[InvoiceCustomSectionResponse]
+
+
+class AppliedInvoiceCustomSections(BaseResponseModel):
+    __root__: List[AppliedInvoiceCustomSection]
+
+
 class InvoiceCustomSectionsResponseList(BaseResponseModel):
     __root__: List[InvoiceCustomSectionResponse]

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