sendscore 0.3.0__py3-none-win_amd64.whl

sendscore/__init__.py

@@ -0,0 +1,122 @@
+"""Check a newsletter email before it goes out, with the SendScore CLI."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from typing import Any, cast
+
+from ._binary import ENGINE_VERSION, find_binary
+from ._error import KILLED, SendScoreError
+from .types import Change, Check, DiffResult, Fingerprint, Fix, Message, TopFix, Verdict
+
+__all__ = [
+    "ENGINE_VERSION",
+    "KILLED",
+    "Change",
+    "Check",
+    "DiffResult",
+    "Fingerprint",
+    "Fix",
+    "Message",
+    "SendScoreError",
+    "TopFix",
+    "Verdict",
+    "check",
+    "diff",
+]
+
+
+def _path(path: str | os.PathLike[str]) -> str:
+    # A lone "-" would mean standard input to the CLI.
+    text = os.fspath(path)
+    return "./-" if text == "-" else text
+
+
+def _run(
+    args: list[str],
+    stdin: bytes | None,
+    verdict_codes: tuple[int, ...],
+    timeout: float | None,
+) -> dict[str, Any]:
+    binary = find_binary()
+    try:
+        r = subprocess.run(
+            [binary, *args],
+            input=stdin,
+            stdin=subprocess.DEVNULL if stdin is None else None,
+            capture_output=True,
+            check=False,
+            timeout=timeout,
+        )
+    except subprocess.TimeoutExpired as e:
+        raise SendScoreError(f"sendscore did not finish within {timeout} seconds", KILLED) from e
+    except OSError as e:
+        raise SendScoreError(f"could not run {binary}: {e}", 0) from e
+    code = KILLED if r.returncode < 0 or r.returncode >= 128 else r.returncode
+    if code not in verdict_codes:
+        text = r.stderr.decode(errors="replace").strip()
+        raise SendScoreError(text or f"sendscore exited {code}", code)
+    try:
+        result = json.loads(r.stdout)
+    except ValueError as e:
+        raise SendScoreError("sendscore printed something that is not JSON", code) from e
+    if not isinstance(result, dict):
+        raise SendScoreError("sendscore printed something that is not a report", code)
+    return cast("dict[str, Any]", result)
+
+
+def check(
+    message: str | os.PathLike[str] | bytes,
+    *,
+    offline: bool = False,
+    links: bool = False,
+    ip: str | None = None,
+    mail_from: str | None = None,
+    helo: str | None = None,
+    tls: bool | None = None,
+    previous: str | os.PathLike[str] | None = None,
+    timeout: float | None = None,
+) -> Verdict:
+    """Checks one message, given as a path or as its bytes.
+
+    A message that fails checks is still a report. This raises SendScoreError
+    only when no report could be made. With a timeout in seconds, the CLI is
+    killed when it runs out.
+    """
+    args = ["check", "--json"]
+    if offline:
+        args.append("--offline")
+    if links:
+        args.append("--links")
+    if ip is not None:
+        args += ["--ip", ip]
+    if mail_from is not None:
+        args += ["--mail-from", mail_from]
+    if helo is not None:
+        args += ["--helo", helo]
+    if tls is not None:
+        args += ["--tls", "yes" if tls else "no"]
+    if previous is not None:
+        args += ["--previous", _path(previous)]
+    is_bytes = isinstance(message, (bytes, bytearray))
+    args += ["--", "-" if is_bytes else _path(message)]  # type: ignore[arg-type]
+    result = _run(args, bytes(message) if is_bytes else None, (0, 1, 2), timeout)  # type: ignore[arg-type]
+    if not str(result.get("schema", "")).startswith("sendscore.verdict/"):
+        raise SendScoreError("sendscore printed something that is not a verdict", 0)
+    return cast(Verdict, result)
+
+
+def diff(
+    before: str | os.PathLike[str],
+    after: str | os.PathLike[str],
+    *,
+    timeout: float | None = None,
+) -> DiffResult:
+    """Compares two saved messages, given as paths."""
+    result = _run(["diff", "--json", "--", _path(before), _path(after)], None, (0, 1), timeout)
+    if "changes" not in result:
+        raise SendScoreError("sendscore printed something that is not a comparison", 0)
+    result["changes"] = result.get("changes") or []
+    return cast(DiffResult, result)

sendscore/_binary.py

@@ -0,0 +1,206 @@
+"""Finds the CLI, which a wheel carries, and downloads a release when none is installed."""
+
+from __future__ import annotations
+
+import gzip
+import hashlib
+import http.client
+import io
+import os
+import platform
+import stat
+import subprocess
+import sys
+import tarfile
+import tempfile
+import urllib.error
+import urllib.request
+import zipfile
+from pathlib import Path
+
+from ._error import SendScoreError
+from ._hashes import HASHES
+
+ENGINE_VERSION = "0.3.0"
+RELEASES = "https://github.com/sendscore/sendscore/releases/download"
+MAX_DOWNLOAD = 100 << 20
+
+_OS = {"linux": "linux", "darwin": "darwin", "win32": "windows"}
+_ARCH = {"x86_64": "amd64", "amd64": "amd64", "arm64": "arm64", "aarch64": "arm64"}
+
+
+def current_platform() -> tuple[str, str]:
+    os_name = _OS.get(sys.platform)
+    arch = _ARCH.get(platform.machine().lower())
+    if not os_name or not arch:
+        raise SendScoreError(f"no SendScore build for {sys.platform} on {platform.machine()}", 0)
+    return os_name, arch
+
+
+def _cache_root() -> Path:
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Caches"
+    if sys.platform == "win32":
+        return Path(os.environ.get("LOCALAPPDATA") or Path.home() / "AppData" / "Local")
+    xdg = os.environ.get("XDG_CACHE_HOME")
+    return Path(xdg) if xdg and os.path.isabs(xdg) else Path.home() / ".cache"
+
+
+def archive_name(version: str, os_name: str, arch: str) -> str:
+    ext = "zip" if os_name == "windows" else "tar.gz"
+    return f"sendscore_{version}_{os_name}_{arch}.{ext}"
+
+
+def _fetch(url: str) -> bytes:
+    try:
+        with urllib.request.urlopen(url, timeout=60) as res:
+            body = res.read(MAX_DOWNLOAD + 1)
+    except (urllib.error.URLError, http.client.HTTPException, OSError) as e:
+        raise SendScoreError(f"download of {url} failed: {e}", 0) from e
+    if len(body) > MAX_DOWNLOAD:
+        raise SendScoreError(f"download of {url} is too large", 0)
+    return body
+
+
+def pin_for(os_name: str, arch: str, pins: dict[str, tuple[str, str]] = HASHES) -> tuple[str, str]:
+    """The (archive, binary) hashes of a platform. With none, nothing is trusted."""
+    pin = pins.get(f"{os_name}_{arch}")
+    if pin is None:
+        raise SendScoreError(
+            f"this package has no pinned hash for {os_name}_{arch}, so it will not download a CLI. "
+            "Install the matching sendscore on PATH, or set SENDSCORE_BIN.",
+            0,
+        )
+    return pin
+
+
+def matches_pin(path: Path, pin: tuple[str, str]) -> bool:
+    """Whether a file exists and is exactly the pinned binary."""
+    try:
+        return hashlib.sha256(path.read_bytes()).hexdigest() == pin[1]
+    except OSError:
+        return False
+
+
+def _extract(archive: bytes, os_name: str, bin_name: str) -> bytes | None:
+    # One file, by its exact name, so no path in the archive is ever used.
+    try:
+        if os_name == "windows":
+            with zipfile.ZipFile(io.BytesIO(archive)) as z:
+                return z.read(bin_name) if bin_name in z.namelist() else None
+        with tarfile.open(fileobj=io.BytesIO(gzip.decompress(archive))) as t:
+            for member in t:
+                if member.name == bin_name and member.isfile():
+                    f = t.extractfile(member)
+                    return f.read() if f else None
+    except (OSError, EOFError, zipfile.BadZipFile, tarfile.TarError) as e:
+        raise SendScoreError(f"could not read the archive: {e}", 0) from e
+    return None
+
+
+def download(
+    version: str,
+    base: str,
+    directory: Path,
+    pin: tuple[str, str],
+    target: tuple[str, str] | None = None,
+) -> Path:
+    """Downloads a release into directory, and returns the binary's path.
+
+    The archive must match its pin before anything is extracted, and the
+    binary must match its pin before it reaches the disk.
+    """
+    os_name, arch = target or current_platform()
+    bin_name = "sendscore.exe" if os_name == "windows" else "sendscore"
+    name = archive_name(version, os_name, arch)
+    archive = _fetch(f"{base}/{name}")
+    if hashlib.sha256(archive).hexdigest() != pin[0]:
+        raise SendScoreError(f"{name} does not match its pinned hash", 0)
+    binary = _extract(archive, os_name, bin_name)
+    if binary is None:
+        raise SendScoreError(f"{name} has no {bin_name}", 0)
+    if hashlib.sha256(binary).hexdigest() != pin[1]:
+        raise SendScoreError(f"the binary in {name} does not match its pinned hash", 0)
+    try:
+        directory.mkdir(parents=True, exist_ok=True)
+        fd, temp = tempfile.mkstemp(dir=directory, prefix=".download-")
+        try:
+            with os.fdopen(fd, "wb") as f:
+                f.write(binary)
+            os.chmod(temp, 0o755)
+            path = directory / bin_name
+            os.replace(temp, path)
+        finally:
+            if os.path.exists(temp):
+                os.unlink(temp)
+    except OSError as e:
+        raise SendScoreError(f"could not write to {directory}: {e}", 0) from e
+    return path
+
+
+def _executable(path: str) -> bool:
+    try:
+        return stat.S_ISREG(os.stat(path).st_mode) and os.access(path, os.X_OK)
+    except OSError:
+        return False
+
+
+def _right_version(path: str) -> bool:
+    try:
+        r = subprocess.run(
+            [path, "--version"], stdin=subprocess.DEVNULL, capture_output=True, timeout=10, check=False
+        )
+    except (OSError, subprocess.SubprocessError):
+        return False
+    words = r.stdout.decode(errors="replace").split()
+    return r.returncode == 0 and bool(words) and words[-1].removeprefix("v") == ENGINE_VERSION
+
+
+def find_binary() -> str:
+    """Finds the CLI: SENDSCORE_BIN, the wheel's binary, the pinned version on PATH, the cache, a download.
+
+    A cached binary is checked against its pinned hash every time, so a file
+    planted in the cache is replaced and never run.
+    """
+    from_env = os.environ.get("SENDSCORE_BIN")
+    if from_env:
+        return from_env
+    return bundled() or on_path() or installed()
+
+
+def bundled() -> str | None:
+    """The binary inside this wheel, or None.
+
+    It came with this code, so it is trusted as this code is, and needs no
+    version check or hash. A source checkout has none.
+    """
+    path = Path(__file__).parent / "_bin" / _exe_name()
+    return str(path) if _executable(str(path)) else None
+
+
+def on_path() -> str | None:
+    """The pinned version on PATH, or None.
+
+    A search of its own, because shutil.which looks in the current directory
+    on Windows, and follows PATHEXT to .bat and .cmd files.
+    """
+    for entry in os.environ.get("PATH", "").split(os.pathsep):
+        candidate = os.path.join(entry, _exe_name())
+        if os.path.isabs(entry) and _executable(candidate) and _right_version(candidate):
+            return candidate
+    return None
+
+
+def _exe_name() -> str:
+    return "sendscore.exe" if sys.platform == "win32" else "sendscore"
+
+
+def installed(pins: dict[str, tuple[str, str]] = HASHES) -> str:
+    """The cached binary, or a download, as the pins allow."""
+    target = current_platform()
+    pin = pin_for(*target, pins)
+    directory = _cache_root() / "sendscore" / ENGINE_VERSION
+    cached = directory / _exe_name()
+    if matches_pin(cached, pin):
+        return str(cached)
+    return str(download(ENGINE_VERSION, f"{RELEASES}/v{ENGINE_VERSION}", directory, pin, target))

sendscore/_cli.py

@@ -0,0 +1,45 @@
+"""The sendscore command: finds the CLI the same way the library does, then runs it."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+
+from ._binary import find_binary
+from ._error import SendScoreError
+
+# EX_SOFTWARE, as the CLI uses for an internal error.
+INTERNAL = 70
+
+# The PATH search may find this launcher and run it to read its version. The
+# mark makes that run fail at once, so the search moves on instead of looping.
+MARK = "SENDSCORE_LAUNCHED"
+
+
+def main() -> int:
+    if os.environ.get(MARK):
+        print("sendscore: found itself instead of the CLI", file=sys.stderr)
+        return INTERNAL
+    os.environ[MARK] = "1"
+    try:
+        path = find_binary()
+    except SendScoreError as e:
+        print(f"sendscore: {e}", file=sys.stderr)
+        return INTERNAL
+    args = [path, *sys.argv[1:]]
+    if os.name == "nt":
+        # Windows has no real exec: os.execv would return to the shell early.
+        try:
+            return subprocess.run(args, check=False).returncode
+        except OSError as e:
+            print(f"sendscore: could not run {path}: {e}", file=sys.stderr)
+            return INTERNAL
+        except KeyboardInterrupt:
+            return 130
+    try:
+        os.execv(path, args)
+    except OSError as e:
+        print(f"sendscore: could not run {path}: {e}", file=sys.stderr)
+        return INTERNAL
+    return INTERNAL

sendscore/_error.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+KILLED = -1
+"""The exit_code of a CLI that was killed, or stopped by a timeout."""
+
+
+class SendScoreError(Exception):
+    """The CLI could not produce a report, or could not be found or installed.
+
+    exit_code is the CLI's: 64 and above, 0 when the CLI never ran, or KILLED.
+    """
+
+    def __init__(self, message: str, exit_code: int) -> None:
+        super().__init__(message)
+        self.exit_code = exit_code

sendscore/_hashes.py

@@ -0,0 +1,10 @@
+# Generated by scripts/pinhashes. Do not edit.
+
+HASHES: dict[str, tuple[str, str]] = {
+    "darwin_amd64": ("d79c0d7d6f41322caf56f2ab90b6d61f25b97109f3449d84964751e9e9a685bb", "a508ff1a9bc8e63d5f79f663d5596cdd1c4cb6803d051d3c91a5a9481870dae1"),
+    "darwin_arm64": ("899eeac2be04f1d0619829cd0eb9fc171e358a0deb409e8dee74e3c95543bfac", "4e3ea55cc7bfa9d00d4b4742720ca475e8354052008a8133b0eeea9b17e6c109"),
+    "linux_amd64": ("c9bee6d95e057da006c27b015697db02f8d40f5f933c2c0f8956d33adc304bc8", "87a3c521bbf05516267757eb979f14bc66a2289cc5d5c86a8955186e984ff7da"),
+    "linux_arm64": ("69c75e7bd97f5f4e1e5f67f9eaa9efa808ef1264550385887c7222ff6370e6a1", "c0d25f8d93b8b202fa1b78e4275da41fe8e637dc256b03b19eed3af38e0b2c99"),
+    "windows_amd64": ("68f136dfd60a370512b97080781005c7cbffc00ce318bc77f5f347ae1625265f", "d2da36431144d87971a33ee9e59590f281fb84b8acf3b8814e989073e90f4866"),
+    "windows_arm64": ("f3f2d796add9f0690e447239931b6bd0e99ff25e6ea9553f205e88821e9b4761", "b78b9923bb5a6f7f0040969162e67417292d6e3558451a5faa7de18510398862"),
+}

sendscore/types.py

@@ -0,0 +1,100 @@
+"""The sendscore.verdict/v1 report. New keys may appear in this version."""
+
+from __future__ import annotations
+
+from typing import Any, Literal, TypedDict
+
+Status = Literal["pass", "warn", "fail", "info", "skipped"]
+Category = Literal["auth", "unsub", "struct", "content", "delivery", "changes"]
+Who = Literal["you", "provider"]
+
+
+Message = TypedDict(
+    "Message",
+    {
+        "received_at": str,
+        "from": str,
+        "subject": str,
+        "message_id": str,
+        "size_bytes": int,
+    },
+)
+
+
+class Fix(TypedDict):
+    who: Who
+    text: str
+
+
+class _CheckOptional(TypedDict, total=False):
+    detail: str
+    evidence: dict[str, Any]
+    fix: Fix
+    docs: str
+    reason: str
+
+
+class Check(_CheckOptional):
+    id: str
+    category: Category
+    status: Status
+    title: str
+
+
+class TopFix(TypedDict):
+    check: str
+    who: Who
+    fix: str
+
+
+class _ChangeOptional(TypedDict, total=False):
+    worsened: str
+
+
+class Change(_ChangeOptional):
+    field: str
+    before: Any
+    after: Any
+
+
+class _FingerprintOptional(TypedDict, total=False):
+    remote_ip: str
+    ptr: str
+
+
+class Fingerprint(_FingerprintOptional):
+    dkim_domains: list[str]
+    dkim_selectors: list[str]
+    return_path_domain: str
+    list_unsubscribe: bool
+    one_click: bool
+    link_hosts: list[str]
+    html_bytes: int
+    links: int
+    images: int
+    auth: dict[str, Status] | None
+
+
+class _VerdictOptional(TypedDict, total=False):
+    id: str
+    publication: str
+    fingerprint: Fingerprint
+
+
+class Verdict(_VerdictOptional):
+    schema: str
+    message: Message
+    verdict: Status
+    ready_to_send: bool
+    summary: str
+    top_fixes: list[TopFix]
+    checks: list[Check]
+    changes: list[Change]
+    explanation: str | None
+    note: str
+
+
+class DiffResult(TypedDict):
+    before: str
+    after: str
+    changes: list[Change]

sendscore-0.3.0.dist-info/METADATA

@@ -0,0 +1,42 @@
+Metadata-Version: 2.1
+Name: sendscore
+Version: 0.3.0
+Summary: Check a newsletter email before it goes out. A typed wrapper around the SendScore CLI.
+Home-page: https://github.com/sendscore/sendscore
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# SendScore for Python
+
+A typed wrapper around the [SendScore](https://github.com/sendscore/sendscore) CLI, which checks a newsletter email before it goes out. Every language package runs the same binary, so they all return the same verdict.
+
+Not published yet.
+
+```sh
+pip install sendscore
+```
+
+It also gives you the `sendscore` command, which takes the same arguments and exit codes as the CLI. To install only the command, use `pipx install sendscore`.
+
+```python
+from sendscore import check, diff
+
+verdict = check("issue.eml")
+if not verdict["ready_to_send"]:
+    for fix in verdict["top_fixes"]:
+        print(fix["who"], fix["fix"])
+
+check(raw_bytes, offline=True)
+diff("before.eml", "after.eml")
+```
+
+A message that fails its checks is still a report, so `check` returns it. `SendScoreError` is raised only when no report could be made, and its `exit_code` is the CLI's. Receipt at SendScore does not prove inbox placement at Gmail or any other provider.
+
+Pass `timeout` in seconds to `check` or `diff` to kill the CLI when it runs out. A killed CLI raises `SendScoreError` with `exit_code` set to `KILLED`, which is -1.
+
+## The binary
+
+The binary installs with the package. `pip install sendscore` picks the wheel for your machine, on macOS 12 or later, Linux with glibc or musl, and Windows, for x64 and arm64. Nothing runs at install time, and nothing is downloaded when you use it. There is no source distribution, so a platform without a wheel gets a clear error from pip.
+
+The package uses `SENDSCORE_BIN`, then that bundled binary, then the CLI on `PATH` if its version matches, then your user cache. Running from a source checkout, which has no binary, the first call downloads the pinned release from GitHub, and checks it against the SHA-256 values in the package before it runs anything, including a cached binary.

sendscore-0.3.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+sendscore/__init__.py,sha256=Pwjp0JNtVCj89lGL0VAOAVSQn4deKqbRejyYOZ48axo,3971
+sendscore/_binary.py,sha256=rlhqjsrr9OVedUdCt3nGUdVt1bW6U6hL3_ntKkfnxmw,7293
+sendscore/_cli.py,sha256=640PcGE4Gvywb4f0Duwu6vZCw6Cjd2VW0h8WZ5Y0Hz8,1390
+sendscore/_error.py,sha256=4kYa6ue5yDM2phlZQUvi6dYRdZctZnXR4KKX-TbH_9A,453
+sendscore/_hashes.py,sha256=kIvD6-00VDoWvRyTh9hbnN6H8zG22J9su4wKFwx-Rcw,1037
+sendscore/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sendscore/types.py,sha256=IvD4Swrsa8Q9c_D-3RaHo8MJU2qkPYMEOYZ1VLv0vLs,1838
+sendscore/_bin/sendscore.exe,sha256=0to2QxFE2Hlxoz7p5ZWQ8oH7hLis87iBTpiQc-kPSGY,10887680
+sendscore-0.3.0.dist-info/METADATA,sha256=loGN1fGqsYl0GqhXafySKqw2qqpDc33m7h-Kh4q0kuU,2110
+sendscore-0.3.0.dist-info/WHEEL,sha256=TsiSDhdhyt9XAieLKOvneE-sCkq4hE0TDj-iWgWgzZA,101
+sendscore-0.3.0.dist-info/entry_points.txt,sha256=JBvY_7ZO8sOckGUBNC7wALFcL4pu-OG4-L3wnk1LRaQ,50
+sendscore-0.3.0.dist-info/licenses/LICENSE,sha256=WPz7bGlc4ohvvTtXMBmtlXWbou5o9pKrAcnmaiC2Iyg,1066
+sendscore-0.3.0.dist-info/RECORD,,

sendscore-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: sendscore-buildpackages
+Root-Is-Purelib: false
+Tag: py3-none-win_amd64

sendscore-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sendscore = sendscore._cli:main

sendscore-0.3.0.dist-info/licenses/LICENSE

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