sendora 0.1.0__py3-none-any.whl

sendora/__init__.py

@@ -0,0 +1,52 @@
+"""The Python client for Sendora's email API.
+
+``Sendora`` and ``AsyncSendora`` take a server key; every failed call
+raises a ``SendoraError``. The request shapes and answers are in
+``sendora.types``.
+"""
+
+from ._client import AsyncSendora, Sendora
+from ._errors import (
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ResponseValidationError,
+    SendoraError,
+    UnprocessableEntityError,
+    WebhookVerificationError,
+)
+from ._options import DEFAULT_BASE_URL
+from ._transport import AsyncHttpClient, HttpClient
+from ._version import __version__
+from .types import SendoraErrorCode
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "APIConnectionError",
+    "APIStatusError",
+    "APITimeoutError",
+    "AsyncHttpClient",
+    "AsyncSendora",
+    "AuthenticationError",
+    "BadRequestError",
+    "ConflictError",
+    "HttpClient",
+    "InternalServerError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ResponseValidationError",
+    "Sendora",
+    "SendoraError",
+    "SendoraErrorCode",
+    "UnprocessableEntityError",
+    "WebhookVerificationError",
+    "__version__",
+]

sendora/_answers.py

@@ -0,0 +1,304 @@
+"""An answer's status, headers and bytes as a value or an error.
+
+Pure: the transports hand over what came back, and the same function reads
+it for the regular and the async clients.
+"""
+
+import json
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Literal, TypeVar, cast
+
+from ._errors import (
+    APIStatusError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ResponseValidationError,
+    SendoraError,
+    UnprocessableEntityError,
+)
+from ._json import is_list, is_object
+from ._model import Answer
+from ._wire import decode
+from .types import (
+    LimitScope,
+    SendoraErrorCode,
+    SuppressedRecipient,
+    ValidationIssue,
+)
+
+_A = TypeVar("_A", bound=Answer)
+
+Expect = Literal["json", "bytes", "none"]
+"""What a call answers when it succeeds: parsed JSON, the bytes, or nothing."""
+
+
+@dataclass(frozen=True, slots=True)
+class Reply:
+    """What came back for one attempt.
+
+    Attributes:
+        status: The HTTP status.
+        headers: The headers, names lower-cased.
+        content: The body's bytes.
+    """
+
+    status: int
+    headers: Mapping[str, str]
+    content: bytes
+
+
+def interpret(reply: Reply, expect: Expect, base_url: str) -> object:
+    """The value a reply amounts to, or the error it is.
+
+    Args:
+        reply: What came back.
+        expect: What the call answers when it succeeds.
+        base_url: The API's address, named when a redirect answers.
+
+    Returns:
+        Parsed JSON, the bytes, or ``None``.
+
+    Raises:
+        SendoraError: The reply is a refusal, a redirect, or unreadable.
+    """
+    status = reply.status
+    if status == 204:  # noqa: PLR2004
+        return None
+    if 200 <= status < 300:  # noqa: PLR2004
+        if expect == "bytes":
+            return reply.content
+        if expect == "none":
+            return None
+        parsed = _parsed(reply.content)
+        if parsed is _NOTHING:
+            msg = (
+                f"The API answered {status} without a JSON body; the call took effect."
+            )
+            raise ResponseValidationError(
+                msg, code="unexpected_response", status=status
+            )
+        return parsed
+    if 300 <= status < 400:  # noqa: PLR2004
+        msg = f"The API answered a redirect; check base_url ({base_url})."
+        raise APIStatusError(msg, code="unexpected_response", status=status)
+    raise error_from_answer(
+        status, _parsed(reply.content), reply.headers.get("retry-after")
+    )
+
+
+def decode_sent(cls: type[_A], value: object, idempotency_key: str | None) -> _A:
+    """A send's answer decoded, its idempotency key on the error if it cannot be.
+
+    The API accepted the send, so a caller repeating it under the same key
+    gets the first answer back rather than a second message.
+
+    Args:
+        cls: The answer's class.
+        value: The parsed JSON.
+        idempotency_key: The key the send went under, which an error carries.
+
+    Returns:
+        The answer.
+
+    Raises:
+        ResponseValidationError: The answer is not one this release reads.
+    """
+    try:
+        return decode(cls, value)
+    except ResponseValidationError as error:
+        error.idempotency_key = idempotency_key
+        raise
+
+
+_NOTHING = object()
+
+# The API's codes are snake_case; anything else, such as the reason phrase a
+# framework's own error body carries, is not one.
+_API_CODE = re.compile(r"[a-z][a-z0-9_]*")
+
+# The API, in JavaScript, sends no whole number above 2**53 - 1 exactly; a
+# longer one is refused rather than read into a wait no sleep can take.
+_DIGITS = re.compile(r"[0-9]{1,16}")
+_LARGEST = 2**53 - 1
+
+
+def _parsed(content: bytes) -> object:
+    try:
+        parsed: object = json.loads(content)
+    except ValueError:
+        return _NOTHING
+    return parsed
+
+
+def error_from_answer(
+    status: int, body: object, retry_after: str | None
+) -> SendoraError:
+    """The error a refusal amounts to, of the class its status names.
+
+    An answer that is not the API's JSON is ``unexpected_response``, but for
+    the edge's own plain-text 429 and 413, which Traefik answers before the
+    API sees the request.
+
+    Args:
+        status: The HTTP status.
+        body: The parsed JSON, or anything else that came.
+        retry_after: The ``Retry-After`` header.
+
+    Returns:
+        The error, every field the answer carries filled.
+    """
+    kind = _class_for(status)
+    if not is_object(body):
+        if status == 429:  # noqa: PLR2004
+            msg = (
+                "Too many requests reached Sendora at once; its edge refused this one."
+            )
+            return kind(
+                msg, code="rate_limited", status=status, retry_after=_whole(retry_after)
+            )
+        if status == 413:  # noqa: PLR2004
+            msg = (
+                "The request body is larger than Sendora accepts; its edge refused it."
+            )
+            return kind(
+                msg,
+                code="request_too_large",
+                status=status,
+                retry_after=_whole(retry_after),
+            )
+        msg = f"The API answered {status} without an error body."
+        return kind(
+            msg,
+            code="unexpected_response",
+            status=status,
+            retry_after=_whole(retry_after),
+        )
+    answer = body
+    raw = answer.get("error")
+    code = (
+        _code(raw)
+        if isinstance(raw, str) and _API_CODE.fullmatch(raw)
+        else "unexpected_response"
+    )
+    issues = _readable(ValidationIssue, answer.get("issues"))
+    message = answer.get("message")
+    if not isinstance(message, str):
+        message = (
+            "The request is invalid: "
+            + "; ".join(f"{issue.path}: {issue.message}" for issue in issues)
+            if code == "invalid_request"
+            else f"The API answered {status} without an error message."
+        )
+    return kind(
+        message,
+        code=code,
+        status=status,
+        retry_after=_either(_whole(answer.get("retryAfter")), _whole(retry_after)),
+        scope=_scope(answer.get("scope")),
+        limit=_whole(answer.get("limit")),
+        cap=_whole(answer.get("cap")),
+        used=_whole(answer.get("used")),
+        resets_at=_time(answer.get("resetsAt")),
+        max=_either(_whole(answer.get("max")), _whole(answer.get("maxServers"))),
+        issues=issues,
+        suppressed=_readable(SuppressedRecipient, answer.get("suppressed")),
+        stream_id=_text(answer.get("streamId"))
+        if code == "recipient_suppressed"
+        else None,
+        addresses=_texts(answer.get("addresses")),
+        existing_id=_existing_id(code, answer),
+        index=_whole(answer.get("index")) if code == "substitution_missing" else None,
+        keys=_texts(answer.get("keys")) if code == "substitution_missing" else [],
+    )
+
+
+def _class_for(status: int) -> type[APIStatusError]:
+    if status >= 500:  # noqa: PLR2004
+        return InternalServerError
+    by_status: dict[int, type[APIStatusError]] = {
+        400: BadRequestError,
+        401: AuthenticationError,
+        403: PermissionDeniedError,
+        404: NotFoundError,
+        409: ConflictError,
+        422: UnprocessableEntityError,
+        429: RateLimitError,
+    }
+    return by_status.get(status, APIStatusError)
+
+
+def _code(raw: str) -> SendoraErrorCode:
+    # A cast does nothing at run time, so no mutant of it can fail a test.
+    return cast("SendoraErrorCode", raw)  # pragma: no mutate
+
+
+_EXISTING_IDS = {
+    "domain_exists": "domainId",
+    "webhook_exists": "webhookId",
+    "stream_exists": "streamId",
+    "inbound_stream_exists": "streamId",
+    "inbound_domain_exists": "inboundDomainId",
+}
+
+
+def _existing_id(code: str, answer: Mapping[str, object]) -> str | None:
+    if code not in _EXISTING_IDS:
+        return None
+    return _text(answer.get(_EXISTING_IDS[code]))
+
+
+def _either(first: int | None, second: int | None) -> int | None:
+    return second if first is None else first
+
+
+def _whole(value: object) -> int | None:
+    if isinstance(value, str) and _DIGITS.fullmatch(value):
+        value = int(value)
+    if type(value) is int and 0 <= value <= _LARGEST:
+        return value
+    return None
+
+
+def _text(value: object) -> str | None:
+    return value if isinstance(value, str) else None
+
+
+def _texts(value: object) -> list[str]:
+    if not is_list(value):
+        return []
+    return [member for member in value if isinstance(member, str)]
+
+
+def _time(value: object) -> datetime | None:
+    if not isinstance(value, str):
+        return None
+    try:
+        return datetime.fromisoformat(value)
+    except ValueError:
+        return None
+
+
+def _scope(value: object) -> LimitScope | None:
+    scopes: tuple[LimitScope, ...] = ("tenant", "server", "test")
+    return next((scope for scope in scopes if scope == value), None)
+
+
+def _readable(cls: type[_A], value: object) -> list[_A]:
+    """The entries of a list the SDK can read as ``cls``; the rest are left out."""
+    if not is_list(value):
+        return []
+    found: list[_A] = []
+    for entry in value:
+        try:
+            found.append(decode(cls, entry))
+        except ResponseValidationError:
+            continue
+    return found

sendora/_client.py

@@ -0,0 +1,234 @@
+"""The clients for a server key: ``Sendora`` and ``AsyncSendora``."""
+
+from types import TracebackType
+from typing import Self
+
+from ._options import DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, options_for
+from ._transport import AsyncHttpClient, AsyncTransport, HttpClient, SyncTransport
+from .resources.email import AsyncEmail, Email
+from .resources.messages import AsyncMessages, Messages
+
+_SERVER_KEY = "SENDORA_API_TOKEN"
+
+
+class Sendora:
+    """The client for a server key (``sk_…``): everything inside one server.
+
+    One client per process is the intended use; it is safe across threads
+    and reuses its connections. Close it, or use it as a context manager.
+
+    Attributes:
+        email: Sends mail, one message or a batch.
+        messages: Reads the message log.
+
+    Example:
+        >>> with Sendora() as sendora:  # the key from SENDORA_API_TOKEN
+        ...     sent = sendora.email.send(
+        ...         from_="notices@example.se",
+        ...         to=["anna@example.com"],
+        ...         subject="Your order",
+        ...         text="Thank you for your order.",
+        ...     )
+    """
+
+    def __init__(
+        self,
+        token: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: HttpClient | None = None,
+    ) -> None:
+        """Makes the client; nothing is sent until a call.
+
+        Args:
+            token: The server key; ``SENDORA_API_TOKEN`` when not given.
+            base_url: The API's address; ``SENDORA_BASE_URL``, then
+                https://api.sendora.se, when not given.
+            timeout: Seconds each step of a request may take: connecting,
+                sending, waiting for the answer.
+            max_retries: How many times a failed call is repeated when
+                repeating is safe; 0 turns retries off.
+            http_client: Your own ``httpx2.Client``, for a proxy or a
+                private CA. Its connections, proxy and certificates are
+                used, not its default headers, query or cookies; the SDK
+                never closes it.
+
+        Raises:
+            ValueError: A setting is missing or out of range.
+            TypeError: ``http_client`` is not an ``httpx2.Client``.
+        """
+        try:
+            transport = SyncTransport(
+                options_for(
+                    token,
+                    base_url=base_url,
+                    timeout=timeout,
+                    max_retries=max_retries,
+                    variable=_SERVER_KEY,
+                ),
+                http_client,
+            )
+        except (ValueError, TypeError) as refused:
+            # An error tracker keeps the locals of each frame it is handed,
+            # so the frames that held the key are dropped, and this one's.
+            del token
+            raise refused.with_traceback(None) from None
+        self._attach(transport)
+
+    def _attach(self, transport: SyncTransport) -> None:
+        self._transport = transport
+        self.email: Email = Email(transport)
+        self.messages: Messages = Messages(transport)
+
+    def with_options(
+        self, *, timeout: float | None = None, max_retries: int | None = None
+    ) -> Self:
+        """A client with another timeout or retry count, sharing these connections.
+
+        Args:
+            timeout: Seconds each step of a request may take.
+            max_retries: How many times a failed call is repeated.
+
+        Returns:
+            The new client. It sends over this client's connections, which
+            close with this client alone: close this one when both are done.
+        """
+        transport = self._transport.with_options(
+            timeout=timeout, max_retries=max_retries
+        )
+        changed = object.__new__(type(self))
+        changed._attach(transport)  # noqa: SLF001 - a client of this class, new here
+        return changed
+
+    def close(self) -> None:
+        """Closes the client's connections, unless they are a caller's own."""
+        self._transport.close()
+
+    def __enter__(self) -> Self:
+        """Answers the client itself."""
+        return self
+
+    def __exit__(
+        self,
+        kind: type[BaseException] | None,
+        error: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Closes the client."""
+        self.close()
+
+    def __repr__(self) -> str:
+        """Names the address, never the key."""
+        return f"{type(self).__name__}(base_url={self._transport.options.base_url!r})"
+
+
+class AsyncSendora:
+    """The async client for a server key (``sk_…``), under asyncio.
+
+    Attributes:
+        email: Sends mail, one message or a batch.
+        messages: Reads the message log.
+
+    Example:
+        >>> async with AsyncSendora() as sendora:
+        ...     sent = await sendora.email.send(
+        ...         from_="notices@example.se",
+        ...         to=["anna@example.com"],
+        ...         subject="Your order",
+        ...         text="Thank you for your order.",
+        ...     )
+    """
+
+    def __init__(
+        self,
+        token: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: AsyncHttpClient | None = None,
+    ) -> None:
+        """Makes the client; nothing is sent until a call.
+
+        Args:
+            token: The server key; ``SENDORA_API_TOKEN`` when not given.
+            base_url: The API's address; ``SENDORA_BASE_URL``, then
+                https://api.sendora.se, when not given.
+            timeout: Seconds each step of a request may take: connecting,
+                sending, waiting for the answer.
+            max_retries: How many times a failed call is repeated when
+                repeating is safe; 0 turns retries off.
+            http_client: Your own ``httpx2.AsyncClient``, for a proxy or a
+                private CA. Its connections, proxy and certificates are
+                used, not its default headers, query or cookies; the SDK
+                never closes it.
+
+        Raises:
+            ValueError: A setting is missing or out of range.
+            TypeError: ``http_client`` is not an ``httpx2.AsyncClient``.
+        """
+        try:
+            transport = AsyncTransport(
+                options_for(
+                    token,
+                    base_url=base_url,
+                    timeout=timeout,
+                    max_retries=max_retries,
+                    variable=_SERVER_KEY,
+                ),
+                http_client,
+            )
+        except (ValueError, TypeError) as refused:
+            # An error tracker keeps the locals of each frame it is handed,
+            # so the frames that held the key are dropped, and this one's.
+            del token
+            raise refused.with_traceback(None) from None
+        self._attach(transport)
+
+    def _attach(self, transport: AsyncTransport) -> None:
+        self._transport = transport
+        self.email: AsyncEmail = AsyncEmail(transport)
+        self.messages: AsyncMessages = AsyncMessages(transport)
+
+    def with_options(
+        self, *, timeout: float | None = None, max_retries: int | None = None
+    ) -> Self:
+        """A client with another timeout or retry count, sharing these connections.
+
+        Args:
+            timeout: Seconds each step of a request may take.
+            max_retries: How many times a failed call is repeated.
+
+        Returns:
+            The new client. It sends over this client's connections, which
+            close with this client alone: close this one when both are done.
+        """
+        transport = self._transport.with_options(
+            timeout=timeout, max_retries=max_retries
+        )
+        changed = object.__new__(type(self))
+        changed._attach(transport)  # noqa: SLF001 - a client of this class, new here
+        return changed
+
+    async def close(self) -> None:
+        """Closes the client's connections, unless they are a caller's own."""
+        await self._transport.close()
+
+    async def __aenter__(self) -> Self:
+        """Answers the client itself."""
+        return self
+
+    async def __aexit__(
+        self,
+        kind: type[BaseException] | None,
+        error: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Closes the client."""
+        await self.close()
+
+    def __repr__(self) -> str:
+        """Names the address, never the key."""
+        return f"{type(self).__name__}(base_url={self._transport.options.base_url!r})"