sendmux-core 1.0.0__py3-none-any.whl

sendmux_core/__init__.py

@@ -0,0 +1,17 @@
+from sendmux_core.auth import configure_auth, validate_api_key
+from sendmux_core.errors import SendmuxApiError
+from sendmux_core.headers import conditional_headers, idempotency_headers
+from sendmux_core.pagination import CursorPage, iter_cursor_pages
+from sendmux_core.retry import RetryOptions
+
+__all__ = [
+    "CursorPage",
+    "RetryOptions",
+    "SendmuxApiError",
+    "conditional_headers",
+    "configure_auth",
+    "idempotency_headers",
+    "iter_cursor_pages",
+    "validate_api_key",
+]
+

sendmux_core/auth.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+ApiKeySurface = Literal["root", "mailbox"]
+
+
+def validate_api_key(api_key: str, *, surface: ApiKeySurface) -> None:
+    expected_prefix = "smx_mbx_" if surface == "mailbox" else "smx_root_"
+    if not api_key.startswith(expected_prefix):
+        raise ValueError(f"Expected a {expected_prefix} API key for the {surface} surface")
+
+
+def configure_auth(configuration: Any, *, api_key: str) -> None:
+    configuration.api_key["BearerAuth"] = api_key
+    configuration.api_key_prefix["BearerAuth"] = "Bearer"
+

sendmux_core/errors.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+
+@dataclass(frozen=True)
+class SendmuxApiError(Exception):
+    status_code: int | None
+    code: str
+    message: str
+    retryable: bool
+    request_id: str | None
+    headers: Mapping[str, str]
+    raw_body: str | None = None
+
+    def __str__(self) -> str:
+        status = f"{self.status_code} " if self.status_code is not None else ""
+        return f"{status}{self.code}: {self.message}"
+
+
+def map_api_exception(exc: Any) -> SendmuxApiError:
+    headers = _headers(exc)
+    payload = _payload(exc)
+    detail = _error_detail(payload)
+    status_code = getattr(exc, "status", None)
+    code = _string(detail.get("code")) or "api_error"
+    message = _string(detail.get("message")) or _string(getattr(exc, "reason", None)) or "Sendmux API request failed"
+    retryable = _bool(detail.get("retryable"))
+
+    return SendmuxApiError(
+        status_code=status_code if isinstance(status_code, int) else None,
+        code=code,
+        message=message,
+        retryable=retryable if retryable is not None else _default_retryable(status_code),
+        request_id=_request_id(payload) or _header(headers, "x-request-id"),
+        headers=headers,
+        raw_body=getattr(exc, "body", None),
+    )
+
+
+def _headers(exc: Any) -> Mapping[str, str]:
+    value = getattr(exc, "headers", None)
+    if not value:
+        return {}
+    return {str(key): str(child) for key, child in dict(value).items()}
+
+
+def _payload(exc: Any) -> Any:
+    data = getattr(exc, "data", None)
+    if data is not None:
+        if hasattr(data, "to_dict"):
+            return data.to_dict()
+        return data
+
+    body = getattr(exc, "body", None)
+    if isinstance(body, str) and body:
+        try:
+            return json.loads(body)
+        except json.JSONDecodeError:
+            return None
+    return None
+
+
+def _error_detail(payload: Any) -> Mapping[str, Any]:
+    if not isinstance(payload, Mapping):
+        return {}
+    error = payload.get("error")
+    if isinstance(error, Mapping):
+        return error
+    return {}
+
+
+def _request_id(payload: Any) -> str | None:
+    if not isinstance(payload, Mapping):
+        return None
+    meta = payload.get("meta")
+    if not isinstance(meta, Mapping):
+        return None
+    return _string(meta.get("request_id"))
+
+
+def _header(headers: Mapping[str, str], name: str) -> str | None:
+    name = name.lower()
+    for key, value in headers.items():
+        if key.lower() == name:
+            return value
+    return None
+
+
+def _string(value: Any) -> str | None:
+    return value if isinstance(value, str) and value else None
+
+
+def _bool(value: Any) -> bool | None:
+    return value if isinstance(value, bool) else None
+
+
+def _default_retryable(status_code: Any) -> bool:
+    return isinstance(status_code, int) and (status_code == 429 or status_code >= 500)

sendmux_core/headers.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+
+def idempotency_headers(idempotency_key: str | None = None) -> dict[str, str]:
+    return {"Idempotency-Key": idempotency_key} if idempotency_key else {}
+
+
+def conditional_headers(*, if_match: str | None = None, if_none_match: str | None = None) -> dict[str, str]:
+    headers: dict[str, str] = {}
+    if if_match:
+        headers["If-Match"] = if_match
+    if if_none_match:
+        headers["If-None-Match"] = if_none_match
+    return headers
+

sendmux_core/pagination.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator, Sequence
+from dataclasses import dataclass
+from typing import Generic, Protocol, TypeVar
+
+T = TypeVar("T")
+
+
+class PaginationMeta(Protocol):
+    has_more: bool
+    next_cursor: str | None
+
+
+class CursorResponse(Protocol[T]):
+    data: Sequence[T]
+    pagination: PaginationMeta
+
+
+@dataclass(frozen=True)
+class CursorPage(Generic[T]):
+    data: Sequence[T]
+    has_more: bool
+    next_cursor: str | None
+
+
+def iter_cursor_pages(fetch_page: Callable[[str | None], CursorResponse[T]]) -> Iterator[T]:
+    cursor: str | None = None
+
+    while True:
+        response = fetch_page(cursor)
+        for item in response.data:
+            yield item
+
+        if not response.pagination.has_more:
+            return
+
+        next_cursor = response.pagination.next_cursor
+        if not next_cursor or next_cursor == cursor:
+            raise RuntimeError("Sendmux cursor pagination did not return a new next_cursor")
+        cursor = next_cursor

sendmux_core/retry.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import random
+import time
+from dataclasses import dataclass
+from email.utils import parsedate_to_datetime
+from typing import Any, Callable, Mapping
+
+
+@dataclass(frozen=True)
+class RetryOptions:
+    max_attempts: int = 3
+    base_delay_seconds: float = 0.25
+    max_delay_seconds: float = 4.0
+    sleep: Callable[[float], None] = time.sleep
+
+
+class RetryingRestClient:
+    def __init__(self, inner: Any, *, retry_options: RetryOptions | None = None) -> None:
+        self._inner = inner
+        self._options = retry_options or RetryOptions()
+
+    def request(self, method: str, url: str, **kwargs: Any) -> Any:
+        attempt = 1
+        while True:
+            response = self._inner.request(method, url, **kwargs)
+            if not self._should_retry(method, kwargs.get("headers") or {}, response, attempt):
+                return response
+
+            delay = self._delay_seconds(response.headers, attempt)
+            _release_response(response)
+            self._options.sleep(delay)
+            attempt += 1
+
+    def _should_retry(self, method: str, headers: Mapping[str, str], response: Any, attempt: int) -> bool:
+        if attempt >= self._options.max_attempts:
+            return False
+        if response.status not in {408, 409, 425, 429, 500, 502, 503, 504}:
+            return False
+        method = method.upper()
+        if method in {"GET", "HEAD", "OPTIONS"}:
+            return True
+        return method == "POST" and _header(headers, "idempotency-key") is not None
+
+    def _delay_seconds(self, headers: Mapping[str, str], attempt: int) -> float:
+        retry_after = _retry_after_seconds(_header(headers, "retry-after"))
+        if retry_after is not None:
+            return min(retry_after, self._options.max_delay_seconds)
+
+        rate_limit_reset = _rate_limit_reset_seconds(_header(headers, "x-ratelimit-reset"))
+        if rate_limit_reset is not None:
+            return min(rate_limit_reset, self._options.max_delay_seconds)
+
+        exponential = min(
+            self._options.base_delay_seconds * (2 ** (attempt - 1)),
+            self._options.max_delay_seconds,
+        )
+        return random.uniform(0, exponential)
+
+
+def _header(headers: Mapping[str, str], name: str) -> str | None:
+    name = name.lower()
+    for key, value in headers.items():
+        if key.lower() == name:
+            return value
+    return None
+
+
+def _retry_after_seconds(value: str | None) -> float | None:
+    if not value:
+        return None
+    try:
+        return max(float(value), 0.0)
+    except ValueError:
+        try:
+            return max(parsedate_to_datetime(value).timestamp() - time.time(), 0.0)
+        except (TypeError, ValueError):
+            return None
+
+
+def _rate_limit_reset_seconds(value: str | None) -> float | None:
+    if not value:
+        return None
+    try:
+        return max(float(value) - time.time(), 0.0)
+    except ValueError:
+        return None
+
+
+def _release_response(response: Any) -> None:
+    raw = getattr(response, "response", None)
+    release_conn = getattr(raw, "release_conn", None)
+    if callable(release_conn):
+        release_conn()

sendmux_core-1.0.0.dist-info/METADATA

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: sendmux-core
+Version: 1.0.0
+Summary: Shared runtime helpers for the Sendmux Python SDK packages.
+Project-URL: Repository, https://github.com/Sendmux/sendmux-sdk
+Requires-Python: >=3.10
+Requires-Dist: urllib3<3,>=2.3.0
+Description-Content-Type: text/markdown
+
+# sendmux-core
+
+Shared runtime helpers for the Sendmux Python SDK packages.
+

sendmux_core-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+sendmux_core/__init__.py,sha256=yjbS2853lFzEvlXATXtweS_unHkDuZ2xvMlSM2FIGQQ,497
+sendmux_core/auth.py,sha256=HiwZcpv83bCeaVQpu8hR7kvNrmudHi3OLZoQ7jRPU_E,575
+sendmux_core/errors.py,sha256=cnF_ts7WAX7sjwXzUwWRdVkZmBJwOzfwFEpJhIL02l0,2899
+sendmux_core/headers.py,sha256=tYTUQV2Xqpa4_lyod_fslY65xj2ASxKZCitH-l0K_tE,482
+sendmux_core/pagination.py,sha256=EjPENnfzxbzcmN-9S8AYaUWTdDfJIbsRcH5MAmLpgJc,1020
+sendmux_core/retry.py,sha256=lT41uux8NPbV1XCss9jASpfyJMeFSGLSd-jMfRmsibE,3142
+sendmux_core-1.0.0.dist-info/METADATA,sha256=S2hVVCkdppGqEU3OX2Oz_vnA3Tsff9Gcoz0pBD0jao4,364
+sendmux_core-1.0.0.dist-info/WHEEL,sha256=KvPDMDa6F56cTSWKcFW-N0kTgjEkQQ6hmuMKcPkRB_Y,87
+sendmux_core-1.0.0.dist-info/RECORD,,

sendmux_core-1.0.0.dist-info/WHEEL

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