benethos-mailbox-client 0.3.0__tar.gz

benethos_mailbox_client-0.3.0/.gitignore

@@ -0,0 +1,62 @@
+# Virtual environment
+.venv/
+venv/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Caching / coverage
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.cache/
+*.sqlite
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# IDE / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Local configuration and secrets
+.env
+# config/: per package, only the templates are versioned
+config/**
+!config/**/
+!config/*/.env.example
+*.token.json
+# containers/*/secrets/: the master key of a deployment, the passwords
+# and the CA of the test mail server
+containers/**/secrets/
+# containers/production/service.env: settings, among them perhaps a secret
+containers/**/service.env
+# containers/production/: the MCP server instances and their routes in Caddy
+containers/production/compose.override.yaml
+containers/production/caddy.d/*.caddy
+
+# Service data: the database holds encrypted credentials, backups the same.
+# data/: per package, only the folders are versioned (.gitkeep)
+data/**
+!data/**/
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
+**/backups/**
+!**/backups/**/
+
+# Live checks: test server address and test accounts stay local
+live/.env
+
+# .gitkeep holds an empty folder and is kept wherever it is. Only works
+# below folders ignored file by file (as above), not below an ignored folder.
+!.gitkeep

benethos_mailbox_client-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benedikt Oswald
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

benethos_mailbox_client-0.3.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.5
+Name: benethos-mailbox-client
+Version: 0.3.0
+Summary: Python client of the REST API of mailbox-service: the mail of all your mailboxes (IMAP, JMAP, POP3, Microsoft 365, Outlook.com) through one API, async and sync.
+Project-URL: Homepage, https://github.com/benethos-hub/mailbox/tree/main/packages/mailbox-client#readme
+Project-URL: Repository, https://github.com/benethos-hub/mailbox
+Project-URL: Issues, https://github.com/benethos-hub/mailbox/issues
+Project-URL: Changelog, https://github.com/benethos-hub/mailbox/blob/main/CHANGELOG.md
+Author: Benedikt Oswald
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,email,email-automation,imap,jmap,microsoft-365,multi-account,outlook,pop3,rest-client,self-hosted
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Email
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28
+Description-Content-Type: text/markdown
+
+# mailbox-client
+
+[![CI](https://github.com/benethos-hub/mailbox/actions/workflows/ci.yml/badge.svg)](https://github.com/benethos-hub/mailbox/actions/workflows/ci.yml)
+[![PyPI benethos-mailbox-client](https://img.shields.io/pypi/v/benethos-mailbox-client?label=PyPI%20benethos-mailbox-client)](https://pypi.org/project/benethos-mailbox-client/)
+[![Python](https://img.shields.io/pypi/pyversions/benethos-mailbox-client)](https://pypi.org/project/benethos-mailbox-client/)
+[![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/benethos-hub/mailbox/blob/main/LICENSE)
+
+> **Beta, version 0.3.0.** Usable with real accounts. A breaking change
+> of the API or the configuration is announced in the changelog. Stored
+> data is carried forward by migrations.
+
+The Python client of the REST API of
+[`mailbox-service`](https://github.com/benethos-hub/mailbox/tree/main/packages/mailbox-service),
+on PyPI as `benethos-mailbox-client`. It reads, searches, sorts, drafts
+and sends mail of the accounts the service holds, as far as its token
+allows. The MCP server of the project,
+[`mailbox-mcp`](https://github.com/benethos-hub/mailbox/tree/main/packages/mailbox-mcp),
+is built on it.
+
+It knows the service through its REST API alone, and needs nothing but
+[httpx](https://www.python-httpx.org/). The REST API follows the status
+above. This package's Python interface has no stability promise yet: it
+follows what the MCP server and the project's own checks need.
+
+What the project is for: [the repository's README](https://github.com/benethos-hub/mailbox#readme).
+
+## Install
+
+```sh
+uv add benethos-mailbox-client      # or: pip install benethos-mailbox-client
+```
+
+## Use
+
+Make a token on your user's page in the service's UI. The client reads
+it from `MAILBOX_SERVICE_TOKEN`, and the address of the service from
+`MAILBOX_SERVICE_URL` (default `http://127.0.0.1:8080`). Both can be
+passed as arguments instead.
+
+For async code:
+
+```python
+from benethos_mailbox_client import MailboxClient
+
+async with MailboxClient() as mailbox:
+    me = await mailbox.me()
+    for account in me.accounts:
+        page = await mailbox.list_messages(account.id, folder="inbox", limit=10)
+        for summary in page.items:
+            print(account.email, summary["subject"])
+```
+
+For code without an event loop, `SyncMailboxClient` has the same
+methods (`close()` for `aclose()`) and answers the same records:
+
+```python
+from benethos_mailbox_client import SyncMailboxClient, message_body
+
+with SyncMailboxClient() as mailbox:
+    body = message_body(
+        to=[("someone@example.org", None)],
+        cc=[],
+        bcc=[],
+        subject="Hello",
+        text="Hi there",
+        html=None,
+        reference=None,
+    )
+    mailbox.send_message("acc_...", body, idempotency_key="hello-1")
+```
+
+`request(method, path, ...)` reaches any route of the API the methods do
+not cover and answers its JSON. The routes and their fields:
+[`docs/openapi.json`](https://github.com/benethos-hub/mailbox/blob/main/docs/openapi.json).
+
+The token travels in a header. Over http the client talks only to this
+machine. To another machine it needs https, or
+`MAILBOX_SERVICE_ALLOW_HTTP=1` (`allow_http=True`) for a network you
+trust, such as between containers.
+
+A client made without an address or a token reads the environment when
+it is made. A program that makes clients for a long time can read it
+once, with `from_environment()`:
+
+```python
+from benethos_mailbox_client import MailboxClient, from_environment
+
+found = from_environment()
+client = MailboxClient(found.url, found.token, allow_http=found.allow_http)
+```
+
+## Errors
+
+Everything the client raises is a `MailboxError`:
+
+| Error | When |
+|---|---|
+| `ConfigurationError` | no token, or an address it refuses |
+| `ServiceUnavailableError` | the service cannot be reached |
+| `ServiceTimeoutError` | the service took the request but did not answer in time |
+| `ApiError` | the API answered with an error: `status`, `code`, `message` |
+
+## Inside
+
+Each endpoint is described once, in `endpoints/`, one module per
+resource of the API: its method, path, query, body and how its answer
+becomes a record. That package sends nothing. `MailboxClient` sends
+those requests with `httpx.AsyncClient`, `SyncMailboxClient` with
+`httpx.Client`, and a method of either is a line or two,
+`get_attachment`, which streams, a few more. What both share stands
+beside them: the address and the token (`environment.py`), the shape
+of a request (`calls.py`), how an answer or a failure is read
+(`answers.py`) and an attachment read in chunks (`attachments.py`).
+
+## License
+
+MIT, see [LICENSE](https://github.com/benethos-hub/mailbox/blob/main/LICENSE).

benethos_mailbox_client-0.3.0/README.md

@@ -0,0 +1,117 @@
+# mailbox-client
+
+[![CI](https://github.com/benethos-hub/mailbox/actions/workflows/ci.yml/badge.svg)](https://github.com/benethos-hub/mailbox/actions/workflows/ci.yml)
+[![PyPI benethos-mailbox-client](https://img.shields.io/pypi/v/benethos-mailbox-client?label=PyPI%20benethos-mailbox-client)](https://pypi.org/project/benethos-mailbox-client/)
+[![Python](https://img.shields.io/pypi/pyversions/benethos-mailbox-client)](https://pypi.org/project/benethos-mailbox-client/)
+[![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/benethos-hub/mailbox/blob/main/LICENSE)
+
+> **Beta, version 0.3.0.** Usable with real accounts. A breaking change
+> of the API or the configuration is announced in the changelog. Stored
+> data is carried forward by migrations.
+
+The Python client of the REST API of
+[`mailbox-service`](https://github.com/benethos-hub/mailbox/tree/main/packages/mailbox-service),
+on PyPI as `benethos-mailbox-client`. It reads, searches, sorts, drafts
+and sends mail of the accounts the service holds, as far as its token
+allows. The MCP server of the project,
+[`mailbox-mcp`](https://github.com/benethos-hub/mailbox/tree/main/packages/mailbox-mcp),
+is built on it.
+
+It knows the service through its REST API alone, and needs nothing but
+[httpx](https://www.python-httpx.org/). The REST API follows the status
+above. This package's Python interface has no stability promise yet: it
+follows what the MCP server and the project's own checks need.
+
+What the project is for: [the repository's README](https://github.com/benethos-hub/mailbox#readme).
+
+## Install
+
+```sh
+uv add benethos-mailbox-client      # or: pip install benethos-mailbox-client
+```
+
+## Use
+
+Make a token on your user's page in the service's UI. The client reads
+it from `MAILBOX_SERVICE_TOKEN`, and the address of the service from
+`MAILBOX_SERVICE_URL` (default `http://127.0.0.1:8080`). Both can be
+passed as arguments instead.
+
+For async code:
+
+```python
+from benethos_mailbox_client import MailboxClient
+
+async with MailboxClient() as mailbox:
+    me = await mailbox.me()
+    for account in me.accounts:
+        page = await mailbox.list_messages(account.id, folder="inbox", limit=10)
+        for summary in page.items:
+            print(account.email, summary["subject"])
+```
+
+For code without an event loop, `SyncMailboxClient` has the same
+methods (`close()` for `aclose()`) and answers the same records:
+
+```python
+from benethos_mailbox_client import SyncMailboxClient, message_body
+
+with SyncMailboxClient() as mailbox:
+    body = message_body(
+        to=[("someone@example.org", None)],
+        cc=[],
+        bcc=[],
+        subject="Hello",
+        text="Hi there",
+        html=None,
+        reference=None,
+    )
+    mailbox.send_message("acc_...", body, idempotency_key="hello-1")
+```
+
+`request(method, path, ...)` reaches any route of the API the methods do
+not cover and answers its JSON. The routes and their fields:
+[`docs/openapi.json`](https://github.com/benethos-hub/mailbox/blob/main/docs/openapi.json).
+
+The token travels in a header. Over http the client talks only to this
+machine. To another machine it needs https, or
+`MAILBOX_SERVICE_ALLOW_HTTP=1` (`allow_http=True`) for a network you
+trust, such as between containers.
+
+A client made without an address or a token reads the environment when
+it is made. A program that makes clients for a long time can read it
+once, with `from_environment()`:
+
+```python
+from benethos_mailbox_client import MailboxClient, from_environment
+
+found = from_environment()
+client = MailboxClient(found.url, found.token, allow_http=found.allow_http)
+```
+
+## Errors
+
+Everything the client raises is a `MailboxError`:
+
+| Error | When |
+|---|---|
+| `ConfigurationError` | no token, or an address it refuses |
+| `ServiceUnavailableError` | the service cannot be reached |
+| `ServiceTimeoutError` | the service took the request but did not answer in time |
+| `ApiError` | the API answered with an error: `status`, `code`, `message` |
+
+## Inside
+
+Each endpoint is described once, in `endpoints/`, one module per
+resource of the API: its method, path, query, body and how its answer
+becomes a record. That package sends nothing. `MailboxClient` sends
+those requests with `httpx.AsyncClient`, `SyncMailboxClient` with
+`httpx.Client`, and a method of either is a line or two,
+`get_attachment`, which streams, a few more. What both share stands
+beside them: the address and the token (`environment.py`), the shape
+of a request (`calls.py`), how an answer or a failure is read
+(`answers.py`) and an attachment read in chunks (`attachments.py`).
+
+## License
+
+MIT, see [LICENSE](https://github.com/benethos-hub/mailbox/blob/main/LICENSE).

benethos_mailbox_client-0.3.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "benethos-mailbox-client"
+version = "0.3.0"
+description = "Python client of the REST API of mailbox-service: the mail of all your mailboxes (IMAP, JMAP, POP3, Microsoft 365, Outlook.com) through one API, async and sync."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Benedikt Oswald" }]
+keywords = [
+    "email",
+    "imap",
+    "jmap",
+    "pop3",
+    "outlook",
+    "microsoft-365",
+    "multi-account",
+    "rest-client",
+    "api-client",
+    "email-automation",
+    "self-hosted",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Communications :: Email",
+    "Typing :: Typed",
+]
+# One library: the client speaks HTTP and nothing else. It knows the
+# service only through its REST API.
+dependencies = [
+    # The minimum is a version without a known vulnerability: the job
+    # lowest-versions of ci.yml checks it against OSV.
+    "httpx>=0.28",
+]
+
+[project.urls]
+Homepage = "https://github.com/benethos-hub/mailbox/tree/main/packages/mailbox-client#readme"
+Repository = "https://github.com/benethos-hub/mailbox"
+Issues = "https://github.com/benethos-hub/mailbox/issues"
+Changelog = "https://github.com/benethos-hub/mailbox/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/benethos_mailbox_client"]

benethos_mailbox_client-0.3.0/src/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-0.3.0/src/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-0.3.0/src/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-0.3.0/src/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