benethos-mailbox-client 0.3.0__py3-none-any.whl

benethos_mailbox_client/__init__.py

@@ -0,0 +1,62 @@
+"""mailbox-client, the Python client of the REST API of mailbox-service.
+
+``MailboxClient`` is for async code, ``SyncMailboxClient`` for code
+without an event loop. Both send the same requests and answer the same
+records."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .client import MailboxClient
+from .endpoints import message_body
+from .environment import Environment, from_environment
+from .errors import (
+    ApiError,
+    ConfigurationError,
+    MailboxError,
+    ServiceTimeoutError,
+    ServiceUnavailableError,
+)
+from .models import (
+    Attachment,
+    Changes,
+    Folder,
+    Me,
+    MeAccount,
+    Outcome,
+    Page,
+    Recipient,
+    Sending,
+    Sent,
+)
+from .sync import SyncMailboxClient
+
+try:
+    __version__ = version("benethos-mailbox-client")
+except PackageNotFoundError:  # pragma: no cover - running from a bare tree
+    __version__ = "0.0.0"
+
+__all__ = [
+    "ApiError",
+    "Attachment",
+    "Changes",
+    "ConfigurationError",
+    "Environment",
+    "Folder",
+    "MailboxClient",
+    "MailboxError",
+    "Me",
+    "MeAccount",
+    "Outcome",
+    "Page",
+    "Recipient",
+    "Sending",
+    "Sent",
+    "ServiceTimeoutError",
+    "ServiceUnavailableError",
+    "SyncMailboxClient",
+    "__version__",
+    "from_environment",
+    "message_body",
+]

benethos_mailbox_client/answers.py

@@ -0,0 +1,85 @@
+"""How an answer of the API, or a failure on the way to it, is read: the
+JSON of an answer, the error envelope as an ``ApiError``, a service that
+cannot be reached or does not answer in time. The same for both
+clients."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .calls import Call, T
+from .errors import ApiError, MailboxError, ServiceTimeoutError, ServiceUnavailableError
+
+
+def answer(response: httpx.Response) -> Any:
+    """The JSON of a read answer, None for no content. Raises ``ApiError``
+    for an error and for an answer that is not JSON."""
+    if response.is_error:
+        raise api_error(response)
+    if response.status_code == 204:
+        return None
+    try:
+        return response.json()
+    except ValueError:
+        raise ApiError(
+            response.status_code, "unexpected_response", "the answer is not JSON"
+        ) from None
+
+
+def read(call: Call[T], response: httpx.Response) -> T:
+    """What the caller gets of ``response``. An answer of another shape
+    than the API describes, such as one without a field the call reads, is
+    an ``ApiError`` too, not an error deep inside the reading."""
+    found = answer(response)
+    try:
+        return call.read(found)
+    except (KeyError, TypeError, ValueError, AttributeError):
+        raise ApiError(
+            response.status_code,
+            "unexpected_response",
+            "the answer is not what the API describes",
+        ) from None
+
+
+def api_error(response: httpx.Response) -> ApiError:
+    """The error envelope as an ApiError. A validation failure (422) has no
+    envelope but a list of what was wrong where, which is what a caller
+    needs to correct the call."""
+    try:
+        body = response.json()
+    except ValueError:
+        body = None
+    if isinstance(body, dict) and isinstance(body.get("error"), dict):
+        error = body["error"]
+        if "code" in error and "message" in error:
+            code, message = str(error["code"]), str(error["message"])
+            return ApiError(response.status_code, code, message)
+    if isinstance(body, dict) and isinstance(body.get("detail"), list):
+        reasons = [
+            f"{'.'.join(str(p) for p in item.get('loc', ()) if p != 'body')}: "
+            f"{item.get('msg', '')}"
+            for item in body["detail"]
+            if isinstance(item, dict)
+        ]
+        if reasons:
+            reason = "; ".join(reasons)
+            return ApiError(response.status_code, "validation_error", reason)
+    return ApiError(response.status_code, "unexpected_response", response.reason_phrase)
+
+
+def failure(exc: httpx.TransportError, base_url: str, seconds: float) -> MailboxError:
+    """What went wrong on the way: a service that answers too slowly is
+    running, one that cannot be reached is not."""
+    if isinstance(exc, httpx.TimeoutException) and not isinstance(
+        exc, httpx.ConnectTimeout
+    ):
+        return ServiceTimeoutError(
+            f"mailbox-service did not answer within {seconds:g} s. "
+            "Try a narrower request."
+        )
+    return ServiceUnavailableError(
+        f"mailbox-service is not reachable at {base_url}. "
+        "Start it with `benethos-mailbox-service serve`."
+    )

benethos_mailbox_client/attachments.py

@@ -0,0 +1,71 @@
+"""An attachment's bytes, read in chunks up to the caller's limit, and
+what the answer's headers say of it: its type, its charset and its file
+name. Both clients collect the chunks here, each in its own way."""
+
+from __future__ import annotations
+
+import codecs
+import re
+from urllib.parse import unquote
+
+import httpx
+
+from .models import Attachment
+
+
+class Collected:
+    """The bytes of an answer read in chunks, up to a limit. ``add``
+    answers False once the limit is passed: reading stops there."""
+
+    def __init__(self, max_bytes: int) -> None:
+        self.max_bytes = max_bytes
+        self.chunks: list[bytes] = []
+        self.read = 0
+        self.complete = True
+
+    def add(self, chunk: bytes) -> bool:
+        self.chunks.append(chunk)
+        self.read += len(chunk)
+        if self.read > self.max_bytes:
+            self.complete = False
+        return self.complete
+
+
+def attachment(headers: httpx.Headers, collected: Collected) -> Attachment:
+    """The attachment the headers describe, with the bytes read of it."""
+    media, _, options = headers.get(
+        "content-type", "application/octet-stream"
+    ).partition(";")
+    charset = re.search(r"charset=\"?([\w.:-]+)", options)
+    name = re.search(
+        r"filename\*=UTF-8''([^;]+)", headers.get("content-disposition", "")
+    )
+    return Attachment(
+        data=b"".join(collected.chunks)[: collected.max_bytes],
+        content_type=_media_type(media),
+        charset=_known_charset(charset.group(1)) if charset else None,
+        filename=unquote(name.group(1)) if name else None,
+        complete=collected.complete,
+    )
+
+
+# A media type, type/subtype in the characters RFC 6838 allows. The sender
+# of a mail chose it, and a caller may show it.
+_MEDIA_TYPE = re.compile(r"[a-z0-9][a-z0-9!#$&^_.+-]*/[a-z0-9][a-z0-9!#$&^_.+-]*")
+
+
+def _media_type(value: str) -> str:
+    """``value`` when it is a media type and nothing else, else the type of
+    unknown bytes."""
+    media = value.strip().lower()
+    if len(media) <= 127 and _MEDIA_TYPE.fullmatch(media):
+        return media
+    return "application/octet-stream"
+
+
+def _known_charset(name: str) -> str | None:
+    try:
+        codecs.lookup(name)
+    except LookupError:
+        return None
+    return name

benethos_mailbox_client/calls.py

@@ -0,0 +1,64 @@
+"""The request a call makes, described without sending it: its method,
+its path below ``/v1``, its parameters and body, how long to wait, and
+how its answer becomes what the caller gets. ``client`` and ``sync``
+send a ``Call``, each in its own way."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, Generic, TypeVar
+from urllib.parse import quote
+
+import httpx
+
+# Seconds to wait: for the service to take the connection, for an answer,
+# and for an attachment, which may be large.
+CONNECT_TIMEOUT = 5.0
+TIMEOUT = 30.0
+ATTACHMENT_TIMEOUT = 120.0
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class Call(Generic[T]):
+    """One request to the API, and how its answer becomes what the caller
+    gets. ``read`` takes the JSON of the answer, None for no content."""
+
+    method: str
+    path: str
+    read: Callable[[Any], T]
+    params: dict[str, Any] = field(default_factory=dict)
+    json: dict[str, Any] | None = None
+    headers: dict[str, str] = field(default_factory=dict)
+    timeout: float = TIMEOUT
+
+    @property
+    def timeouts(self) -> httpx.Timeout:
+        return timeouts(self.timeout)
+
+
+def timeouts(seconds: float = TIMEOUT) -> httpx.Timeout:
+    """How long to wait for the connection, and then for the answer."""
+    return httpx.Timeout(seconds, connect=CONNECT_TIMEOUT)
+
+
+def given(values: Mapping[str, Any] | None) -> dict[str, Any]:
+    """Without the entries that are None: those stay out of a request."""
+    return {k: v for k, v in (values or {}).items() if v is not None}
+
+
+def path(*parts: str) -> str:
+    """A path below ``/v1``, each part quoted: an id may come from anyone."""
+    return "/v1/" + "/".join(quote(part, safe="") for part in parts)
+
+
+def as_is(found: Any) -> Any:
+    """The reading of a call whose answer is passed on as it comes."""
+    return found
+
+
+def nothing(found: Any) -> None:
+    """The reading of a call whose answer has no content."""
+    return None

benethos_mailbox_client/client.py

@@ -0,0 +1,242 @@
+"""``MailboxClient``, the client for async code: it sends the calls of
+``endpoints`` with ``httpx.AsyncClient``. Each method is one line, what
+it asks and what it answers is described in ``endpoints``."""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Any, TypeVar
+
+import httpx
+
+from . import endpoints
+from .answers import api_error, failure, read
+from .attachments import Collected, attachment
+from .calls import Call, timeouts
+from .environment import connection
+from .models import Attachment, Changes, Folder, Me, Outcome, Page, Sent
+
+T = TypeVar("T")
+
+
+class MailboxClient:
+    """The REST API of mailbox-service, for async code.
+
+    ``base_url`` defaults to ``MAILBOX_SERVICE_URL``, ``token`` to
+    ``MAILBOX_SERVICE_TOKEN``. Raises ``ConfigurationError`` without a
+    token, and for http to another machine unless ``allow_http`` (else
+    ``MAILBOX_SERVICE_ALLOW_HTTP``) allows it. ``transport`` is for tests,
+    e.g. ``httpx.MockTransport``."""
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        token: str | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+        allow_http: bool | None = None,
+    ) -> None:
+        found = connection(base_url, token, allow_http)
+        self.base_url = found.base_url
+        self._http = httpx.AsyncClient(
+            base_url=found.base_url,
+            headers=found.headers,
+            timeout=timeouts(),
+            transport=transport,
+        )
+
+    async def __aenter__(self) -> MailboxClient:
+        return self
+
+    async def __aexit__(
+        self,
+        kind: type[BaseException] | None,
+        error: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def send(self, call: Call[T]) -> T:
+        """Send ``call`` and read its answer."""
+        try:
+            response = await self._http.request(
+                call.method,
+                call.path,
+                params=call.params,
+                json=call.json,
+                headers=call.headers,
+                timeout=call.timeouts,
+            )
+        except httpx.TransportError as exc:
+            raise failure(exc, self.base_url, call.timeout) from None
+        return read(call, response)
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Any:
+        """Any request: the JSON the API answers, None for no content.
+        Parameters and fields that are None are left out."""
+        call = endpoints.request(
+            method, path, params=params, json=json, headers=headers
+        )
+        return await self.send(call)
+
+    # --- the caller and the accounts --------------------------------------------------
+
+    async def me(self) -> Me:
+        return await self.send(endpoints.me())
+
+    # --- folders ----------------------------------------------------------------------
+
+    async def list_folders(self, account_id: str) -> list[Folder]:
+        return await self.send(endpoints.list_folders(account_id))
+
+    async def create_folder(
+        self, account_id: str, name: str, parent_id: str | None
+    ) -> Folder:
+        return await self.send(endpoints.create_folder(account_id, name, parent_id))
+
+    # --- messages ---------------------------------------------------------------------
+
+    async def list_messages(
+        self,
+        account_id: str | None,
+        *,
+        folder: str | None = None,
+        text: str | None = None,
+        sender: str | None = None,
+        to: str | None = None,
+        subject: str | None = None,
+        after: str | None = None,
+        before: str | None = None,
+        unread: bool | None = None,
+        starred: bool | None = None,
+        has_attachments: bool | None = None,
+        limit: int,
+        cursor: str | None = None,
+    ) -> Page:
+        return await self.send(
+            endpoints.list_messages(
+                account_id,
+                folder=folder,
+                text=text,
+                sender=sender,
+                to=to,
+                subject=subject,
+                after=after,
+                before=before,
+                unread=unread,
+                starred=starred,
+                has_attachments=has_attachments,
+                limit=limit,
+                cursor=cursor,
+            )
+        )
+
+    async def list_changes(
+        self, account_id: str | None, *, since: str | None, limit: int
+    ) -> Changes:
+        return await self.send(
+            endpoints.list_changes(account_id, since=since, limit=limit)
+        )
+
+    async def get_message(self, account_id: str, message_id: str) -> dict[str, Any]:
+        return await self.send(endpoints.get_message(account_id, message_id))
+
+    async def get_attachment(
+        self, account_id: str, message_id: str, attachment_id: str, max_bytes: int
+    ) -> Attachment:
+        """The attachment's bytes up to ``max_bytes``, with its type, charset
+        and file name. Reading stops where the limit is passed."""
+        call = endpoints.get_attachment(account_id, message_id, attachment_id)
+        collected = Collected(max_bytes)
+        try:
+            async with self._http.stream(
+                call.method, call.path, timeout=call.timeouts
+            ) as response:
+                if response.is_error:
+                    await response.aread()
+                    raise api_error(response)
+                async for chunk in response.aiter_bytes():
+                    if not collected.add(chunk):
+                        break
+        except httpx.TransportError as exc:
+            raise failure(exc, self.base_url, call.timeout) from None
+        return attachment(response.headers, collected)
+
+    async def update_messages(
+        self,
+        account_id: str,
+        message_ids: list[str],
+        *,
+        unread: bool | None = None,
+        starred: bool | None = None,
+        folder_id: str | None = None,
+    ) -> Outcome:
+        return await self.send(
+            endpoints.update_messages(
+                account_id,
+                message_ids,
+                unread=unread,
+                starred=starred,
+                folder_id=folder_id,
+            )
+        )
+
+    async def delete_message(
+        self, account_id: str, message_id: str, *, permanent: bool = False
+    ) -> None:
+        await self.send(
+            endpoints.delete_message(account_id, message_id, permanent=permanent)
+        )
+
+    async def trash_messages(self, account_id: str, message_ids: list[str]) -> Outcome:
+        return await self.send(endpoints.trash_messages(account_id, message_ids))
+
+    # --- drafts and sending -----------------------------------------------------------
+
+    async def list_drafts(
+        self, account_id: str, limit: int, cursor: str | None = None
+    ) -> Page:
+        return await self.send(endpoints.list_drafts(account_id, limit, cursor))
+
+    async def create_draft(
+        self, account_id: str, message: dict[str, Any]
+    ) -> dict[str, Any]:
+        return await self.send(endpoints.create_draft(account_id, message))
+
+    async def update_draft(
+        self,
+        account_id: str,
+        draft_id: str,
+        message: dict[str, Any],
+        keep_attachments: list[str] | None = None,
+    ) -> dict[str, Any]:
+        return await self.send(
+            endpoints.update_draft(account_id, draft_id, message, keep_attachments)
+        )
+
+    async def delete_draft(self, account_id: str, draft_id: str) -> None:
+        await self.send(endpoints.delete_draft(account_id, draft_id))
+
+    async def send_message(
+        self, account_id: str, message: dict[str, Any], idempotency_key: str
+    ) -> Sent:
+        return await self.send(
+            endpoints.send_message(account_id, message, idempotency_key)
+        )
+
+    async def send_draft(
+        self, account_id: str, draft_id: str, idempotency_key: str
+    ) -> Sent:
+        return await self.send(
+            endpoints.send_draft(account_id, draft_id, idempotency_key)
+        )

benethos_mailbox_client/endpoints/__init__.py

@@ -0,0 +1,47 @@
+"""Each endpoint of the API the client knows, described once: the
+request it makes and how its answer becomes a record of ``models``, one
+module per resource of the API.
+
+A function here sends nothing. It answers a ``Call``, which ``client``
+and ``sync`` send. Nothing above this package spells out a path, a query
+name or a field of the API.
+"""
+
+from __future__ import annotations
+
+from .accounts import me
+from .compose import message_body
+from .drafts import create_draft, delete_draft, list_drafts, update_draft
+from .folders import create_folder, list_folders
+from .generic import request
+from .messages import (
+    delete_message,
+    get_attachment,
+    get_message,
+    list_changes,
+    list_messages,
+    trash_messages,
+    update_messages,
+)
+from .sending import send_draft, send_message
+
+__all__ = [
+    "create_draft",
+    "create_folder",
+    "delete_draft",
+    "delete_message",
+    "get_attachment",
+    "get_message",
+    "list_changes",
+    "list_drafts",
+    "list_folders",
+    "list_messages",
+    "me",
+    "message_body",
+    "request",
+    "send_draft",
+    "send_message",
+    "trash_messages",
+    "update_draft",
+    "update_messages",
+]

benethos_mailbox_client/endpoints/accounts.py

@@ -0,0 +1,42 @@
+"""The caller and its accounts: ``/v1/me``, which every token may ask,
+read into ``Me``."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..calls import Call, path
+from ..models import Me, MeAccount, Sending
+
+
+def me() -> Call[Me]:
+    return Call("GET", path("me"), _me)
+
+
+def _me(found: dict[str, Any]) -> Me:
+    return Me(
+        accounts=[
+            MeAccount(
+                id=str(a["id"]),
+                email=str(a["email"]),
+                display_name=a.get("display_name"),
+                operations=frozenset(a.get("operations", [])),
+                warnings=frozenset(a.get("warnings", [])),
+                sending=tuple(_sending(s) for s in a.get("sending", [])),
+                capabilities=(
+                    frozenset(a["capabilities"]) if "capabilities" in a else None
+                ),
+            )
+            for a in found.get("accounts", [])
+        ],
+        operations=frozenset(found.get("operations", [])),
+    )
+
+
+def _sending(item: dict[str, Any]) -> Sending:
+    recipients = item.get("recipients")
+    return Sending(
+        recipients=tuple(recipients) if recipients is not None else None,
+        max_per_day=item.get("max_sends_per_day"),
+        left=item.get("sends_left"),
+    )

benethos_mailbox_client/endpoints/compose.py

@@ -0,0 +1,40 @@
+"""What drafts and sending share: the body of a message as the API
+takes it, made from recipients, a subject, a text and a reference."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..models import Recipient
+
+
+def message_body(
+    *,
+    to: list[Recipient],
+    cc: list[Recipient],
+    bcc: list[Recipient],
+    subject: str,
+    text: str,
+    html: str | None,
+    reference: tuple[str, str] | None,
+) -> dict[str, Any]:
+    """The body of a draft or a message to send, as the API takes it.
+    ``reference``: the id of the message answered or forwarded, and the
+    action (reply, reply_all, forward)."""
+    body: dict[str, Any] = {
+        "to": [_recipient(r) for r in to],
+        "cc": [_recipient(r) for r in cc],
+        "bcc": [_recipient(r) for r in bcc],
+        "subject": subject,
+        "text": text,
+    }
+    if html is not None:
+        body["html"] = html
+    if reference is not None:
+        body["reference"] = {"message_id": reference[0], "action": reference[1]}
+    return body
+
+
+def _recipient(recipient: Recipient) -> dict[str, str]:
+    email, name = recipient
+    return {"email": email, "name": name} if name else {"email": email}