smtpfast 0.1.0__py3-none-any.whl

smtpfast/__init__.py

@@ -0,0 +1,40 @@
+"""The official Python SDK for the SMTPfast API."""
+from . import types, webhooks
+from ._client import AsyncSMTPfast, SMTPfast
+from ._core import RequestOptions
+from ._errors import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    SMTPfastError,
+    UnprocessableEntityError,
+)
+from ._version import __version__
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "APITimeoutError",
+    "AsyncSMTPfast",
+    "AuthenticationError",
+    "BadRequestError",
+    "ConflictError",
+    "InternalServerError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "RequestOptions",
+    "SMTPfast",
+    "SMTPfastError",
+    "UnprocessableEntityError",
+    "__version__",
+    "types",
+    "webhooks",
+]

smtpfast/_client.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+import httpx
+from typing_extensions import Self
+
+from ._core import AsyncCore, SyncCore
+from ._resources import AsyncResource, Resource
+
+
+class SMTPfast(Resource):
+    """The SMTPfast API client.
+
+    >>> client = SMTPfast()  # reads SMTPFAST_API_KEY
+    >>> client.emails.send({"from": "you@yourdomain.com", "to": "them@example.org", "subject": "Hi", "text": "Hello"})
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        max_retries: int = 2,
+        timeout: float = 60.0,
+        headers: Mapping[str, str] | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        super().__init__(SyncCore(api_key, base_url, max_retries, timeout, headers, http_client=http_client))
+
+    def close(self) -> None:
+        self._core.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class AsyncSMTPfast(AsyncResource):
+    """The SMTPfast API client for asyncio. Every method is a coroutine."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        max_retries: int = 2,
+        timeout: float = 60.0,
+        headers: Mapping[str, str] | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        super().__init__(AsyncCore(api_key, base_url, max_retries, timeout, headers, http_client=http_client))
+
+    async def aclose(self) -> None:
+        await self._core.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()

smtpfast/_core.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+import asyncio
+import email.utils
+import math
+import os
+import random
+import time
+import uuid
+from collections.abc import AsyncIterator, Iterator, Mapping
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+from typing_extensions import TypedDict
+
+from ._errors import APIConnectionError, APIError, APITimeoutError, SMTPfastError
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://smtpfa.st/api"
+RETRY_STATUS = {408, 429, 500, 502, 503, 504}
+SAFE_METHODS = {"GET", "HEAD", "PUT", "DELETE", "OPTIONS"}
+MAX_RETRY_AFTER = 60.0
+# Query parameters list_all sets or cannot combine with walking forward by `after`.
+PAGINATION_MANAGED = {"before", "page", "latest"}
+
+
+class RequestOptions(TypedDict, total=False):
+    """Per-call settings: `timeout` in seconds, `max_retries`, and extra `headers`."""
+
+    timeout: float
+    max_retries: int
+    headers: Mapping[str, str]
+
+
+class _Core:
+    def __init__(
+        self,
+        api_key: str | None,
+        base_url: str | None,
+        max_retries: int,
+        timeout: float,
+        headers: Mapping[str, str] | None,
+    ) -> None:
+        key = (api_key or os.environ.get("SMTPFAST_API_KEY") or "").strip()
+        if not key:
+            raise SMTPfastError("No API key: pass api_key= or set the SMTPFAST_API_KEY environment variable.")
+        self.base_url = (base_url or os.environ.get("SMTPFAST_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.max_retries = max_retries
+        self.timeout = timeout
+        self.headers = {
+            "Authorization": f"Bearer {key}",
+            "User-Agent": f"smtpfast-python/{__version__}",
+            "Accept": "application/json",
+            **(headers or {}),
+        }
+
+    def _build(self, http_method, route, path_params, query, body, idempotent, idempotency_key, options):
+        options = options or {}
+        max_retries = options.get("max_retries", self.max_retries)
+        timeout = options.get("timeout", self.timeout)
+        headers = httpx.Headers(self.headers)
+        headers.update(options.get("headers") or {})
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        elif idempotent and "Idempotency-Key" not in headers and max_retries > 0:
+            headers["Idempotency-Key"] = str(uuid.uuid4())
+        # A POST or PATCH is retried only when its operation dedupes on the key.
+        retryable = http_method in SAFE_METHODS or (idempotent and bool(headers.get("Idempotency-Key")))
+        params = {k: _query_value(v) for k, v in (query or {}).items() if v is not None}
+        request = httpx.Request(
+            http_method,
+            self.base_url + _fill(route, path_params),
+            params=params,
+            json=body,
+            headers=headers,
+            extensions={"timeout": httpx.Timeout(timeout).as_dict()},
+        )
+        return request, max_retries, timeout, retryable
+
+
+class SyncCore(_Core):
+    def __init__(self, *args: Any, http_client: httpx.Client | None = None) -> None:
+        super().__init__(*args)
+        self.http = http_client or httpx.Client()
+        self._owns_http = http_client is None
+
+    def request(self, http_method, route, *, path_params=None, query=None, body=None, idempotent=False, idempotency_key=None, options=None):
+        request, max_retries, timeout, retryable = self._build(http_method, route, path_params, query, body, idempotent, idempotency_key, options)
+        attempt = 0
+        while True:
+            try:
+                response = self.http.send(request)
+            except httpx.TimeoutException as err:
+                if not retryable or attempt >= max_retries:
+                    raise APITimeoutError(timeout) from err
+                time.sleep(_backoff(attempt))
+                attempt += 1
+                continue
+            except httpx.TransportError as err:
+                if not retryable or attempt >= max_retries:
+                    raise APIConnectionError() from err
+                time.sleep(_backoff(attempt))
+                attempt += 1
+                continue
+            wait = _retry_delay(response, attempt, retryable)
+            if wait is None or attempt >= max_retries:
+                response.read()
+                return _result(response)
+            response.close()
+            time.sleep(wait)
+            attempt += 1
+
+    def paginate(self, http_method, route, *, path_params=None, query=None, body=None, options=None) -> Iterator[Any]:
+        query = {k: v for k, v in (query or {}).items() if k not in PAGINATION_MANAGED}
+        while True:
+            page = self.request(http_method, route, path_params=path_params, query=query, options=options) or {}
+            items = page.get("data") or []
+            yield from items
+            last = items[-1] if items else None
+            if not page.get("has_more") or not isinstance(last, dict) or not last.get("id"):
+                return
+            query["after"] = last["id"]
+
+    def close(self) -> None:
+        if self._owns_http:
+            self.http.close()
+
+
+class AsyncCore(_Core):
+    def __init__(self, *args: Any, http_client: httpx.AsyncClient | None = None) -> None:
+        super().__init__(*args)
+        self.http = http_client or httpx.AsyncClient()
+        self._owns_http = http_client is None
+
+    async def request(self, http_method, route, *, path_params=None, query=None, body=None, idempotent=False, idempotency_key=None, options=None):
+        request, max_retries, timeout, retryable = self._build(http_method, route, path_params, query, body, idempotent, idempotency_key, options)
+        attempt = 0
+        while True:
+            try:
+                response = await self.http.send(request)
+            except httpx.TimeoutException as err:
+                if not retryable or attempt >= max_retries:
+                    raise APITimeoutError(timeout) from err
+                await asyncio.sleep(_backoff(attempt))
+                attempt += 1
+                continue
+            except httpx.TransportError as err:
+                if not retryable or attempt >= max_retries:
+                    raise APIConnectionError() from err
+                await asyncio.sleep(_backoff(attempt))
+                attempt += 1
+                continue
+            wait = _retry_delay(response, attempt, retryable)
+            if wait is None or attempt >= max_retries:
+                await response.aread()
+                return _result(response)
+            await response.aclose()
+            await asyncio.sleep(wait)
+            attempt += 1
+
+    async def paginate(self, http_method, route, *, path_params=None, query=None, body=None, options=None) -> AsyncIterator[Any]:
+        query = {k: v for k, v in (query or {}).items() if k not in PAGINATION_MANAGED}
+        while True:
+            page = await self.request(http_method, route, path_params=path_params, query=query, options=options) or {}
+            items = page.get("data") or []
+            for item in items:
+                yield item
+            last = items[-1] if items else None
+            if not page.get("has_more") or not isinstance(last, dict) or not last.get("id"):
+                return
+            query["after"] = last["id"]
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self.http.aclose()
+
+
+class _SyncResource:
+    def __init__(self, core: SyncCore) -> None:
+        self._core = core
+
+
+class _AsyncResource:
+    def __init__(self, core: AsyncCore) -> None:
+        self._core = core
+
+
+def _fill(route: str, values: Mapping[str, str] | None) -> str:
+    for name, value in (values or {}).items():
+        route = route.replace("{" + name + "}", quote(str(value), safe=""))
+    return route
+
+
+def _query_value(v: Any) -> Any:
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    return v
+
+
+def _retry_delay(response: httpx.Response, attempt: int, retryable: bool) -> float | None:
+    """Seconds to wait before retrying this response, or None for no retry."""
+    if response.status_code not in RETRY_STATUS:
+        return None
+    after = _retry_after(response.headers.get("Retry-After"))
+    if response.status_code == 429:
+        # A per-second limit sends Retry-After and rejects before any work is
+        # done, so any method may retry. Without the header (an hourly or
+        # daily limit), retrying soon cannot succeed.
+        if after is None or after > MAX_RETRY_AFTER:
+            return None
+        return after
+    if not retryable:
+        return None
+    if after is not None:
+        return after if after <= MAX_RETRY_AFTER else None
+    return _backoff(attempt)
+
+
+def _retry_after(header: str | None) -> float | None:
+    if not header:
+        return None
+    try:
+        seconds = float(header)
+        return max(seconds, 0.0) if math.isfinite(seconds) else None
+    except ValueError:
+        try:
+            parsed = email.utils.parsedate_to_datetime(header)
+        except (TypeError, ValueError):
+            return None
+        return max(float(parsed.timestamp() - time.time()), 0.0)
+
+
+def _backoff(attempt: int) -> float:
+    return float(min(0.5 * 2**attempt, 8.0)) * (0.75 + random.random() * 0.5)
+
+
+def _result(response: httpx.Response) -> Any:
+    if not 200 <= response.status_code < 300:
+        raise APIError.from_response(response)
+    if response.status_code == 204 or not response.content:
+        return None
+    try:
+        return response.json()
+    except ValueError:
+        return response.text

smtpfast/_errors.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class SMTPfastError(Exception):
+    """Every error the SDK raises is an SMTPfastError."""
+
+
+class APIError(SMTPfastError):
+    """The API answered with a status outside 2xx."""
+
+    def __init__(self, status: int, body: Any, headers: httpx.Headers) -> None:
+        self.status = status
+        self.body = body
+        self.headers = headers
+        super().__init__(_message(status, body))
+
+    @staticmethod
+    def from_response(response: httpx.Response) -> APIError:
+        try:
+            body: Any = response.json()
+        except ValueError:
+            body = response.text
+        status = response.status_code
+        kind = _BY_STATUS.get(status) or (InternalServerError if status >= 500 else APIError)
+        return kind(status, body, response.headers)
+
+
+class BadRequestError(APIError):
+    pass
+
+
+class AuthenticationError(APIError):
+    pass
+
+
+class PermissionDeniedError(APIError):
+    pass
+
+
+class NotFoundError(APIError):
+    pass
+
+
+class ConflictError(APIError):
+    pass
+
+
+class UnprocessableEntityError(APIError):
+    pass
+
+
+class RateLimitError(APIError):
+    pass
+
+
+class InternalServerError(APIError):
+    pass
+
+
+class APIConnectionError(SMTPfastError):
+    """The request did not get an answer: DNS, TLS, a reset connection."""
+
+    def __init__(self, message: str = "Could not connect to the SMTPfast API") -> None:
+        super().__init__(message)
+
+
+class APITimeoutError(APIConnectionError):
+    """No answer arrived within the timeout."""
+
+    def __init__(self, timeout: float) -> None:
+        super().__init__(f"The SMTPfast API did not answer within {timeout:g} s")
+
+
+_BY_STATUS: dict[int, type[APIError]] = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: UnprocessableEntityError,
+    429: RateLimitError,
+}
+
+
+def _message(status: int, body: Any) -> str:
+    if isinstance(body, dict) and isinstance(body.get("error"), str):
+        return f"{status}: {body['error']}"
+    if isinstance(body, str) and body.strip():
+        return f"{status}: {body.strip()[:300]}"
+    return f"{status}: the SMTPfast API answered with an error"