spot-sdk-python 2.0.0b12__tar.gz → 2.0.0b13__tar.gz

{spot_sdk_python-2.0.0b12 → spot_sdk_python-2.0.0b13}/PKG-INFO

@@ -1,25 +1,24 @@
 Metadata-Version: 2.4
 Name: spot-sdk-python
-Version: 2.0.0b12
+Version: 2.0.0b13
 Summary: SPOT plugin SDK: the plugin contract, the plugin runtime, its clients and test helpers
-License: Apache-2.0
 Author: SPOT Project
-Author-email: spot@sonn.lu
-Requires-Python: >=3.11,<3.16
-Classifier: License :: OSI Approved :: Apache Software License
+Author-email: SPOT Project <spot@sonn.lu>
+License-Expression: Apache-2.0
 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: Programming Language :: Python :: 3.15
-Requires-Dist: fastapi (>=0.133.0,<1)
-Requires-Dist: httpx2 (>=2.13.1,<3)
-Requires-Dist: idna (>=3.11,<4)
-Requires-Dist: pydantic (>=2.10,<3.0)
-Requires-Dist: pydantic-settings (>=2.0.0,<3.0.0)
-Requires-Dist: selectolax (>=1.0,<1.1)
-Requires-Dist: starlette (>=1.7.0,<2)
+Requires-Dist: pydantic>=2.10,<3
+Requires-Dist: pydantic-settings>=2.0.0,<3
+Requires-Dist: httpx2>=2.13.1,<3
+Requires-Dist: selectolax>=1.0,<1.1
+Requires-Dist: idna>=3.11,<4
+Requires-Dist: fastapi>=0.133.0,<1
+Requires-Dist: starlette>=1.7.0,<2
+Requires-Python: >=3.11, <3.16
 Project-URL: Homepage, https://sonn.lu
 Description-Content-Type: text/markdown
 
@@ -51,7 +50,7 @@ plugins share:
 ## Install
 
 ```bash
-pip install spot-sdk-python==2.0.0b12
+pip install spot-sdk-python==2.0.0b13
 ```
 
 Python 3.11 to 3.15. Version 2 implements plugin contract 2, for
@@ -116,4 +115,3 @@ token=...)`.
 ## License
 
 Apache License 2.0.
-

{spot_sdk_python-2.0.0b12 → spot_sdk_python-2.0.0b13}/README.md

@@ -26,7 +26,7 @@ plugins share:
 ## Install
 
 ```bash
-pip install spot-sdk-python==2.0.0b12
+pip install spot-sdk-python==2.0.0b13
 ```
 
 Python 3.11 to 3.15. Version 2 implements plugin contract 2, for

spot_sdk_python-2.0.0b13/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["uv_build>=0.12.22,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "spot-sdk-python"
+version = "2.0.0b13"
+description = "SPOT plugin SDK: the plugin contract, the plugin runtime, its clients and test helpers"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11,<3.16"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+]
+dependencies = [
+    "pydantic>=2.10,<3",
+    "pydantic-settings>=2.0.0,<3",
+    "httpx2>=2.13.1,<3",
+    "selectolax>=1.0,<1.1",
+    "idna>=3.11,<4",
+    "fastapi>=0.133.0,<1",
+    "starlette>=1.7.0,<2",
+]
+
+[[project.authors]]
+name = "SPOT Project"
+email = "spot@sonn.lu"
+
+[project.urls]
+Homepage = "https://sonn.lu"
+
+[tool.uv.build-backend]
+module-name = "spot_sdk"
+module-root = ""
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "N",
+    "W",
+]
+ignore = ["E501"]

spot_sdk_python-2.0.0b13/pyproject.toml.orig

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["uv_build>=0.12.22,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "spot-sdk-python"
+version = "2.0.0b13"
+description = "SPOT plugin SDK: the plugin contract, the plugin runtime, its clients and test helpers"
+readme = "README.md"
+license = "Apache-2.0"
+authors = [{ name = "SPOT Project", email = "spot@sonn.lu" }]
+requires-python = ">=3.11,<3.16"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+]
+dependencies = [
+    "pydantic>=2.10,<3",
+    "pydantic-settings>=2.0.0,<3",
+    "httpx2>=2.13.1,<3",
+    "selectolax>=1.0,<1.1",
+    "idna>=3.11,<4",
+    "fastapi>=0.133.0,<1",
+    "starlette>=1.7.0,<2",
+]
+
+[project.urls]
+Homepage = "https://sonn.lu"
+
+[tool.uv.build-backend]
+module-name = "spot_sdk"
+module-root = ""
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W"]
+ignore = ["E501"]  # Line too long

{spot_sdk_python-2.0.0b12 → spot_sdk_python-2.0.0b13}/spot_sdk/knowledge.py

@@ -64,8 +64,9 @@ class KnowledgeDocument(BaseModel):
     id: str = Field(
         ...,
         description=(
-            "Stable id, unique within its source (e.g. 'employee:alice@co.com'). "
-            "Upsert is idempotent on (source, id)."
+            "Stable id, unique within its source, e.g. a key of the source's own or a "
+            "keyed hash. It appears in URL paths and logs, so it never holds personal "
+            "data such as an email address. Upsert is idempotent on (source, id)."
         ),
     )
     content: str = Field(

{spot_sdk_python-2.0.0b12 → spot_sdk_python-2.0.0b13}/spot_sdk/mime.py

@@ -38,7 +38,9 @@ import base64
 import binascii
 import codecs
 import email
+import functools
 import hashlib
+import ipaddress
 import json
 import math
 import re
@@ -54,8 +56,8 @@ from email.utils import decode_params, getaddresses, parsedate_to_datetime, unqu
 from html import unescape as unescape_html
 from itertools import chain
 from typing import Any, Literal, NamedTuple, TypeAlias, TypeVar, cast
+from urllib.parse import SplitResult
 from urllib.parse import unquote as unquote_url
-from urllib.parse import urlsplit
 from uuid import UUID
 
 import idna
@@ -519,6 +521,38 @@ _MAX_LABEL = 4 * 63
 _MAX_A_LABEL = 63
 # The most characters idna maps a call (from 3.17).
 _IDNA_INPUT = 1024
+# NFC reorders a run of combining marks (of a canonical combining class
+# other than 0) in time quadratic in it. A label with more marks in a
+# row than an A-label holds characters maps to no DNS label: NFC composes at
+# most 3 of them into the character before (U+1F8F), and the 61 or more left
+# are code points an A-label spells with a character each at least, after its
+# "xn--": 65 characters.
+_MAX_MARKS = _MAX_A_LABEL
+_MARK_RUN = re.compile(rb"(?<![^\x00])[^\x00]{%d}" % (_MAX_MARKS + 1))
+# The characters UTS 46 maps to other marks than their own class counts (idna
+# 3.20, Unicode 14.0 and 15.1): to two, to marks though they are of class 0,
+# or to an iota, no mark.
+_MARK_READINGS = str.maketrans(
+    {
+        "\u0344": "\u0308\u0301",
+        "\u0345": "\u03b9",
+        "\u0f73": "\u0f71\u0f72",
+        "\u0f75": "\u0f71\u0f74",
+        "\u0f81": "\u0f71\u0f80",
+        "\uff9e": "\u3099",
+        "\uff9f": "\u309a",
+    }
+)
+# Python's urlsplit reads a URL without its leading C0 controls and spaces,
+# and without its tabs and line breaks. Its netloc follows "//", after the
+# scheme if any, up to the first of "/?#".
+_URL_LEADING = "".join(map(chr, range(0x21)))
+_URL_REMOVED = "\t\r\n"
+_NETLOC = re.compile(r"(?:[A-Za-z][A-Za-z0-9+.-]*:)?//([^/?#]*)")
+# What urlsplit refuses NFKC to make of a netloc's characters.
+_URL_DELIMITERS = frozenset("/?#@:")
+# An IPvFuture address, in brackets (RFC 3986).
+_IPV_FUTURE = re.compile(r"v[a-fA-F0-9]+\..+")
 
 
 # A parameter as email.utils decodes it: a value, or an RFC 2231
@@ -1532,11 +1566,26 @@ def _domain(host: str) -> str:
     A host that can be no DNS name (``_can_be_dns_name``) reaches no
     resolver: it is only lower-cased, neither mapped nor decoded. That bounds
     the work a host costs: CPython reorders combining marks for NFC in time
-    quadratic in their run, and a run ends at a dot.
+    quadratic in their run, and a longer run than ``_MAX_MARKS`` makes no DNS
+    name.
 
     It reads the host, and does not decide whether a browser would accept it:
     a label against the Bidi rule, or with a joiner out of context, is read
-    all the same."""
+    all the same.
+
+    A host of at most ``_MAX_DOMAIN`` characters is read once while it stays
+    among the last 256 the process read: a hostile message repeats one host
+    up to MAX_URLS times (sdk#27). UTS 46 maps a character to at most 18, so
+    the cache holds 19 MiB at most. A longer host is read each time: it is a
+    DNS name only once its invisible characters or its trailing dots are
+    removed."""
+    if len(host) > _MAX_DOMAIN:
+        return _read_domain(host)
+    return _cached_domain(host)
+
+
+def _read_domain(host: str) -> str:
+    """``host`` read as ``_domain`` reads it, each time."""
     host = host.rstrip(_DOT_CHARACTERS)
     if not _can_be_dns_name(host):
         return host.lower()
@@ -1549,19 +1598,37 @@ def _domain(host: str) -> str:
     return ".".join(map(_decoded, labels))
 
 
+_cached_domain = functools.lru_cache(maxsize=256)(_read_domain)
+
+
 def _can_be_dns_name(host: str) -> bool:
     """Whether ``host`` may map to a DNS name, counted on what a resolver could
     see: without its invisible characters (``visible``, which holds all those
     UTS 46 removes) and its trailing dots, it keeps at most ``_MAX_DOMAIN``
-    characters, and each label at most ``_MAX_LABEL``. UTS 46 maps any other
+    characters, each label at most ``_MAX_LABEL``, and at most ``_MAX_MARKS``
+    combining marks in a row as UTS 46 maps them. UTS 46 maps any other
     character to one or more, so the count never exceeds the mapped host's
-    before NFC. It only counts: the host is read as UTS 46 maps it."""
+    before NFC. The joiners, the only invisible characters UTS 46 keeps, may
+    split a run counted whole: no ASCII either, they leave the label as long
+    in its A-label. It only counts: the host is read as UTS 46 maps it."""
     counted = visible(host).rstrip(_DOT_CHARACTERS)
-    return len(counted) <= _MAX_DOMAIN and all(
-        len(label) <= _MAX_LABEL for label in _DOTS.split(counted)
+    return (
+        len(counted) <= _MAX_DOMAIN
+        and all(len(label) <= _MAX_LABEL for label in _DOTS.split(counted))
+        and not _too_many_marks(counted)
     )
 
 
+def _too_many_marks(text: str) -> bool:
+    """Whether ``text`` holds more than ``_MAX_MARKS`` combining marks in a row,
+    as UTS 46 maps them (``_MARK_READINGS``). In linear time: the classes, all
+    under 256, are matched as bytes, from the start of each run."""
+    if text.isascii():
+        return False
+    classes = bytes(map(unicodedata.combining, text.translate(_MARK_READINGS)))
+    return _MARK_RUN.search(classes) is not None
+
+
 def _mapped(label: str) -> str:
     """A label mapped as UTS 46 maps it; as written, lower-cased, when it does
     not map."""
@@ -1878,19 +1945,76 @@ def url_host(text: str) -> str:
     dropped. A label UTS 46 does not map stays as written, lower-cased, a
     host browsers refuse (a space, a slash, a label against the Bidi rule) is
     kept as read, and a host that can be no DNS name is only lower-cased:
-    never an exception. That is a host that keeps over 1 012 characters, or a
-    label over 252, once its invisible characters are removed: a DNS name
-    holds 253, a label 63, and NFC composes at most 4 code points into one.
-    An A-label over 63 characters stays encoded.
+    never an exception. That is a host that keeps over 1 012 characters, a
+    label over 252, or over 63 combining marks in a row, once its invisible
+    characters are removed: a DNS name holds 253, a label 63, NFC composes at
+    most 4 code points into one, and an A-label spells each code point that is
+    not ASCII with a character at least. An A-label over 63 characters stays
+    encoded.
+
+    The host is found as CPython 3.11's urlsplit reads it (3.13 also accepts
+    an IPvFuture ``V``), its ``.hostname``, and none where urlsplit refuses the
+    URL, but in linear time: urlsplit puts the netloc in NFKC to refuse a
+    character NFKC turns into a delimiter (U+2100 is ``a/c``), in time
+    quadratic in a run of combining marks.
     """
     if text[:4].lower() == "www.":
         text = "http://" + text
+    # Browsers read a backslash as a slash in web URLs.
+    host = _hostname(text.replace("\\", "/"))
+    return _domain(_clean(unquote_url(host))) if host else ""
+
+
+def _hostname(url: str) -> str | None:
+    """``urlsplit(url).hostname``, as CPython 3.11's urlsplit reads it (3.13
+    also accepts an IPvFuture ``V``); None where urlsplit refuses ``url``: a
+    bracket without its pair, brackets misplaced or around no IPv6 or IPvFuture
+    address (``_accepted_brackets``), or a character NFKC turns into a
+    delimiter. That last is checked a character at a time: NFKC composes no
+    delimiter, and the netloc's own ``@`` and ``:`` do not count."""
+    netloc = _netloc(url)
+    if ("[" in netloc) != ("]" in netloc):
+        return None
+    if "[" in netloc and not _accepted_brackets(netloc.rpartition("@")[2]):
+        return None
+    if any(
+        not _URL_DELIMITERS.isdisjoint(unicodedata.normalize("NFKD", character))
+        for character in set(netloc)
+        if not character.isascii()
+    ):
+        return None
+    return SplitResult("", netloc, "", "", "").hostname
+
+
+def _netloc(url: str) -> str:
+    """The netloc urlsplit reads in ``url``, unchecked; "" when it has none."""
+    url = url.lstrip(_URL_LEADING)
+    for removed in _URL_REMOVED:
+        url = url.replace(removed, "")
+    found = _NETLOC.match(url)
+    return found.group(1) if found else ""
+
+
+def _accepted_brackets(hostinfo: str) -> bool:
+    """Whether urlsplit accepts the brackets of a netloc whose ``hostinfo``
+    follows its last ``@``: nothing before them, only a port after them, and an
+    IPv6 or IPvFuture address in them. With the brackets in the userinfo, the
+    host itself must be such an address."""
+    before, bracket, bracketed = hostinfo.partition("[")
+    if not bracket:
+        host = before.partition(":")[0]
+    elif before:
+        return False
+    else:
+        host, _, port = bracketed.partition("]")
+        if port and not port.startswith(":"):
+            return False
+    if host.startswith("v"):
+        return _IPV_FUTURE.fullmatch(host) is not None
     try:
-        # Browsers read a backslash as a slash in web URLs.
-        host = urlsplit(text.replace("\\", "/")).hostname
+        return ipaddress.ip_address(host).version == 6
     except ValueError:
-        return ""
-    return _domain(_clean(unquote_url(host))) if host else ""
+        return False
 
 
 def _url(

{spot_sdk_python-2.0.0b12 → spot_sdk_python-2.0.0b13}/spot_sdk/workflow.py

@@ -15,6 +15,10 @@ ResponseMode = Literal["observe", "enforce"]
 DECISIVE_SIGNAL_PATTERN = r"^[a-z0-9_]+(\.[a-z0-9_]+)*\.([a-z0-9_]+|\*)$"
 """A signal name, or a prefix ending in ``.*``."""
 
+# A workflow id goes into URLs, log lines and the commit messages of the config
+# history: letters, digits, dots, underscores and hyphens only (sdk#26)
+WORKFLOW_ID_PATTERN = r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"
+
 
 class FailureStrategy(StrEnum):
     """Strategy for handling analyzer failures."""
@@ -163,7 +167,11 @@ class VerdictPolicy(BaseModel):
 class Workflow(BaseModel):
     """Complete workflow configuration for email analysis."""
 
-    id: str = Field(..., description="Workflow ID")
+    id: str = Field(
+        ...,
+        pattern=WORKFLOW_ID_PATTERN,
+        description="Workflow ID: a letter or digit, then up to 127 letters, digits, dots, underscores or hyphens",
+    )
     name: str = Field(..., description="Workflow name")
     version: int = Field(default=1, ge=1, description="Workflow version")
     description: str = Field(default="", description="Workflow description")

spot_sdk_python-2.0.0b12/pyproject.toml

@@ -1,38 +0,0 @@
-[build-system]
-requires = ["poetry-core"]
-build-backend = "poetry.core.masonry.api"
-
-[tool.poetry]
-name = "spot-sdk-python"
-version = "2.0.0b12"
-description = "SPOT plugin SDK: the plugin contract, the plugin runtime, its clients and test helpers"
-authors = ["SPOT Project <spot@sonn.lu>"]
-license = "Apache-2.0"
-homepage = "https://sonn.lu"
-readme = "README.md"
-packages = [
-    {include = "spot_sdk"}
-]
-
-[tool.poetry.dependencies]
-python = ">=3.11,<3.16"
-pydantic = "^2.10"
-pydantic-settings = "^2.0.0"
-httpx2 = ">=2.13.1,<3"
-selectolax = ">=1.0,<1.1"
-idna = ">=3.11,<4"
-fastapi = ">=0.133.0,<1"
-starlette = ">=1.7.0,<2"
-
-[tool.poetry.group.dev.dependencies]
-pytest = "^9.0.3"
-pytest-asyncio = "^1.3.0"
-pytest-cov = "^4.1.0"
-mypy = "^1.5.0"
-
-[tool.ruff]
-target-version = "py311"
-
-[tool.ruff.lint]
-select = ["E", "F", "I", "N", "W"]
-ignore = ["E501"]  # Line too long