augstash 0.2.0__py3-none-any.whl

augstash/__init__.py

@@ -0,0 +1,39 @@
+"""augstash - the Python client for the Augstash API.
+
+The hand-written entry points live here; the generated client (154 API classes and their models)
+lives under ``augstash.generated`` and is regenerated by ``python sdk/tools/refresh.py``.
+
+    from augstash import AugstashClient, AugstashError
+    from augstash.generated.api import ContactApi
+"""
+from augstash.client import AugstashClient
+from augstash.errors import AugstashConfigError, AugstashConnectionError, AugstashError
+from augstash.pagination import paginate_cursor, paginate_pages
+from augstash.transport import AugstashApiClient, RetryPolicy, parse_retry_after
+from augstash.webhooks import (
+    EVENT_HEADER,
+    EVENT_ID_HEADER,
+    SIGNATURE_HEADER,
+    sign_webhook,
+    verify_webhook_signature,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AugstashClient",
+    "AugstashApiClient",
+    "AugstashError",
+    "AugstashConnectionError",
+    "AugstashConfigError",
+    "RetryPolicy",
+    "parse_retry_after",
+    "paginate_pages",
+    "paginate_cursor",
+    "verify_webhook_signature",
+    "sign_webhook",
+    "SIGNATURE_HEADER",
+    "EVENT_HEADER",
+    "EVENT_ID_HEADER",
+    "__version__",
+]

augstash/client.py

@@ -0,0 +1,95 @@
+"""The entry point: one configured client, from which every API surface is taken.
+
+::
+
+    from augstash import AugstashClient
+    from augstash.generated.api import WalletApi, SmsApi
+
+    client = AugstashClient(
+        base_url=os.environ["AUGSTASH_BASE_URL"],   # no default beyond localhost - pass your own
+        api_key=os.environ["AUGSTASH_API_KEY"],     # ask_live_<keyId>.<secret>
+    )
+
+    balance = client.api(WalletApi).balance()
+    client.api(SmsApi).send_sms(send_sms_request=SendSmsRequest(to="+919000000000", body="hi"))
+
+There are 154 API classes, one per controller, and ``client.api(X)`` reaches any of them: it hands
+back a cached, fully configured instance. No hand-written list of accessors exists on purpose - one
+would drift the moment an endpoint is added.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Type, TypeVar
+
+from augstash.errors import AugstashConfigError
+from augstash.generated.configuration import Configuration
+from augstash.transport import AugstashApiClient, RetryPolicy
+
+T = TypeVar("T")
+
+
+class AugstashClient:
+    """A configured Augstash API client."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: Optional[str] = None,
+        bearer_token: Optional[str] = None,
+        timeout: Optional[float] = 30.0,
+        retry: Optional[RetryPolicy] = None,
+        idempotency: bool = True,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> None:
+        """
+        :param base_url: origin of the Augstash API for your environment. Required.
+        :param api_key: an ``ask_live_*`` key, sent as ``X-Api-Key``
+        :param bearer_token: an Augstash-issued user JWT; reaches endpoints a key cannot
+        :param timeout: per-request timeout in seconds
+        :param retry: retry policy for 429/502/503/504 and transport failures
+        :param idempotency: send ``X-Idempotency-Key`` on mutating calls. Turning it off also stops
+            mutating calls being retried, because a retry would then risk executing twice.
+        :param headers: extra headers on every request
+        """
+        if not base_url:
+            raise AugstashConfigError("base_url is required - there is no default Augstash host")
+        if not api_key and not bearer_token:
+            raise AugstashConfigError("pass either api_key (ask_live_*) or bearer_token")
+
+        configuration = Configuration(host=base_url.rstrip("/"))
+        if api_key:
+            configuration.api_key["ApiKeyAuth"] = api_key
+        if bearer_token:
+            configuration.access_token = bearer_token
+
+        self.configuration = configuration
+        self.api_client = AugstashApiClient(configuration, retry=retry, idempotency=idempotency)
+        self.api_client.user_agent = "augstash-python/0.1.0"
+        for name, value in (headers or {}).items():
+            self.api_client.set_default_header(name, value)
+        self._timeout = timeout
+        self._instances: Dict[type, Any] = {}
+
+    @property
+    def timeout(self) -> Optional[float]:
+        """Per-request timeout in seconds. Pass ``_request_timeout=`` on a call to override it."""
+        return self._timeout
+
+    def api(self, api_class: Type[T]) -> T:
+        """A configured instance of any generated API class, created once and reused."""
+        existing = self._instances.get(api_class)
+        if existing is not None:
+            return existing  # type: ignore[return-value]
+        created = api_class(self.api_client)  # type: ignore[call-arg]
+        self._instances[api_class] = created
+        return created
+
+    def close(self) -> None:
+        """Release the underlying connection pool."""
+        self.api_client.close()
+
+    def __enter__(self) -> "AugstashClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()

augstash/errors.py

@@ -0,0 +1,73 @@
+"""Errors the Augstash API raises, in the shape it actually sends them.
+
+A failure arrives as ``{"success": false, "code": ..., "data": {"code", "fieldErrors", "detail"},
+"message": ..., "traceId": ...}``. ``code`` is the stable name to branch on; ``message`` is
+localized text that changes with the caller's language and must never be matched against.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+
+class AugstashError(Exception):
+    """Every error raised for a call the server answered.
+
+    Branch on :attr:`code`. Quote :attr:`trace_id` in a support request - it is the correlation id
+    the backend logged the failure under.
+    """
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        trace_id: Optional[str] = None,
+        detail: Optional[str] = None,
+        field_errors: Optional[List[Dict[str, Any]]] = None,
+        method: Optional[str] = None,
+        url: Optional[str] = None,
+        retry_after_seconds: Optional[float] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.trace_id = trace_id
+        self.detail = detail
+        self.field_errors = field_errors or []
+        self.method = method
+        self.url = url
+        self.retry_after_seconds = retry_after_seconds
+
+    @property
+    def is_authentication_error(self) -> bool:
+        """No key, an unknown key, or an expired token."""
+        return self.status == 401
+
+    @property
+    def is_permission_error(self) -> bool:
+        """Authenticated, but this key lacks the scope - or the endpoint needs a signed-in user."""
+        return self.status == 403
+
+    @property
+    def is_rate_limit_error(self) -> bool:
+        """The key's per-minute budget is spent; wait :attr:`retry_after_seconds`."""
+        return self.status == 429
+
+    def __str__(self) -> str:
+        detail = f" ({self.detail})" if self.detail else ""
+        trace = f" traceId={self.trace_id}" if self.trace_id else ""
+        return f"[{self.status} {self.code}] {self.message}{detail}{trace}"
+
+
+class AugstashConnectionError(AugstashError):
+    """The request never reached Augstash, or the answer never came back."""
+
+    def __init__(self, message: str, cause: Optional[BaseException] = None,
+                 method: Optional[str] = None, url: Optional[str] = None) -> None:
+        super().__init__(status=0, code="CONNECTION_ERROR", message=message, method=method, url=url)
+        self.cause = cause
+
+
+class AugstashConfigError(ValueError):
+    """Configuration this SDK refuses to start with - a missing base URL or missing credentials."""