interloper-slack 0.54.0__tar.gz

interloper_slack-0.54.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.3
+Name: interloper-slack
+Version: 0.54.0
+Summary: Interloper Slack integration: notification hook and connection
+Author: Guillaume Onfroy
+Author-email: Guillaume Onfroy <guillaume@digitlcloud.com>
+Requires-Dist: interloper-core
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# interloper-slack
+
+Slack notifications for interloper runs: a `SlackHook` that posts a run
+outcome to a channel, and the `SlackConnection` that holds the bot token.
+
+The hook is the notification counterpart to core's `WebhookHook` — same
+events, but the payload is a message a human reads rather than a document a
+service parses.
+
+## Setup
+
+1. Create a Slack app (**From scratch**) at
+   [api.slack.com/apps](https://api.slack.com/apps).
+2. Under **OAuth & Permissions**, add these bot token scopes:
+   - `chat:write` — post the notification
+   - `channels:read`, `groups:read` — populate the channel picker
+3. **Install to Workspace** and copy the bot user token (`xoxb-…`).
+4. Invite the bot to each channel it posts to (`/invite @your-app`). Slack
+   rejects `chat.postMessage` with `not_in_channel` otherwise.
+
+One connection serves the whole workspace; each hook picks its own channel.
+
+## Usage
+
+```python
+import interloper as il
+from interloper_slack import SlackConnection, SlackHook
+
+hook = SlackHook(
+    connection=SlackConnection(bot_token="xoxb-..."),
+    channel="C0123456789",
+    watches=[my_source],
+    events=["run_failed"],
+)
+```
+
+The token also loads from the environment (`SLACK_BOT_TOKEN`), so
+`SlackConnection()` works with no arguments.
+
+`events` defaults to `["run_failed"]` like every hook — the alert most teams
+want. Add `"run_completed"` for a full-chatter channel.
+
+In a deployed instance you configure this through the UI instead: add a Slack
+connection, then a Slack hook watching the source or job you care about. The
+scheduler's hook evaluator fires it on terminal runs.
+
+## Message shape
+
+```
+❌ *Facebook Ads* failed
+Run `9f3c…` · partition `2026-07-30`
+```
+```
+HTTPStatusError: 429 Too Many Requests
+```
+
+The headline also travels as the message's `text`, so notification previews
+and screen readers get the outcome without parsing blocks.
+
+## Notes
+
+Every Slack call goes through the connection's `client` — a `cached_property`
+`il.RESTClient` with `il.HTTPBearerAuth`, like every other connection in the
+workspace. That client owns the base URL, the token, and the connection pool,
+so callers name a path and nothing else; the channel picker paginates with
+`il.JSONCursorPaginator` over Slack's `response_metadata.next_cursor`.
+
+The client is **sync**, where most connections' are async. The two consumers
+are a hook firing (sync by contract) and a form lookup — neither has
+independent requests to overlap, and the API process runs sync providers in a
+thread, so it never blocks the event loop.
+
+The one thing the framework can't cover is that Slack answers a *rejected*
+call with HTTP 200 and `{"ok": false, "error": "..."}`, so `raise_for_status()`
+alone lets failures pass silently. Each call site checks `ok` itself and raises
+`RuntimeError` with Slack's own error code — the same shape as the other
+connections that face an in-body error flag. For the paginated picker that
+check lives in the `data_selector`, since `paginate` only raises for HTTP
+status.
+
+A failed firing is recorded on the hook's firing claim (as `hook_failed`) and
+is not retried.

interloper_slack-0.54.0/README.md

@@ -0,0 +1,82 @@
+# interloper-slack
+
+Slack notifications for interloper runs: a `SlackHook` that posts a run
+outcome to a channel, and the `SlackConnection` that holds the bot token.
+
+The hook is the notification counterpart to core's `WebhookHook` — same
+events, but the payload is a message a human reads rather than a document a
+service parses.
+
+## Setup
+
+1. Create a Slack app (**From scratch**) at
+   [api.slack.com/apps](https://api.slack.com/apps).
+2. Under **OAuth & Permissions**, add these bot token scopes:
+   - `chat:write` — post the notification
+   - `channels:read`, `groups:read` — populate the channel picker
+3. **Install to Workspace** and copy the bot user token (`xoxb-…`).
+4. Invite the bot to each channel it posts to (`/invite @your-app`). Slack
+   rejects `chat.postMessage` with `not_in_channel` otherwise.
+
+One connection serves the whole workspace; each hook picks its own channel.
+
+## Usage
+
+```python
+import interloper as il
+from interloper_slack import SlackConnection, SlackHook
+
+hook = SlackHook(
+    connection=SlackConnection(bot_token="xoxb-..."),
+    channel="C0123456789",
+    watches=[my_source],
+    events=["run_failed"],
+)
+```
+
+The token also loads from the environment (`SLACK_BOT_TOKEN`), so
+`SlackConnection()` works with no arguments.
+
+`events` defaults to `["run_failed"]` like every hook — the alert most teams
+want. Add `"run_completed"` for a full-chatter channel.
+
+In a deployed instance you configure this through the UI instead: add a Slack
+connection, then a Slack hook watching the source or job you care about. The
+scheduler's hook evaluator fires it on terminal runs.
+
+## Message shape
+
+```
+❌ *Facebook Ads* failed
+Run `9f3c…` · partition `2026-07-30`
+```
+```
+HTTPStatusError: 429 Too Many Requests
+```
+
+The headline also travels as the message's `text`, so notification previews
+and screen readers get the outcome without parsing blocks.
+
+## Notes
+
+Every Slack call goes through the connection's `client` — a `cached_property`
+`il.RESTClient` with `il.HTTPBearerAuth`, like every other connection in the
+workspace. That client owns the base URL, the token, and the connection pool,
+so callers name a path and nothing else; the channel picker paginates with
+`il.JSONCursorPaginator` over Slack's `response_metadata.next_cursor`.
+
+The client is **sync**, where most connections' are async. The two consumers
+are a hook firing (sync by contract) and a form lookup — neither has
+independent requests to overlap, and the API process runs sync providers in a
+thread, so it never blocks the event loop.
+
+The one thing the framework can't cover is that Slack answers a *rejected*
+call with HTTP 200 and `{"ok": false, "error": "..."}`, so `raise_for_status()`
+alone lets failures pass silently. Each call site checks `ok` itself and raises
+`RuntimeError` with Slack's own error code — the same shape as the other
+connections that face an in-body error flag. For the paginated picker that
+check lives in the `data_selector`, since `paginate` only raises for HTTP
+status.
+
+A failed firing is recorded on the hook's firing claim (as `hook_failed`) and
+is not retried.

interloper_slack-0.54.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "interloper-slack"
+version = "0.54.0"
+description = "Interloper Slack integration: notification hook and connection"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["interloper-core"]
+
+[[project.authors]]
+name = "Guillaume Onfroy"
+email = "guillaume@digitlcloud.com"
+
+[project.entry-points."interloper.components"]
+slack = "interloper_slack"
+
+[build-system]
+requires = ["uv_build>=0.11.5,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.sources.interloper-core]
+workspace = true
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+extend-select = [
+    "E",
+    "I",
+    "UP",
+    "ANN001",
+    "ANN201",
+    "ANN202",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = [
+    "F401",
+    "F403",
+]
+"tests/**" = [
+    "ANN",
+    "F811",
+]

interloper_slack-0.54.0/pyproject.toml.orig

@@ -0,0 +1,36 @@
+# ###############
+# PROJECT / UV
+# ###############
+[project]
+name = "interloper-slack"
+version = "0.54.0"
+description = "Interloper Slack integration: notification hook and connection"
+readme = "README.md"
+authors = [{ name = "Guillaume Onfroy", email = "guillaume@digitlcloud.com" }]
+requires-python = ">=3.10"
+dependencies = [
+    "interloper-core",
+]
+
+[project.entry-points."interloper.components"]
+slack = "interloper_slack"
+
+[build-system]
+requires = ["uv_build>=0.11.5,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.sources]
+interloper-core = { workspace = true }
+
+# ###############
+# RUFF
+# ###############
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+extend-select = ["E", "I", "UP", "ANN001", "ANN201", "ANN202"]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401", "F403"]
+"tests/**" = ["ANN", "F811"]

interloper_slack-0.54.0/src/interloper_slack/__init__.py

@@ -0,0 +1,9 @@
+"""Interloper Slack integration: notification hook and connection."""
+
+from interloper_slack.connection import SlackConnection
+from interloper_slack.hook import SlackHook
+
+__all__ = [
+    "SlackConnection",
+    "SlackHook",
+]

interloper_slack-0.54.0/src/interloper_slack/connection.py

@@ -0,0 +1,123 @@
+"""Slack connection resource holding a bot token."""
+
+from __future__ import annotations
+
+from functools import cached_property
+from typing import Any
+
+import httpx
+from interloper.connection import Connection, connection
+from interloper.resource.fields import SecretField, fetch_field_provider
+from interloper.rest import HTTPBearerAuth, JSONCursorPaginator, RESTClient
+from pydantic_settings import SettingsConfigDict
+
+API_BASE = "https://slack.com/api"
+
+#: Slack caps ``conversations.list`` at 1000 per page.
+_PAGE_LIMIT = 1000
+
+#: Both channel visibilities a bot can post to once invited.
+_CHANNEL_TYPES = "public_channel,private_channel"
+
+#: Every call here serves an operator waiting on a form or a firing hook;
+#: neither is worth blocking on longer than this.
+_TIMEOUT = 30.0
+
+
+def _channels(response: httpx.Response) -> list[dict[str, Any]]:
+    """Select one page of channels, checking Slack's in-body ``ok`` flag.
+
+    ``paginate`` only raises for HTTP status, so the selector is where a
+    rejected page surfaces instead of a confusing miss on the ``channels``
+    key — Slack answers a refusal with 200 and ``ok: false``.
+
+    Returns:
+        The page's raw channel objects.
+    """
+    response.raise_for_status()
+    body = response.json()
+    if not body.get("ok"):
+        raise RuntimeError(f"Slack API error: {body.get('error')}")
+    return body.get("channels", [])
+
+
+@connection(
+    key="slack_connection",
+    name="Slack",
+    icon="devicon:slack",
+    tags=["Communication"],
+)
+class SlackConnection(Connection):
+    """Connection resource holding a Slack bot token.
+
+    The token is the whole credential, so one connection serves every hook in
+    the workspace and each hook picks its own channel. Create a Slack app,
+    give its bot the ``chat:write`` scope (plus ``channels:read`` /
+    ``groups:read`` for the channel picker), install it, and paste the
+    ``xoxb-`` token.
+    """
+
+    model_config = SettingsConfigDict(env_prefix="slack_")
+
+    bot_token: str = SecretField(
+        label="Bot token",
+        description="Slack bot user OAuth token (xoxb-…)",
+        info=(
+            "From your Slack app's OAuth & Permissions page. Needs the chat:write scope, "
+            "plus channels:read and groups:read for the channel picker."
+        ),
+    )
+
+    @cached_property
+    def client(self) -> RESTClient:
+        """The Slack Web API client every caller shares.
+
+        Sync, unlike most connections' clients: the consumers are a hook
+        firing (sync by contract) and a form lookup, neither of which has
+        independent requests to overlap. The API process runs sync providers
+        in a thread, so this does not block its event loop.
+        """
+        return RESTClient(API_BASE, auth=HTTPBearerAuth(self.bot_token), timeout=_TIMEOUT)
+
+    @fetch_field_provider
+    def channels(self) -> list[dict[str, str]]:
+        """List the workspace channels this token can see.
+
+        Backs the hook's ``channel`` ``FetchField``. Archived channels are
+        excluded — posting to one fails — and each option is labelled with a
+        leading ``#`` so the picker reads the way the channel does in Slack.
+
+        Returns:
+            Channel options with ``id`` and a display ``name``.
+        """
+        pages = self.client.paginate(
+            "/conversations.list",
+            JSONCursorPaginator(cursor_path="response_metadata.next_cursor", cursor_param="cursor"),
+            params={
+                "types": _CHANNEL_TYPES,
+                "limit": str(_PAGE_LIMIT),
+                "exclude_archived": "true",
+            },
+            data_selector=_channels,
+        )
+        results = [{"id": channel["id"], "name": f"#{channel['name']}"} for page in pages for channel in page]
+        return sorted(results, key=lambda c: c["name"].lower())
+
+    def check(self) -> bool:
+        """Prove the token works via ``auth.test``.
+
+        ``auth.test`` needs no scope beyond a valid token, so it isolates a
+        bad credential from a missing ``channels:read`` grant.
+
+        Returns:
+            True — an invalid token raises instead.
+
+        Raises:
+            RuntimeError: If Slack rejects the token.
+        """
+        response = self.client.post("/auth.test")
+        response.raise_for_status()
+        body = response.json()
+        if not body.get("ok"):
+            raise RuntimeError(f"Slack API error: {body.get('error')}")
+        return True

interloper_slack-0.54.0/src/interloper_slack/hook.py

@@ -0,0 +1,105 @@
+"""Slack hook: post a run outcome to a channel."""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from interloper.errors import ConfigError
+from interloper.hook import Hook, HookContext
+from interloper.resource.fields import FetchField, InputField
+
+from interloper_slack.connection import SlackConnection
+
+#: Event type → (emoji, past-tense verb) for the headline.
+_OUTCOMES: dict[str, tuple[str, str]] = {
+    "run_completed": (":white_check_mark:", "completed"),
+    "run_failed": (":x:", "failed"),
+}
+
+
+class SlackHook(Hook):
+    """Posts a run outcome to a Slack channel.
+
+    The notification counterpart to ``WebhookHook``: same events, but the
+    payload is a message a human reads rather than a document a service
+    parses. Defaults to ``run_failed`` like every hook, which is the alert
+    most teams want; add ``run_completed`` for a full-chatter channel.
+
+    The bot must be a member of the target channel — Slack rejects
+    ``chat.postMessage`` with ``not_in_channel`` otherwise, and the failure
+    is recorded on the firing claim rather than retried.
+    """
+
+    name: ClassVar[str] = "Slack"
+    icon: ClassVar[str] = "devicon:slack"
+    tags: ClassVar[list[str]] = ["Communication"]
+
+    connection: SlackConnection
+
+    channel: str = FetchField(
+        provider="connection.channels",
+        label_key="name",
+        value_key="id",
+        description="Channel that receives the notification",
+        discriminator=True,
+    )
+    timeout: float = InputField(default=10.0, description="Request timeout in seconds")
+
+    def fire(self, context: HookContext) -> None:
+        """Post the event as a message to the configured channel.
+
+        Raises:
+            ConfigError: If no Slack connection is attached.
+            RuntimeError: If Slack rejects the message — it answers a refusal
+                with 200 and ``ok: false``, so the status alone is not enough.
+        """
+        if self.connection is None:
+            raise ConfigError(f"SlackHook '{self.id}' fired without a Slack connection")
+
+        response = self.connection.client.post(
+            "/chat.postMessage",
+            json=self._message(context),
+            timeout=self.timeout,
+        )
+        response.raise_for_status()
+        body = response.json()
+        if not body.get("ok"):
+            raise RuntimeError(f"Slack API error: {body.get('error')}")
+
+    def _message(self, context: HookContext) -> dict[str, Any]:
+        """Build the ``chat.postMessage`` payload.
+
+        ``text`` carries the headline on its own so notification previews and
+        screen readers get the outcome without parsing blocks.
+
+        Returns:
+            The JSON-able message payload.
+        """
+        emoji, verb = _OUTCOMES.get(context.event_type, (":bell:", context.event_type))
+        subject = context.metadata.get("component_name") or context.component_id
+        headline = f"{emoji} *{subject}* {verb}"
+
+        lines = [headline]
+        if details := self._details(context):
+            lines.append(details)
+        if error := context.metadata.get("error"):
+            lines.append(f"```{error}```")
+
+        return {
+            "channel": self.channel,
+            "text": f"{subject} {verb}",
+            "blocks": [{"type": "section", "text": {"type": "mrkdwn", "text": "\n".join(lines)}}],
+        }
+
+    def _details(self, context: HookContext) -> str:
+        """Render the run/partition context line.
+
+        Returns:
+            The line, or ``""`` when the context carries neither.
+        """
+        parts = []
+        if context.run_id:
+            parts.append(f"Run `{context.run_id}`")
+        if context.partition_date:
+            parts.append(f"partition `{context.partition_date}`")
+        return " · ".join(parts)