spot-sdk-python 2.1.0b3__tar.gz → 2.2.0b1__tar.gz

{spot_sdk_python-2.1.0b3 → spot_sdk_python-2.2.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spot-sdk-python
-Version: 2.1.0b3
+Version: 2.2.0b1
 Summary: SPOT plugin SDK: the plugin contract, the plugin runtime, its clients and test helpers
 Author: SPOT Project
 Author-email: SPOT Project <spot@sonn.lu>

{spot_sdk_python-2.1.0b3 → spot_sdk_python-2.2.0b1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "spot-sdk-python"
-version = "2.1.0b3"
+version = "2.2.0b1"
 description = "SPOT plugin SDK: the plugin contract, the plugin runtime, its clients and test helpers"
 readme = "README.md"
 license = "Apache-2.0"

{spot_sdk_python-2.1.0b3 → spot_sdk_python-2.2.0b1}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "spot-sdk-python"
-version = "2.1.0b3"
+version = "2.2.0b1"
 description = "SPOT plugin SDK: the plugin contract, the plugin runtime, its clients and test helpers"
 readme = "README.md"
 license = "Apache-2.0"

{spot_sdk_python-2.1.0b3 → spot_sdk_python-2.2.0b1}/spot_sdk/__init__.py

@@ -44,7 +44,7 @@ from .workflow import (
 
 if TYPE_CHECKING:
     from .app import CorrelationMiddleware, PluginHealth, SyncState, create_plugin_app
-    from .clients import SpotAPIError, SpotClient
+    from .clients import SpotAPIError, SpotClient, SpotGateway
     from .knowledge import KnowledgeClient, KnowledgeDocument, chunk_text, content_hash
     from .llm import LLMClient, LLMOutputError, LLMToolCall, LLMToolCalls, LLMToolRound
 
@@ -55,7 +55,7 @@ _LAZY = {
         ("CorrelationMiddleware", "PluginHealth", "SyncState", "create_plugin_app"),
         ".app",
     ),
-    **dict.fromkeys(("SpotAPIError", "SpotClient"), ".clients"),
+    **dict.fromkeys(("SpotAPIError", "SpotClient", "SpotGateway"), ".clients"),
     **dict.fromkeys(
         ("KnowledgeClient", "KnowledgeDocument", "chunk_text", "content_hash"),
         ".knowledge",
@@ -142,6 +142,7 @@ __all__ = [
     "LLMToolRound",
     "SpotAPIError",
     "SpotClient",
+    "SpotGateway",
     # Knowledge Store
     "KnowledgeClient",
     "KnowledgeDocument",

{spot_sdk_python-2.1.0b3 → spot_sdk_python-2.2.0b1}/spot_sdk/clients.py

@@ -10,6 +10,7 @@ the route and the status, never the content.
 - Analyzers fetch the raw message or one decoded part with
   :meth:`SpotClient.raw` and :meth:`SpotClient.part`.
 - Responders read a workflow's result with :meth:`SpotClient.result`.
+- :class:`SpotGateway` types a plugin's client parameter, so a test passes a fake.
 """
 
 from __future__ import annotations
@@ -17,7 +18,7 @@ from __future__ import annotations
 import asyncio
 import base64
 import json
-from typing import Any, TypeVar
+from typing import Any, Protocol, TypeVar
 from urllib.parse import quote
 from uuid import UUID
 
@@ -155,6 +156,35 @@ def ingestion_body(
     return b"".join([b'{"raw": "', *pieces, b'", ', others[1:]])
 
 
+class SpotGateway(Protocol):
+    """The gateway's plugin routes, as a plugin calls them.
+
+    A plugin types its parameter with it. ``SpotClient`` calls the gateway over
+    HTTP, and ``spot_sdk.testing.FakeSpot`` holds it in memory, so a test passes
+    a ``FakeSpot`` with no cast.
+    """
+
+    async def ingest(
+        self,
+        raw: bytes,
+        *,
+        envelope: Envelope | None = None,
+        priority: IngestionPriority = "normal",
+        wait_for_verdict: bool = False,
+        timeout_ms: int = 30_000,
+    ) -> IngestionResult: ...
+
+    async def report_action(
+        self, job_id: str, action: str, *, applied: bool
+    ) -> None: ...
+
+    async def raw(self, email_id: UUID) -> bytes: ...
+
+    async def part(self, email_id: UUID, part_id: str) -> tuple[bytes, str]: ...
+
+    async def result(self, job_id: str) -> OrchestrationResult: ...
+
+
 class SpotClient:
     """The api-gateway's plugin routes, called with the plugin's own token."""
 

{spot_sdk_python-2.1.0b3 → spot_sdk_python-2.2.0b1}/spot_sdk/hosting.py

@@ -44,7 +44,11 @@ could expand past the bound once decoded."""
 
 
 class AnswerRefusedError(Exception):
-    """A plugin's answer that is not read: encoded, or longer than ``MAX_ANSWER_BYTES``."""
+    """A plugin's answer that is not read: encoded, or longer than its bound."""
+
+
+class AnswerTooLargeError(AnswerRefusedError):
+    """An answer longer than its bound, which a caller may treat apart from an encoded one."""
 
 
 class InvalidResponseError(Exception):
@@ -121,11 +125,14 @@ def secrets_archive(secrets: Mapping[str, str]) -> bytes:
     return buffer.getvalue()
 
 
-async def read_answer(response: httpx2.Response) -> bytes:
-    """A streamed answer's body, as sent, read up to ``MAX_ANSWER_BYTES``.
+async def read_answer(
+    response: httpx2.Response, max_bytes: int = MAX_ANSWER_BYTES
+) -> bytes:
+    """A streamed answer's body, as sent, read up to ``max_bytes``.
 
     Raises:
-        AnswerRefusedError: the answer is encoded, or longer than ``MAX_ANSWER_BYTES``
+        AnswerRefusedError: the answer is encoded
+        AnswerTooLargeError: the answer is longer than ``max_bytes``
     """
     if (
         response.headers.get("content-encoding", "identity").strip().lower()
@@ -135,8 +142,8 @@ async def read_answer(response: httpx2.Response) -> bytes:
     body = bytearray()
     async for chunk in response.aiter_raw():
         body += chunk
-        if len(body) > MAX_ANSWER_BYTES:
-            raise AnswerRefusedError("response too large")
+        if len(body) > max_bytes:
+            raise AnswerTooLargeError(f"response too large: over {max_bytes} bytes")
     return bytes(body)
 
 

{spot_sdk_python-2.1.0b3 → spot_sdk_python-2.2.0b1}/spot_sdk/mime.py

@@ -1772,6 +1772,18 @@ def _addresses(value: str, cut: _Cutter, punycode: _Punycode) -> Iterator[Addres
         )
 
 
+def mailbox(value: str) -> Address | None:
+    """The first mailbox of an address header's ``value``, as :func:`parse` reads
+    a From into ``EmailView.from_``.
+
+    ``value`` is a header's value as the view keeps it (unfolded, RFC 2047
+    decoded). A value that does not parse is kept whole, with no domain; an
+    empty one is None. Its strings are cut to the view's budgets, its A-labels
+    decoded within one message's budget, as :func:`parse` does.
+    """
+    return next(_addresses(value, _Cutter(), _Punycode()), None)
+
+
 def _date(value: str) -> datetime | None:
     try:
         return parsedate_to_datetime(value)

{spot_sdk_python-2.1.0b3 → spot_sdk_python-2.2.0b1}/spot_sdk/testing/README.md

@@ -11,7 +11,7 @@ shows them in use.
 | `assert_contract(app, eml, *, token, timeout=10.0)` | waits until the plugin has started (`/health` is `healthy`), runs the app's `/internal/analyze` on a parsed `.eml` as core does, and checks the token and the `AnalyzerVerdict` |
 | `assert_bounds_agree(manifest, settings_cls)` | checks that the manifest states the bounds (`ge`, `le`, `pattern`...) of the settings model |
 | `assert_provider_contract(app, knowledge, *, token)` | runs two syncs of a context provider as core does, and checks the token, `/internal/sync`, `/internal/state` and the documents written to `knowledge` |
-| `FakeSpot` | `SpotClient` in memory: `ingest`, `raw`, `part`, `result`; `app(token=, knowledge=)` serves it over HTTP |
+| `FakeSpot` | `SpotClient` in memory: `ingest`, `report_action`, `raw`, `part`, `result`; `app(token=, knowledge=)` serves it over HTTP |
 | `FakeKnowledgeClient` | `KnowledgeClient` in memory, with naive word matching |
 | `FakeLLM` | `LLMClient` with scripted answers, recording each request |
 

{spot_sdk_python-2.1.0b3 → spot_sdk_python-2.2.0b1}/spot_sdk/testing/fake_spot.py

@@ -58,7 +58,7 @@ class _Query(BaseModel):
 
 
 class FakeSpot:
-    """In-memory gateway with the methods of ``SpotClient``."""
+    """In-memory gateway with the methods of ``SpotClient``: a ``SpotGateway``."""
 
     def __init__(
         self,