getresponse 0.1.0__py3-none-any.whl

getresponse/__init__.py

@@ -0,0 +1,14 @@
+"""Async, fully-typed GetResponse v3 API client."""
+
+from . import models
+from ._core import GetResponseApiError, RateLimitError
+from ._ratelimit import RateLimitOptions
+from .client import GetResponseClient
+
+__all__ = [
+    "GetResponseClient",
+    "GetResponseApiError",
+    "RateLimitError",
+    "RateLimitOptions",
+    "models",
+]

getresponse/_core.py

@@ -0,0 +1,243 @@
+"""HTTP transport: request building, auth-agnostic call plumbing, and error mapping."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+import httpx
+from pydantic import BaseModel, TypeAdapter
+
+from ._ratelimit import RateLimitOptions, _RateLimiter, _WaitExceedsMaxWait
+from .models import ErrorResponse
+
+DEFAULT_BASE_URL = "https://api.getresponse.com/v3"
+MAX_US_BASE_URL = "https://api3.getresponse360.com/v3"
+MAX_PL_BASE_URL = "https://api3.getresponse360.pl/v3"
+
+
+class GetResponseApiError(Exception):
+    """Raised for any non-2xx response; carries the parsed `ErrorResponse` fields."""
+
+    def __init__(
+        self,
+        status_code: int,
+        *,
+        code: int | None = None,
+        code_description: str | None = None,
+        message: str | None = None,
+        more_info: str | None = None,
+        context: dict[str, Any] | None = None,
+        uuid: str | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.code = code
+        self.code_description = code_description
+        self.message = message
+        self.more_info = more_info
+        self.context = context
+        self.uuid = uuid
+        super().__init__(
+            f"GetResponse API error {status_code}: {message or code_description or 'unknown error'}"
+        )
+
+    @classmethod
+    def from_response(cls, response: httpx.Response) -> GetResponseApiError:
+        """Build from an HTTP error response, tolerating a body that isn't an `ErrorResponse`."""
+        try:
+            err = ErrorResponse.model_validate(response.json())
+        except Exception:
+            return cls(status_code=response.status_code, message=response.text or None)
+        return cls(
+            status_code=response.status_code,
+            code=err.code,
+            code_description=err.code_description,
+            message=err.message,
+            more_info=err.more_info,
+            context=err.context,
+            uuid=err.uuid,
+        )
+
+
+class RateLimitError(GetResponseApiError):
+    """Raised by the rate limiter: retries after a 429 were exhausted, or a wait -- proactive
+
+    (concurrency slot / token bucket / adaptive block) or reactive (429 reset) -- would exceed
+    `RateLimitOptions.max_wait`.
+    """
+
+    def __init__(
+        self,
+        status_code: int = 429,
+        *,
+        code: int | None = None,
+        code_description: str | None = None,
+        message: str | None = None,
+        more_info: str | None = None,
+        context: dict[str, Any] | None = None,
+        uuid: str | None = None,
+        reset_seconds: float | None = None,
+        limit: int | None = None,
+        remaining: int | None = None,
+    ) -> None:
+        super().__init__(
+            status_code,
+            code=code,
+            code_description=code_description,
+            message=message,
+            more_info=more_info,
+            context=context,
+            uuid=uuid,
+        )
+        self.reset_seconds = reset_seconds
+        self.limit = limit
+        self.remaining = remaining
+
+    @classmethod
+    def from_error(
+        cls,
+        err: GetResponseApiError,
+        *,
+        reset_seconds: float | None,
+        limit: int | None,
+        remaining: int | None,
+    ) -> RateLimitError:
+        """Attach rate-limit fields to a `GetResponseApiError` already parsed from a 429."""
+        return cls(
+            err.status_code,
+            code=err.code,
+            code_description=err.code_description,
+            message=err.message,
+            more_info=err.more_info,
+            context=err.context,
+            uuid=err.uuid,
+            reset_seconds=reset_seconds,
+            limit=limit,
+            remaining=remaining,
+        )
+
+    @classmethod
+    def wait_too_long(cls, wait_seconds: float) -> RateLimitError:
+        """Build for a proactive wait that would exceed `max_wait` (no HTTP response involved)."""
+        return cls(
+            429,
+            message=f"rate limit wait of {wait_seconds:.1f}s exceeds max_wait",
+            reset_seconds=wait_seconds,
+        )
+
+
+def _int_or_none(value: str | None) -> int | None:
+    """Parse an optional header string as an int, tolerating a missing/invalid value."""
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except ValueError:
+        return None
+
+
+def _encode_query(query: dict[str, Any] | None) -> dict[str, Any] | None:
+    """Drop `None` values; encode enums/datetimes/bools to their wire representation."""
+    if not query:
+        return None
+    encoded: dict[str, Any] = {}
+    for key, value in query.items():
+        if value is None:
+            continue
+        if isinstance(value, Enum):
+            encoded[key] = value.value
+        elif isinstance(value, datetime):
+            encoded[key] = value.isoformat()
+        elif isinstance(value, bool):
+            encoded[key] = "true" if value else "false"
+        else:
+            encoded[key] = value
+    return encoded
+
+
+class _Core:
+    """Thin wrapper around an `httpx.AsyncClient`: one call site for every operation."""
+
+    def __init__(
+        self, client: httpx.AsyncClient, rate_limit: RateLimitOptions | None = None
+    ) -> None:
+        self._client = client
+        self._limiter = (
+            _RateLimiter(rate_limit) if rate_limit is not None and rate_limit.enabled else None
+        )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        path_params: dict[str, str] | None = None,
+        query: dict[str, Any] | None = None,
+        body: Any = None,
+        files: dict[str, Any] | None = None,
+        return_type: Any = None,
+    ) -> Any:
+        """Send one API call and decode the response into `return_type` (or `None`)."""
+        url = path.format(**(path_params or {}))
+        params = _encode_query(query)
+        json_body: Any = None
+        if isinstance(body, BaseModel):
+            json_body = body.model_dump(mode="json", by_alias=True, exclude_none=True)
+        elif body is not None:
+            json_body = body
+
+        response = await self._send(method, url, params, json_body, files)
+        if response.status_code >= 400:
+            raise GetResponseApiError.from_response(response)
+        if return_type is None or response.status_code == 204 or not response.content:
+            return None
+        return TypeAdapter(return_type).validate_python(response.json())
+
+    async def _send(
+        self,
+        method: str,
+        url: str,
+        params: dict[str, Any] | None,
+        json_body: Any,
+        files: dict[str, Any] | None,
+    ) -> httpx.Response:
+        """Send the request as-is when no limiter is configured (zero overhead, unchanged
+
+        behavior); otherwise run it through the limiter's proactive acquire and reactive
+        429-retry loop.
+        """
+        if self._limiter is None:
+            return await self._client.request(
+                method, url, params=params, json=json_body, files=files
+            )
+
+        attempt = 0
+        while True:
+            try:
+                await self._limiter.acquire()
+            except _WaitExceedsMaxWait as exc:
+                raise RateLimitError.wait_too_long(exc.wait_seconds) from exc
+            try:
+                response = await self._client.request(
+                    method, url, params=params, json=json_body, files=files
+                )
+            finally:
+                self._limiter.release()
+            self._limiter.observe(response.headers)
+            if response.status_code != 429:
+                return response
+
+            attempt += 1
+            err = GetResponseApiError.from_response(response)
+            reset = self._limiter.reset_seconds_from(response.headers, err.context)
+            opts = self._limiter.options
+            if attempt < opts.max_retries and reset is not None and reset <= opts.max_wait:
+                await opts.sleep(reset)
+                continue
+            raise RateLimitError.from_error(
+                err,
+                reset_seconds=reset,
+                limit=_int_or_none(response.headers.get("X-RateLimit-Limit")),
+                remaining=_int_or_none(response.headers.get("X-RateLimit-Remaining")),
+            )

getresponse/_ratelimit.py

@@ -0,0 +1,185 @@
+"""Opt-in rate limiter: a concurrency cap plus per-second/per-window token buckets.
+
+Disabled unless a `RateLimitOptions` is passed to `GetResponseClient(rate_limit=...)`. `_Core`
+owns one `_RateLimiter` per client and drives it around every send attempt: `acquire()` before
+sending (a concurrency slot, an rps token, a window token, and any adaptive block from a prior
+response), `release()` after, and `observe()`/`reset_seconds_from()` to read the response's rate
+headers. Every wait is capped by `max_wait`; exceeding it raises `_WaitExceedsMaxWait`, which
+`_Core` turns into the public `RateLimitError`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+import time
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+_RESET_RE = re.compile(r"\d+")
+
+
+def _parse_reset_seconds(value: str) -> int | None:
+    """Extract the leading integer from a header value like `"432 seconds"`."""
+    m = _RESET_RE.search(value)
+    return int(m.group()) if m else None
+
+
+async def _default_sleep(seconds: float) -> None:
+    """Default `RateLimitOptions.sleep`: real `asyncio.sleep`, overridable in tests."""
+    await asyncio.sleep(seconds)
+
+
+def _default_clock() -> float:
+    """Default `RateLimitOptions.clock`: real monotonic time, overridable in tests."""
+    return time.monotonic()
+
+
+@dataclass
+class RateLimitOptions:
+    """Opt-in rate-limit tuning; pass to `GetResponseClient(rate_limit=...)` to enable it.
+
+    `safety_margin` (range `(0, 1]`) scales `requests_per_second`/`requests_per_window` down
+    before they're used as bucket capacities -- concurrency is never scaled. `sleep`/`clock`
+    are injectable so tests can run against a fake, instantly-advancing clock.
+    """
+
+    enabled: bool = True
+    max_concurrency: int = 10
+    requests_per_second: float = 80
+    requests_per_window: float = 30000
+    window_seconds: float = 600
+    safety_margin: float = 1.0
+    max_retries: int = 5
+    max_wait: float = 60.0
+    sleep: Callable[[float], Awaitable[None]] = _default_sleep
+    clock: Callable[[], float] = _default_clock
+
+    @property
+    def effective_rps(self) -> float:
+        """`requests_per_second` scaled by `safety_margin` and floored."""
+        return float(int(self.requests_per_second * self.safety_margin))
+
+    @property
+    def effective_rpw(self) -> float:
+        """`requests_per_window` scaled by `safety_margin` and floored."""
+        return float(int(self.requests_per_window * self.safety_margin))
+
+
+class _WaitExceedsMaxWait(Exception):
+    """Internal signal: a proactive wait would exceed `max_wait`; `_Core` maps this to `RateLimitError`."""
+
+    def __init__(self, wait_seconds: float) -> None:
+        self.wait_seconds = wait_seconds
+        super().__init__(f"wait of {wait_seconds:.1f}s exceeds max_wait")
+
+
+class _TokenBucket:
+    """Continuous-refill token bucket: `capacity` tokens, refilling at `rate` tokens/second."""
+
+    def __init__(self, rate: float, capacity: float, *, clock: Callable[[], float]) -> None:
+        self._rate = rate
+        self._capacity = capacity
+        self._clock = clock
+        self._tokens = capacity
+        self._last = clock()
+
+    def _refill(self) -> None:
+        now = self._clock()
+        self._tokens = min(self._capacity, self._tokens + (now - self._last) * self._rate)
+        self._last = now
+
+    def wait_time(self) -> float:
+        """Seconds until one token is available (0 if one already is). Does not consume it."""
+        self._refill()
+        if self._tokens >= 1 or self._rate <= 0:
+            return 0.0
+        return (1 - self._tokens) / self._rate
+
+    def consume(self) -> None:
+        """Take one token. Call only right after waiting out `wait_time()`."""
+        self._refill()
+        self._tokens -= 1
+
+
+class _RateLimiter:
+    """Per-client rate limiter: wraps every send attempt with proactive and adaptive throttling."""
+
+    def __init__(self, options: RateLimitOptions) -> None:
+        self.options = options
+        self._concurrency = asyncio.Semaphore(options.max_concurrency)
+        self._rps_bucket = _TokenBucket(
+            options.effective_rps, options.effective_rps, clock=options.clock
+        )
+        self._rpw_bucket = _TokenBucket(
+            options.effective_rpw / options.window_seconds,
+            options.effective_rpw,
+            clock=options.clock,
+        )
+        self._blocked_until: float | None = None
+
+    async def acquire(self) -> None:
+        """Take a concurrency slot, then wait out whichever of rps/window/adaptive-block is
+
+        longest. Raises `_WaitExceedsMaxWait` instead of waiting past `options.max_wait`; on
+        that path the concurrency slot is released again before raising.
+        """
+        await self._concurrency.acquire()
+        try:
+            wait = 0.0
+            if self._blocked_until is not None:
+                remaining = self._blocked_until - self.options.clock()
+                if remaining <= 0:
+                    self._blocked_until = None
+                else:
+                    wait = remaining
+            wait = max(wait, self._rps_bucket.wait_time(), self._rpw_bucket.wait_time())
+            if wait > self.options.max_wait:
+                raise _WaitExceedsMaxWait(wait)
+            if wait > 0:
+                await self.options.sleep(wait)
+            self._rps_bucket.consume()
+            self._rpw_bucket.consume()
+        except Exception:
+            self._concurrency.release()
+            raise
+
+    def release(self) -> None:
+        """Free the concurrency slot taken by a matching `acquire()`."""
+        self._concurrency.release()
+
+    def observe(self, headers: httpx.Headers) -> None:
+        """Adaptive best-effort throttle: block new requests once a response reports 0 left."""
+        remaining = headers.get("X-RateLimit-Remaining")
+        if remaining is None:
+            return
+        try:
+            if int(remaining) > 0:
+                return
+        except ValueError:
+            return
+        reset = self.reset_seconds_from(headers, None)
+        wait = reset if reset is not None else self.options.window_seconds
+        self._blocked_until = self.options.clock() + wait
+
+    def reset_seconds_from(
+        self, headers: httpx.Headers, context: dict[str, Any] | None
+    ) -> float | None:
+        """Seconds until the limit resets: the `X-RateLimit-Reset` header, else
+
+        `context["timeToReset"]` (from a parsed `ErrorResponse`).
+        """
+        header_value = headers.get("X-RateLimit-Reset")
+        if header_value is not None:
+            parsed = _parse_reset_seconds(header_value)
+            if parsed is not None:
+                return float(parsed)
+        if context and context.get("timeToReset") is not None:
+            try:
+                return float(context["timeToReset"])
+            except (TypeError, ValueError):
+                return None
+        return None

getresponse/_resource_groups.py

@@ -0,0 +1,161 @@
+"""Resource-group attributes attached to GetResponseClient. Generated from the spec's tags."""
+
+from __future__ import annotations
+
+from ._core import _Core
+from .resources import (
+    AbTestsResource,
+    AbTestsSubjectResource,
+    AccountsResource,
+    AddressesResource,
+    AutorespondersResource,
+    CampaignsListsResource,
+    CartsResource,
+    CategoriesResource,
+    ClickTracksResource,
+    ContactsResource,
+    CustomEventsResource,
+    CustomFieldsResource,
+    CustomReportsResource,
+    EcommerceResource,
+    FileLibraryResource,
+    FormAndPopupResource,
+    FormsAndPopupsResource,
+    FormsResource,
+    FromFieldsResource,
+    GdprFieldsResource,
+    ImportsResource,
+    LandingPageResource,
+    LandingPagesResource,
+    LegacyFormsResource,
+    LegacyLandingPagesResource,
+    MetaFieldsResource,
+    MultimediaResource,
+    NewslettersResource,
+    OrdersResource,
+    PredefinedFieldsResource,
+    ProductsResource,
+    ProductVariantsResource,
+    RssNewslettersResource,
+    SearchContactsResource,
+    ShopsResource,
+    SmsAutomationMessagesResource,
+    SmsMessagesResource,
+    SmsResource,
+    SubscriptionConfirmationsResource,
+    SuppressionsResource,
+    TagsResource,
+    TaxesResource,
+    TrackingResource,
+    TransactionalEmailsResource,
+    TransactionalEmailsTemplatesResource,
+    WebinarsResource,
+    WebsiteResource,
+    WebsitesResource,
+    WorkflowsResource,
+)
+
+
+class _ResourceGroups:
+    """Mixin providing one typed resource-group attribute per API tag."""
+
+    ab_tests: AbTestsResource
+    ab_tests_subject: AbTestsSubjectResource
+    accounts: AccountsResource
+    addresses: AddressesResource
+    autoresponders: AutorespondersResource
+    campaigns_lists: CampaignsListsResource
+    carts: CartsResource
+    categories: CategoriesResource
+    click_tracks: ClickTracksResource
+    contacts: ContactsResource
+    custom_events: CustomEventsResource
+    custom_fields: CustomFieldsResource
+    custom_reports: CustomReportsResource
+    ecommerce: EcommerceResource
+    file_library: FileLibraryResource
+    form_and_popup: FormAndPopupResource
+    forms: FormsResource
+    forms_and_popups: FormsAndPopupsResource
+    from_fields: FromFieldsResource
+    gdpr_fields: GdprFieldsResource
+    imports: ImportsResource
+    landing_page: LandingPageResource
+    landing_pages: LandingPagesResource
+    legacy_forms: LegacyFormsResource
+    legacy_landing_pages: LegacyLandingPagesResource
+    meta_fields: MetaFieldsResource
+    multimedia: MultimediaResource
+    newsletters: NewslettersResource
+    orders: OrdersResource
+    predefined_fields: PredefinedFieldsResource
+    product_variants: ProductVariantsResource
+    products: ProductsResource
+    rss_newsletters: RssNewslettersResource
+    sms_automation_messages: SmsAutomationMessagesResource
+    sms_messages: SmsMessagesResource
+    search_contacts: SearchContactsResource
+    shops: ShopsResource
+    sms: SmsResource
+    subscription_confirmations: SubscriptionConfirmationsResource
+    suppressions: SuppressionsResource
+    tags: TagsResource
+    taxes: TaxesResource
+    tracking: TrackingResource
+    transactional_emails: TransactionalEmailsResource
+    transactional_emails_templates: TransactionalEmailsTemplatesResource
+    webinars: WebinarsResource
+    website: WebsiteResource
+    websites: WebsitesResource
+    workflows: WorkflowsResource
+
+    def _attach_resource_groups(self, core: _Core) -> None:
+        self.ab_tests = AbTestsResource(core)
+        self.ab_tests_subject = AbTestsSubjectResource(core)
+        self.accounts = AccountsResource(core)
+        self.addresses = AddressesResource(core)
+        self.autoresponders = AutorespondersResource(core)
+        self.campaigns_lists = CampaignsListsResource(core)
+        self.carts = CartsResource(core)
+        self.categories = CategoriesResource(core)
+        self.click_tracks = ClickTracksResource(core)
+        self.contacts = ContactsResource(core)
+        self.custom_events = CustomEventsResource(core)
+        self.custom_fields = CustomFieldsResource(core)
+        self.custom_reports = CustomReportsResource(core)
+        self.ecommerce = EcommerceResource(core)
+        self.file_library = FileLibraryResource(core)
+        self.form_and_popup = FormAndPopupResource(core)
+        self.forms = FormsResource(core)
+        self.forms_and_popups = FormsAndPopupsResource(core)
+        self.from_fields = FromFieldsResource(core)
+        self.gdpr_fields = GdprFieldsResource(core)
+        self.imports = ImportsResource(core)
+        self.landing_page = LandingPageResource(core)
+        self.landing_pages = LandingPagesResource(core)
+        self.legacy_forms = LegacyFormsResource(core)
+        self.legacy_landing_pages = LegacyLandingPagesResource(core)
+        self.meta_fields = MetaFieldsResource(core)
+        self.multimedia = MultimediaResource(core)
+        self.newsletters = NewslettersResource(core)
+        self.orders = OrdersResource(core)
+        self.predefined_fields = PredefinedFieldsResource(core)
+        self.product_variants = ProductVariantsResource(core)
+        self.products = ProductsResource(core)
+        self.rss_newsletters = RssNewslettersResource(core)
+        self.sms_automation_messages = SmsAutomationMessagesResource(core)
+        self.sms_messages = SmsMessagesResource(core)
+        self.search_contacts = SearchContactsResource(core)
+        self.shops = ShopsResource(core)
+        self.sms = SmsResource(core)
+        self.subscription_confirmations = SubscriptionConfirmationsResource(core)
+        self.suppressions = SuppressionsResource(core)
+        self.tags = TagsResource(core)
+        self.taxes = TaxesResource(core)
+        self.tracking = TrackingResource(core)
+        self.transactional_emails = TransactionalEmailsResource(core)
+        self.transactional_emails_templates = TransactionalEmailsTemplatesResource(core)
+        self.webinars = WebinarsResource(core)
+        self.website = WebsiteResource(core)
+        self.websites = WebsitesResource(core)
+        self.workflows = WorkflowsResource(core)

getresponse/client.py

@@ -0,0 +1,79 @@
+"""Root async client: auth, resource groups, lifecycle, and pagination."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable
+from typing import Any
+
+import httpx
+
+from ._core import DEFAULT_BASE_URL, _Core
+from ._ratelimit import RateLimitOptions
+from ._resource_groups import _ResourceGroups
+
+
+class GetResponseClient(_ResourceGroups):
+    """Async GetResponse v3 API client; one resource-group attribute per tag."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        access_token: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        transport: httpx.AsyncBaseTransport | None = None,
+        rate_limit: RateLimitOptions | None = None,
+    ) -> None:
+        if (api_key is None) == (access_token is None):
+            raise ValueError("Provide exactly one of `api_key` or `access_token`.")
+        headers = (
+            {"X-Auth-Token": f"api-key {api_key}"}
+            if api_key is not None
+            else {"Authorization": f"Bearer {access_token}"}
+        )
+        self._client = httpx.AsyncClient(
+            base_url=base_url, headers=headers, timeout=timeout, transport=transport
+        )
+        self._core = _Core(self._client, rate_limit)
+        self._attach_resource_groups(self._core)
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> GetResponseClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: object | None,
+    ) -> None:
+        await self.aclose()
+
+    async def paginate(
+        self,
+        list_method: Callable[..., Awaitable[list[Any]]],
+        *,
+        per_page: int = 100,
+        **kwargs: Any,
+    ) -> AsyncIterator[Any]:
+        """Walk every page of a `list_*` resource method, yielding items one by one.
+
+        GetResponse also reports `TotalCount`/`CurrentPage`/`TotalPages` response
+        headers, but resource methods only return typed bodies (no header access),
+        so this walks by page length instead: it stops once a page comes back empty
+        or shorter than `per_page`.
+        """
+        page = 1
+        while True:
+            items = await list_method(page=page, per_page=per_page, **kwargs)
+            if not items:
+                return
+            for item in items:
+                yield item
+            if len(items) < per_page:
+                return
+            page += 1