runnotify 0.1.0__py3-none-any.whl

runnotify/__init__.py

@@ -0,0 +1,75 @@
+"""Status reporting for long, unattended runs.
+
+A run that is meant to be left alone fails in ways nobody is watching for: it
+dies partway, it wedges on something that never returns, or the kernel kills it
+and leaves no trace. Each ends with a short result that looks like a result.
+This package reports those endings to wherever you read them.
+
+    from runnotify import Notifier
+
+    with Notifier("nightly-crawl") as run:
+        for i, item in enumerate(items):
+            process(item)
+            run.ping()
+            run.progress(f"{i}/{len(items)}", n=i)
+
+The context manager reports RUNNING on entry and COMPLETED, CANCELLED or ERROR
+on exit. Without it, call the status methods directly; an exit hook still reports
+CANCELLED if the process ends with nothing terminal sent, and
+:meth:`~runnotify.notifier.Notifier.start_oom_watchdog` covers the ``SIGKILL``
+case the interpreter never sees.
+
+Delivery is pluggable. Slack and Notion ship here; anything satisfying
+:class:`~runnotify.channel.Channel` can be passed to the notifier, registered by
+name for configuration, or published by another distribution through the
+``runnotify.channels`` entry-point group.
+
+Reporting is optional by construction: with nothing configured, every call is a
+no-op and the run is unchanged.
+"""
+
+from __future__ import annotations
+
+import logging
+
+__version__ = "0.1.0"
+
+from .channel import (
+    BaseChannel,
+    Channel,
+    ChannelError,
+    available,
+    build,
+    build_all,
+    register,
+    unregister,
+)
+from .channels import NotionChannel, SlackChannel
+from .config import Config, WatchdogConfig
+from .event import Event, Status
+from .notifier import DeliveryResult, Notifier
+
+__all__ = [
+    "BaseChannel",
+    "Channel",
+    "ChannelError",
+    "Config",
+    "DeliveryResult",
+    "Event",
+    "Notifier",
+    "NotionChannel",
+    "SlackChannel",
+    "Status",
+    "WatchdogConfig",
+    "__version__",
+    "available",
+    "build",
+    "build_all",
+    "register",
+    "unregister",
+]
+
+# A library configures no handlers. Without this, a host application that never
+# calls logging.basicConfig sees "No handlers could be found" noise from a
+# package whose entire job is to stay out of the way.
+logging.getLogger("runnotify").addHandler(logging.NullHandler())

runnotify/_cli.py

@@ -0,0 +1,169 @@
+"""The ``runnotify`` command: send one event from a shell.
+
+Built for the two things a command line is good for here — wiring a notification
+into a shell script or a job runner, and finding out why reporting is not
+working. It loads a ``.env`` the way a run would, names the file it read, and
+says which channel failed rather than reporting a single opaque boolean.
+
+Exit codes: ``0`` delivered, ``1`` at least one channel failed, ``2`` nothing was
+configured to deliver to, or the arguments were wrong.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import sys
+from pathlib import Path
+
+from . import __version__
+from ._env import find_env_file, load_env
+from .channel import available
+from .config import Config
+from .event import Status
+from .notifier import Notifier
+
+__all__ = ["build_parser", "main"]
+
+EXIT_OK = 0
+EXIT_DELIVERY_FAILED = 1
+EXIT_NOT_CONFIGURED = 2
+
+
+def build_parser() -> argparse.ArgumentParser:
+    # The channel list is read from the registry rather than written out, so
+    # installing a plugin documents it here without an edit.
+    installed = ", ".join(sorted(available())) or "none installed"
+    parser = argparse.ArgumentParser(
+        prog="runnotify",
+        description=f"Report the status of a run. Channels available: {installed}.",
+        epilog="Configuration: command line > environment > runnotify.toml > defaults.",
+    )
+    parser.add_argument("--version", action="version", version=f"runnotify {__version__}")
+    parser.add_argument("--topic", help="Identifies the run. Required unless configured.")
+    parser.add_argument(
+        "--status",
+        type=str.lower,
+        choices=[s.value for s in Status],
+        help="What to report.",
+    )
+    parser.add_argument("--message", default="", help="Message body.")
+    parser.add_argument("--progress", type=float, default=None, help="Numeric progress value.")
+    parser.add_argument("--source", default=None, help="Machine identifier (default: hostname).")
+    parser.add_argument(
+        "--channel",
+        action="append",
+        dest="channels",
+        metavar="NAME",
+        help="Deliver only to this channel. Repeatable.",
+    )
+    parser.add_argument("--config", default=None, help="TOML config file to use.")
+    parser.add_argument("--env-file", default=None, help="Read this .env instead of searching.")
+    parser.add_argument("--no-env", action="store_true", help="Do not read any .env file.")
+    parser.add_argument("--dry-run", action="store_true", help="Build the event, deliver nothing.")
+    parser.add_argument(
+        "--list-channels", action="store_true", help="List selectable channels and exit."
+    )
+    parser.add_argument("-v", "--verbose", action="count", default=0, help="Repeatable.")
+    return parser
+
+
+def _configure_logging(verbosity: int) -> None:
+    level = logging.WARNING
+    if verbosity == 1:
+        level = logging.INFO
+    elif verbosity >= 2:
+        level = logging.DEBUG
+    logging.basicConfig(level=level, format="%(levelname)s %(name)s: %(message)s")
+
+
+def _load_dotenv(args: argparse.Namespace) -> str:
+    """Read the nearest ``.env``, returning the path used for diagnostics."""
+    if args.no_env:
+        return ""
+    if args.env_file:
+        return str(args.env_file) if load_env(args.env_file) is not None else ""
+    found = find_env_file(Path.cwd())
+    if found:
+        load_env(found)
+        return str(found)
+    return ""
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    _configure_logging(args.verbose)
+
+    if args.list_channels:
+        for name, factory in sorted(available().items()):
+            print(f"{name}\t{factory.__module__}.{factory.__qualname__}")
+        return EXIT_OK
+
+    if not args.status:
+        parser.error("--status is required (or use --list-channels)")
+
+    env_file = _load_dotenv(args)
+
+    config = Config.load(args.config, env=os.environ)
+    if args.channels:
+        wanted = {c.strip().lower() for c in args.channels}
+        unknown = wanted - set(config.channels)
+        if unknown:
+            print(
+                f"runnotify: no configuration for channel(s): {', '.join(sorted(unknown))}",
+                file=sys.stderr,
+            )
+            return EXIT_NOT_CONFIGURED
+        config.channels = {k: v for k, v in config.channels.items() if k in wanted}
+
+    try:
+        notifier = Notifier(
+            topic=args.topic,
+            config=config,
+            source=args.source,
+            dry_run=args.dry_run,
+            # One event, then exit: the exit hook would otherwise append a
+            # second, untrue CANCELLED to every non-terminal status sent here.
+            cancel_on_exit=False,
+        )
+    except ValueError as exc:
+        parser.error(str(exc))  # raises SystemExit
+
+    if not notifier.channels:
+        print(_not_configured_message(config, env_file, notifier.problems), file=sys.stderr)
+        return EXIT_NOT_CONFIGURED
+
+    result = notifier.notify(args.status, args.message, progress=args.progress)
+    notifier.close()
+
+    if result:
+        print(f"sent {args.status} for {notifier.topic!r} via {', '.join(result.delivered)}")
+        return EXIT_OK
+
+    for name, failure in result.failed.items():
+        print(f"runnotify: {name} failed: {failure}", file=sys.stderr)
+    if not result.outcomes:
+        print(
+            f"runnotify: no channel accepted a {args.status} event "
+            "(check each channel's min_status)",
+            file=sys.stderr,
+        )
+        return EXIT_NOT_CONFIGURED
+    return EXIT_DELIVERY_FAILED
+
+
+def _not_configured_message(config: Config, env_file: str, problems: list[str]) -> str:
+    """Say what was looked at, so the next step is obvious."""
+    lines = ["runnotify: no channels configured, nothing sent."]
+    lines += [f"  {problem}" for problem in problems]
+    lines.append(f"  config file: {config.source_file or 'none found'}")
+    lines.append(f"  .env file:   {env_file or 'none found'}")
+    lines.append(f"  selectable:  {', '.join(sorted(available())) or 'none'}")
+    lines.append("  add a [channels.<name>] section to runnotify.toml, or see --help")
+    return "\n".join(lines)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

runnotify/_env.py

@@ -0,0 +1,73 @@
+"""Finding and reading a ``.env`` file, with no dependencies.
+
+The CLI is the tool people reach for when a webhook is not working, and it is
+invoked by hand rather than from a script that has already loaded its own
+environment. Without this it reports a missing variable that is, as far as the
+file is concerned, set.
+
+Existing environment variables win: a value exported in the shell is a
+deliberate override and must not be replaced by a file.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+__all__ = ["find_env_file", "load_env", "parse_env"]
+
+
+def find_env_file(start: Path | str | None = None, *, name: str = ".env") -> Path | None:
+    """The nearest ``name`` at or above ``start``, or None."""
+    current = Path(start or Path.cwd()).resolve()
+    if current.is_file():
+        current = current.parent
+    for directory in (current, *current.parents):
+        candidate = directory / name
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def parse_env(text: str) -> dict[str, str]:
+    """Parse ``KEY=VALUE`` lines.
+
+    Handles ``export`` prefixes, ``#`` comments, blank lines, and single or
+    double quoted values. Anything that is not a assignment is skipped rather
+    than raising: a malformed line in someone's ``.env`` must not stop a run from
+    reporting.
+    """
+    values: dict[str, str] = {}
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[len("export ") :].lstrip()
+        key, sep, value = line.partition("=")
+        if not sep:
+            continue
+        key = key.strip()
+        if not key:
+            continue
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'):
+            value = value[1:-1]
+        elif "#" in value:
+            value = value.split("#", 1)[0].strip()
+        values[key] = value
+    return values
+
+
+def load_env(path: Path | str, *, override: bool = False) -> dict[str, str]:
+    """Read ``path`` into :data:`os.environ`. Returns what was applied."""
+    try:
+        text = Path(path).read_text(encoding="utf-8")
+    except OSError:
+        return {}
+    applied: dict[str, str] = {}
+    for key, value in parse_env(text).items():
+        if override or key not in os.environ:
+            os.environ[key] = value
+            applied[key] = value
+    return applied

runnotify/_http.py

@@ -0,0 +1,151 @@
+"""A small JSON-over-HTTP client with bounded retries, built on the stdlib.
+
+Shared by the channels so that timeout, retry and backoff behave the same
+everywhere and are configured the same way. There is no third-party HTTP
+dependency: a notifier is imported by every run in a study, and a dependency
+here would be a dependency there.
+
+Transient failures are retried; a request that fails is retried at most
+``retries`` times with exponential backoff, and ``Retry-After`` is honoured when
+the server sends one. Statuses outside :data:`RETRY_STATUSES` are final — a 401
+from a bad token will not be retried, because it will not succeed.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import email.utils
+import json
+import logging
+import time
+import urllib.error
+import urllib.request
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+__all__ = ["HttpError", "Response", "request"]
+
+logger = logging.getLogger("runnotify")
+
+#: Statuses worth trying again: rate limits, and the server-side 5xx family that
+#: commonly reflects a momentary condition.
+RETRY_STATUSES = frozenset({408, 425, 429, 500, 502, 503, 504})
+
+#: Ceiling on any single backoff sleep, including a server's ``Retry-After``. A
+#: notifier must not park a run for minutes because a backend asked it to.
+MAX_BACKOFF_S = 30.0
+
+
+class HttpError(RuntimeError):
+    """A request that did not succeed, after any retries were exhausted."""
+
+    def __init__(self, message: str, *, status: int | None = None, body: str = "") -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+@dataclass(frozen=True, slots=True)
+class Response:
+    status: int
+    headers: Mapping[str, str]
+    body: bytes
+
+    def json(self) -> Any:
+        if not self.body:
+            return None
+        return json.loads(self.body.decode("utf-8"))
+
+
+def _retry_after_seconds(headers: Mapping[str, str]) -> float | None:
+    """``Retry-After`` as seconds, accepting both the numeric and date forms."""
+    raw = None
+    for key, value in headers.items():
+        if key.lower() == "retry-after":
+            raw = value
+            break
+    if not raw:
+        return None
+    raw = raw.strip()
+    try:
+        return max(0.0, float(raw))
+    except ValueError:
+        pass
+    # The header's other legal form is an HTTP date. Anything else is a server
+    # sending nonsense, and the caller's own backoff is the better answer.
+    try:
+        parsed = email.utils.parsedate_to_datetime(raw)
+    except (TypeError, ValueError):
+        return None
+    return max(0.0, parsed.timestamp() - time.time())
+
+
+def request(
+    method: str,
+    url: str,
+    *,
+    headers: Mapping[str, str] | None = None,
+    json_body: Any = None,
+    timeout: float = 10.0,
+    retries: int = 2,
+    backoff: float = 0.5,
+    sleep: Callable[[float], None] = time.sleep,
+    opener: Callable[..., Any] = urllib.request.urlopen,
+) -> Response:
+    """Perform one JSON request, retrying transient failures.
+
+    ``sleep`` and ``opener`` are injectable so tests can drive the retry path
+    without real time or real sockets.
+
+    Raises :class:`HttpError` when every attempt fails.
+    """
+    all_headers = {"Content-Type": "application/json", **(headers or {})}
+    data = json.dumps(json_body).encode("utf-8") if json_body is not None else None
+    attempts = max(1, retries + 1)
+    last: HttpError | None = None
+
+    for attempt in range(attempts):
+        if attempt:
+            delay = min(backoff * (2 ** (attempt - 1)), MAX_BACKOFF_S)
+            if last is not None and last.status in (429, 503):
+                delay = min(getattr(last, "retry_after", None) or delay, MAX_BACKOFF_S)
+            logger.debug("retrying %s %s in %.1fs (attempt %d)", method, url, delay, attempt + 1)
+            sleep(delay)
+
+        req = urllib.request.Request(url, data=data, headers=dict(all_headers), method=method)
+        try:
+            with opener(req, timeout=timeout) as resp:
+                body = resp.read()
+                status = getattr(resp, "status", None) or resp.getcode()
+                return Response(status=int(status), headers=dict(resp.headers), body=body)
+        except urllib.error.HTTPError as exc:
+            body_text = _safe_body(exc)
+            last = HttpError(
+                f"{method} {url} failed with HTTP {exc.code}", status=exc.code, body=body_text
+            )
+            last.retry_after = _retry_after_seconds(dict(exc.headers or {}))  # type: ignore[attr-defined]
+            if exc.code not in RETRY_STATUSES:
+                raise last from exc
+        except (urllib.error.URLError, OSError, TimeoutError) as exc:
+            last = HttpError(f"{method} {url} failed: {exc}")
+
+    assert last is not None  # attempts >= 1, so a failure path always set this
+    raise last
+
+
+def _safe_body(exc: urllib.error.HTTPError) -> str:
+    """The error body, truncated, or an empty string if it cannot be read.
+
+    Closes the error. ``HTTPError`` is itself a file-like object holding the
+    response stream, and an unclosed one is a leaked connection that surfaces
+    only later, as a ``ResourceWarning`` raised from a garbage collector far
+    from the request that caused it.
+    """
+    try:
+        return exc.read().decode("utf-8", "replace")[:500]
+    except Exception:  # pragma: no cover - the stream may already be closed
+        return ""
+    finally:
+        with contextlib.suppress(Exception):
+            exc.close()

runnotify/_watchdog.py

@@ -0,0 +1,112 @@
+"""Out-of-process watchdog: report a run that was killed without warning.
+
+``atexit`` covers every ending the interpreter gets to observe. ``SIGKILL`` is
+not one of them, and ``SIGKILL`` is what the Linux OOM killer sends — so a run
+that exhausts memory leaves a short table, no traceback, and no notification.
+
+This module runs as a detached child (``python -m runnotify._watchdog``). It
+polls whether its parent still exists and, when the parent disappears without
+having disarmed it, delivers an OOM event through that run's own channels. A
+channel added by a plugin therefore reports OOM with no change here.
+
+Configuration arrives as one JSON object on **stdin**, never on the command
+line: it carries webhook URLs and API tokens, and a command line is world
+readable through ``ps``.
+
+POSIX only. The liveness probe is ``os.kill(pid, 0)``, which reports existence
+without signalling on POSIX; on Windows the same call terminates the target.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import sys
+import time
+from collections.abc import Mapping
+from typing import Any
+
+from .channel import build_all
+from .event import Event, Status
+
+__all__ = ["main", "run"]
+
+
+def _parent_alive(pid: int) -> bool:
+    """Whether ``pid`` still names a live process.
+
+    ``PermissionError`` counts as alive: the process exists, this one merely
+    cannot signal it.
+    """
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
+def run(
+    config: Mapping[str, Any],
+    *,
+    sleep: Any = time.sleep,
+    alive: Any = _parent_alive,
+) -> int:
+    """Watch until the parent exits. Returns the process exit code.
+
+    ``sleep`` and ``alive`` are injectable so the loop can be tested without a
+    real process or real time.
+    """
+    pid = int(config["pid"])
+    sentinel = str(config["sentinel"])
+    poll = float(config.get("poll_interval", 5.0))
+    topic = str(config["topic"])
+    source = str(config.get("source", ""))
+    sections = config.get("channels") or {}
+
+    while True:
+        sleep(poll)
+        if alive(pid):
+            continue
+
+        # The parent is gone. A sentinel means it told us so.
+        if os.path.exists(sentinel):
+            with contextlib.suppress(OSError):
+                os.unlink(sentinel)
+            return 0
+
+        channels, _ = build_all(sections)
+        event = Event(
+            topic=topic,
+            status=Status.OOM,
+            message=f"Process {pid} was killed before reporting a result — likely OOM",
+            source=source,
+        )
+        failures = 0
+        for channel in channels:
+            try:
+                channel.deliver(event)
+            except Exception:
+                failures += 1
+        return 1 if failures and failures == len(channels) else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for ``python -m runnotify._watchdog``."""
+    del argv
+    try:
+        config = json.loads(sys.stdin.buffer.read().decode("utf-8"))
+    except (ValueError, OSError):
+        return 2
+    if not isinstance(config, dict) or "pid" not in config:
+        return 2
+    try:
+        return run(config)
+    except Exception:
+        return 1
+
+
+if __name__ == "__main__":  # pragma: no cover - exercised as a subprocess
+    raise SystemExit(main())