spot-sdk-python 2.1.0b3__py3-none-any.whl → 2.2.0b1__py3-none-any.whl

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/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/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/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/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/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,

{spot_sdk_python-2.1.0b3.dist-info → spot_sdk_python-2.2.0b1.dist-info}/METADATA

@@ -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.dist-info → spot_sdk_python-2.2.0b1.dist-info}/RECORD

@@ -1,19 +1,19 @@
-spot_sdk/__init__.py,sha256=l-o_lRVVvHz6eLt3gtUbSEghPCJg-L8XNFxTQXeRokk,4077
+spot_sdk/__init__.py,sha256=8ncEYjaoAewQBh20V9HtZDzvhv4jfYbCpedu8ihk21g,4124
 spot_sdk/_json.py,sha256=qK1b4EEgc6pHQn-M3_WnMN988N6sw4kvOUr7V-iEk74,1766
 spot_sdk/app.py,sha256=xVEZatG4KPnJZT5MBT_pjJxa389X-eljjFSBNkW1Nzo,25979
 spot_sdk/artifacts.py,sha256=mcWKIv1A-v3-bNQPxDVopJLGOfPk6YdiskIRmyV024U,7883
-spot_sdk/clients.py,sha256=sf6Mbc9Hw8pcAiD0XuTdM3Yg6b-oQJ6Uyq99Qsdw3-Y,9703
+spot_sdk/clients.py,sha256=GYjVP3duiMo-jLv215JLmMyfFLJL0EavfhHCek231FU,10664
 spot_sdk/config.py,sha256=sMSCOI_eVlcNiPamj4Nyuq7p44KZr06LFZVDlYgcqiI,1560
 spot_sdk/correlation.py,sha256=tgIL122V_d0htaR005zBHt2iLOoQnj3E-X-yKyPT6dc,2184
 spot_sdk/email.py,sha256=ifZHG9M0x-sTrOtohrU1NStsL4qeVddn18JoqLFawIQ,7313
 spot_sdk/errors.py,sha256=HTaRaoDfn5XV4v03qD4eCM-IgNaR7upQ08UF-I-1qaI,813
-spot_sdk/hosting.py,sha256=Dna2jXiTNJFc_38mNSQyMDqZvolg-zo6IkvrCcEyY1A,5618
+spot_sdk/hosting.py,sha256=3yQl5xEiFlVAts065e-LT6-qsajxAVhQ4KetHHmYpNE,5836
 spot_sdk/knowledge.py,sha256=TiBFPTekknqPuOGcH4FnkEsYBc5zZkmW7ToZTfTstqc,12405
 spot_sdk/knowledge_tags.py,sha256=BGhDsNeF8Q0MMNEIZjWrgQWjwH_Vf7dGBNN_hlBqTXs,978
 spot_sdk/llm.py,sha256=IEWhBbEat-7oHSNDg9_QOb7ylzv2g0B9uACpZq9-vMk,18610
 spot_sdk/logging.py,sha256=Tn_InLtrmy0NBFbkVXreVeXBazaz2bSdqEL1gxQa_Oo,10772
 spot_sdk/manifest.py,sha256=P38sJ0lPzAeAcd1hY2Qa9QSPrlLSVLpE6mTt-3l7j1Q,12245
-spot_sdk/mime.py,sha256=5PTxMpat1wq0k-6OtNAfj57de9pDviuMuWD2WbtynEk,121120
+spot_sdk/mime.py,sha256=cq93SPA6GLX-okjbNZQ9hVHbPmG4LUTbCzhyK48wE6E,121652
 spot_sdk/model_input.py,sha256=9sWrix9rH2h1oe49GWDOTy9zwsxWLSXtBfyhcYXsZh4,7469
 spot_sdk/orchestrator.py,sha256=r_-SWCrDLEjBcb_zn7KdMXttzbFvf1LhLx4FW8kq3q4,2665
 spot_sdk/proxy.py,sha256=HJUPnzxw3e2aZQXMBZmQEGDRPEnFI3Kyh0zaSPJcE5g,3529
@@ -21,7 +21,7 @@ spot_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 spot_sdk/retriever.py,sha256=fQh09-KusdO3EMhIeHX_H2G6N_K57XUk-AKZ7fLTAGk,4374
 spot_sdk/settings.py,sha256=4FN8WYSEoxY-Gf4D0jaSU-5z6o0EqrQXFbnD03qhd0Q,2884
 spot_sdk/signals.py,sha256=DkTqCSCcGbbtJjoTFrXExY9TcKFDXb-4SLR8wAgJUx0,1517
-spot_sdk/testing/README.md,sha256=N-42IBZOCxf0KbrfZ0nO64eBEC-l2hlQAjq4qIRJLQU,2786
+spot_sdk/testing/README.md,sha256=PBLlLySANJIXGGcSoSXQtUtA2kjfSkSx8w4F4o60ia8,2803
 spot_sdk/testing/__init__.py,sha256=4pTiWDdyYBFJwQnrhiC8PK8Ag-puKGEAHQG4hv8zfRs,555
 spot_sdk/testing/container.py,sha256=I4R-K-sWjT-AHPf-DoXacrBvLO-2fVqxPLwTgv0XofM,18504
 spot_sdk/testing/contract.py,sha256=t4J9HYIw2GF9esViY9362HYWoQunI3t9q6SraQhl0gA,10720
@@ -29,7 +29,7 @@ spot_sdk/testing/corpus.py,sha256=O1tEjwOR2VHPI_kWelQmvFjUXs_0OUtUEFtKfpdighc,92
 spot_sdk/testing/engine.py,sha256=IviyvQGvSGUiUSaK4Bbpv5O8sRs0LCpw49pXhR3kCZI,16280
 spot_sdk/testing/fake_knowledge_client.py,sha256=akq8N0xkI5HUlH8XHBq4ZKdEiNBiLwT4OrVaZZRadgs,6395
 spot_sdk/testing/fake_llm.py,sha256=8CZV1ZiEXOd6AK1oSk_9R8nvzzf5w1EEfPOYu3f3ruo,2538
-spot_sdk/testing/fake_spot.py,sha256=ep1BvYybhQKwO5uLe0KC0TwM5685Jv7HXANm2RLB1tM,8008
+spot_sdk/testing/fake_spot.py,sha256=ReZcw-rJU_-bJw3nayjaiUbSsSkLbvTtbah9b6vPgG4,8027
 spot_sdk/testing/metrics.py,sha256=sXdTw7WPCgyobmjZFk1WlX_qL7oaOGXfQ67zqd8QFY4,5062
 spot_sdk/testing/report.py,sha256=eToJgYPt0uYMyso87kskDZngKIEHU00RVGYDgsR4hFw,4248
 spot_sdk/testing/settings.py,sha256=lRwLD41qIV4ejmJJQbIPAJO2x7u8ieRpl1aTYWg9j0U,5113
@@ -37,6 +37,6 @@ spot_sdk/testing/views.py,sha256=Su45wOqCQG_O2WcpZhFnCZCLEc8yd9KsUl3YkjvvM9g,164
 spot_sdk/urls.py,sha256=pAz5Zara9UkNRoN2Vtx-33pARfBDy3JIA8xi-bkFdmk,1637
 spot_sdk/verdict.py,sha256=FUtAcsajJKgO_LaAfEJtHYq1K9BwG7a6sfpVkITjs_w,4429
 spot_sdk/workflow.py,sha256=sxD_Ms-t8Emv2vn4vf7ftJRIsPR9Fy7LumwFji60LP0,6993
-spot_sdk_python-2.1.0b3.dist-info/WHEEL,sha256=rp-k_VZaX8oABFEtLwG_Df95p8LSKt9-uPyQ4jKH0P4,81
-spot_sdk_python-2.1.0b3.dist-info/METADATA,sha256=d-XJ-fmvs7l7lX1b3QQDB-EIrouRfRaqLDI70Hm7K9A,4078
-spot_sdk_python-2.1.0b3.dist-info/RECORD,,
+spot_sdk_python-2.2.0b1.dist-info/WHEEL,sha256=rp-k_VZaX8oABFEtLwG_Df95p8LSKt9-uPyQ4jKH0P4,81
+spot_sdk_python-2.2.0b1.dist-info/METADATA,sha256=9Fo_3t1E7NO4fbQy6p1v39ROAzhKM7TMotYqzyDHwVE,4078
+spot_sdk_python-2.2.0b1.dist-info/RECORD,,