sendora 0.1.0__tar.gz

sendora-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.coverage
+htmlcov/
+mutants/
+dist/

sendora-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0
+
+- `Sendora` and `AsyncSendora` for a server key, with `email.send`,
+  `email.send_batch`, `messages.get`, `messages.search` and
+  `messages.search_all`; their settings from the environment, the errors,
+  and the retries the TypeScript SDK makes.

sendora-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sendora
+
+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.

sendora-0.1.0/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.5
+Name: sendora
+Version: 0.1.0
+Summary: The Python client for Sendora's email API.
+Project-URL: Homepage, https://sendora.se/docs
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,email,sdk,sendora,transactional email
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: httpx2<3,>=2.3
+Description-Content-Type: text/markdown
+
+# sendora
+
+The Python client for [Sendora](https://sendora.se)'s email API.
+
+This package is being built: it covers the API in the releases before
+1.0.0, and its full guide arrives with 1.0.0. Until then, the TypeScript
+SDK and the API reference at https://sendora.se/docs describe what it
+wraps.
+
+```
+pip install sendora
+```
+
+It needs Python 3.11 or newer and has one dependency, httpx2.

sendora-0.1.0/README.md

@@ -0,0 +1,14 @@
+# sendora
+
+The Python client for [Sendora](https://sendora.se)'s email API.
+
+This package is being built: it covers the API in the releases before
+1.0.0, and its full guide arrives with 1.0.0. Until then, the TypeScript
+SDK and the API reference at https://sendora.se/docs describe what it
+wraps.
+
+```
+pip install sendora
+```
+
+It needs Python 3.11 or newer and has one dependency, httpx2.

sendora-0.1.0/pyproject.toml

@@ -0,0 +1,127 @@
+[project]
+name = "sendora"
+dynamic = ["version"]
+description = "The Python client for Sendora's email API."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = ["httpx2>=2.3,<3"]
+keywords = ["email", "transactional email", "api", "sdk", "sendora"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "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",
+]
+
+[project.urls]
+Homepage = "https://sendora.se/docs"
+
+[build-system]
+requires = ["hatchling==1.32.4"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/sendora/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sendora"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src", "README.md", "CHANGELOG.md", "LICENSE", "pyproject.toml"]
+
+[dependency-groups]
+test = [
+  "anyio==4.15.1",
+  "coverage==7.16.1",
+  "hypothesis==6.168.1",
+  "pytest==9.1.1",
+]
+dev = [
+  "mutmut==3.8.0",
+  "mypy==2.3.1",
+  "pyright[nodejs]==1.1.414",
+  "ruff==0.16.9",
+]
+
+[tool.uv]
+default-groups = ["dev", "test"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 88
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+  # The formatter owns these.
+  "COM812",
+  "ISC001",
+  # No copyright header per file; the licence is the package's.
+  "CPY001",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101", "S105", "S106", "PLR2004", "D", "SLF001", "FBT001", "ANN401", "E501"]
+"scripts/**" = ["T201", "D", "INP001"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+"smtplib".msg = "The SDK sends mail only through the API."
+"__future__.annotations".msg = "The decoder reads annotations at run time."
+
+[tool.pyright]
+include = ["src", "tests", "scripts"]
+typeCheckingMode = "strict"
+pythonVersion = "3.11"
+# Each checker honours its own ignore comments and refuses one it no longer
+# needs, so a line that must not type-check fails the check when it does.
+enableTypeIgnoreComments = false
+reportUnnecessaryTypeIgnoreComment = "error"
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+files = ["src", "tests", "scripts"]
+
+[tool.pytest]
+testpaths = ["tests/unit"]
+strict = true
+addopts = ["-p", "no:cacheprovider"]
+
+[tool.coverage.run]
+branch = true
+source = ["sendora"]
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+exclude_also = ["if TYPE_CHECKING:", "@overload"]
+
+[tool.mutmut]
+source_paths = ["src/sendora"]
+only_mutate = [
+  "src/sendora/_answers.py",
+  "src/sendora/_errors.py",
+  "src/sendora/_json.py",
+  "src/sendora/_pages.py",
+  "src/sendora/_retry.py",
+  "src/sendora/_wire.py",
+]
+# The package-shape and release tests read files mutmut does not copy, and
+# exercise nothing it mutates.
+pytest_add_cli_args_test_selection = [
+  "tests/unit",
+  "--ignore=tests/unit/test_package.py",
+  "--ignore=tests/unit/test_check_release.py",
+]

sendora-0.1.0/src/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-0.1.0/src/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