src-py-lib 0.1.0__py3-none-any.whl

src_py_lib/clients/slack.py

@@ -0,0 +1,146 @@
+"""Slack Web API client with cursor pagination and rate-limit handling."""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any, Final, cast
+
+from src_py_lib.utils.config import Config, config_field
+from src_py_lib.utils.http import HTTPClient, HTTPClientError, retry_after_seconds
+from src_py_lib.utils.json_types import JSONDict, json_dict, json_list, json_str
+
+SLACK_API_URL: Final[str] = "https://slack.com/api"
+DEFAULT_PAGE_LIMIT: Final[int] = 200
+DEFAULT_METHOD_INTERVAL_SECONDS: Final[float] = 1.3
+
+logger = logging.getLogger(__name__)
+
+
+class SlackError(RuntimeError):
+    """Raised for Slack API errors."""
+
+
+class SlackClientConfig(Config):
+    """Config fields needed to build a Slack API client."""
+
+    slack_bot_token: str = config_field(
+        default="",
+        env_var="SLACK_BOT_TOKEN",
+        cli_flag="--slack-bot-token",
+        metavar="TOKEN",
+        help="Slack bot token or op:// secret reference",
+        secret=True,
+        required=True,
+    )
+
+
+@dataclass
+class SlackPacer:
+    """Reserve spaced request slots per Slack method to avoid 429 bursts."""
+
+    default_interval_seconds: float = DEFAULT_METHOD_INTERVAL_SECONDS
+    method_intervals: dict[str, float] = field(default_factory=lambda: cast(dict[str, float], {}))
+    _lock: threading.Lock = field(default_factory=threading.Lock, init=False)
+    _next_slot: dict[str, float] = field(
+        default_factory=lambda: cast(dict[str, float], {}), init=False
+    )
+
+    def wait_for_slot(self, method: str) -> None:
+        interval = self.method_intervals.get(method, self.default_interval_seconds)
+        with self._lock:
+            now = time.time()
+            slot = max(self._next_slot.get(method, 0.0), now)
+            self._next_slot[method] = slot + interval
+        delay = slot - time.time()
+        if delay > 0:
+            time.sleep(delay)
+
+    def bump_after_rate_limit(self, method: str, wait_seconds: float) -> None:
+        with self._lock:
+            self._next_slot[method] = max(
+                self._next_slot.get(method, 0.0), time.time() + wait_seconds
+            )
+
+
+@dataclass
+class SlackClient:
+    token: str
+    http: HTTPClient = field(default_factory=lambda: HTTPClient(max_attempts=1))
+    pacer: SlackPacer = field(default_factory=SlackPacer)
+
+    def get(self, method: str, params: dict[str, Any] | None = None) -> JSONDict:
+        while True:
+            self.pacer.wait_for_slot(method)
+            try:
+                data = self.http.json(
+                    "GET",
+                    f"{SLACK_API_URL}/{method}",
+                    headers={"Authorization": f"Bearer {self.token}"},
+                    query=params or {},
+                )
+            except HTTPClientError as exception:
+                if exception.status_code == 429:
+                    wait_seconds = retry_after_seconds(exception.headers.get("retry-after")) or 5.0
+                    logger.warning("Slack %s rate-limited; sleeping %.0fs.", method, wait_seconds)
+                    self.pacer.bump_after_rate_limit(method, wait_seconds)
+                    continue
+                raise SlackError(f"Slack request to {method} failed: {exception}") from exception
+            if data.get("ok") is True:
+                return data
+            if data.get("error") == "ratelimited":
+                self.pacer.bump_after_rate_limit(method, 5)
+                continue
+            raise SlackError(f"Slack API error on {method}: {data.get('error')}")
+
+    def paginate(
+        self,
+        method: str,
+        *,
+        collection_key: str,
+        params: dict[str, Any] | None = None,
+        limit: int = DEFAULT_PAGE_LIMIT,
+    ) -> list[JSONDict]:
+        out: list[JSONDict] = []
+        cursor = ""
+        while True:
+            page_params = {**(params or {}), "limit": limit}
+            if cursor:
+                page_params["cursor"] = cursor
+            data = self.get(method, page_params)
+            out.extend(json_dict(item) for item in json_list(data.get(collection_key)))
+            cursor = json_str(json_dict(data.get("response_metadata")), "next_cursor")
+            if not cursor:
+                return out
+
+    def list_users(self) -> list[JSONDict]:
+        return self.paginate("users.list", collection_key="members")
+
+    def validate(self) -> JSONDict:
+        """Validate the token with Slack auth.test and return the response."""
+        data = self.get("auth.test")
+        if not json_str(data, "user_id"):
+            raise SlackError("Slack auth.test response did not include user_id.")
+        return data
+
+    def workspace_url(self) -> str:
+        url = json_str(self.get("auth.test"), "url").strip().rstrip("/")
+        if not url:
+            raise SlackError("Slack auth.test response did not include workspace URL.")
+        return url
+
+
+def slack_client_from_config(
+    config: SlackClientConfig,
+    *,
+    http: HTTPClient | None = None,
+    pacer: SlackPacer | None = None,
+) -> SlackClient:
+    """Return a Slack API client from shared Slack Config fields."""
+    return SlackClient(
+        config.slack_bot_token,
+        http=http or HTTPClient(max_attempts=1),
+        pacer=pacer or SlackPacer(),
+    )

src_py_lib/clients/sourcegraph.py

@@ -0,0 +1,127 @@
+"""Sourcegraph GraphQL API client."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping, Sequence
+from dataclasses import dataclass, field
+from urllib.parse import urlsplit
+
+from src_py_lib.clients.graphql import GraphQLClient, stream_connection_nodes
+from src_py_lib.utils.config import Config, config_field
+from src_py_lib.utils.http import HTTPClient
+from src_py_lib.utils.json_types import JSONDict, JSONValue, json_dict
+
+DEFAULT_SOURCEGRAPH_ENDPOINT = "https://sourcegraph.com"
+SOURCEGRAPH_VALIDATE_QUERY = """
+query SourcegraphClientValidate {
+  currentUser {
+    username
+  }
+}
+"""
+
+
+def normalize_sourcegraph_endpoint(endpoint: str, *, require_https: bool = False) -> str:
+    """Return a stable Sourcegraph base URL, or raise ValueError."""
+    normalized_endpoint = endpoint.strip().rstrip("/")
+    endpoint_parts = urlsplit(normalized_endpoint)
+    if require_https and endpoint_parts.scheme != "https":
+        raise ValueError(
+            f"Sourcegraph endpoint must be an https:// URL (got {endpoint_parts.scheme!r})"
+        )
+    if endpoint_parts.scheme not in {"http", "https"}:
+        raise ValueError(
+            "Sourcegraph endpoint must be an http:// or https:// URL "
+            f"(got {endpoint_parts.scheme!r})"
+        )
+    if not endpoint_parts.hostname:
+        raise ValueError(
+            f"could not parse hostname from Sourcegraph endpoint {normalized_endpoint!r}"
+        )
+    return normalized_endpoint
+
+
+class SourcegraphClientConfig(Config):
+    """Config fields needed to build a Sourcegraph API client."""
+
+    src_endpoint: str = config_field(
+        default=DEFAULT_SOURCEGRAPH_ENDPOINT,
+        env_var="SRC_ENDPOINT",
+        cli_flag="--src-endpoint",
+        metavar="URL",
+        help=f"Sourcegraph instance URL (default: {DEFAULT_SOURCEGRAPH_ENDPOINT})",
+    )
+    src_access_token: str = config_field(
+        default="",
+        env_var="SRC_ACCESS_TOKEN",
+        cli_flag="--src-access-token",
+        metavar="TOKEN",
+        help="Sourcegraph access token, or op:// secret reference",
+        secret=True,
+        required=True,
+    )
+
+
+@dataclass
+class SourcegraphClient:
+    """Small Sourcegraph GraphQL client.
+
+    `endpoint` should be the instance base URL, for example
+    `https://sourcegraph.example.com`.
+    """
+
+    endpoint: str
+    token: str
+    http: HTTPClient = field(default_factory=HTTPClient)
+
+    def __post_init__(self) -> None:
+        self.endpoint = normalize_sourcegraph_endpoint(self.endpoint)
+
+    def graphql(self, query: str, variables: Mapping[str, JSONValue] | None = None) -> JSONDict:
+        return self._client().execute(query, variables)
+
+    def stream_connection_nodes(
+        self,
+        query: str,
+        variables: Mapping[str, JSONValue] | None = None,
+        *,
+        connection_path: Sequence[str],
+        page_size: int | None = None,
+        first_variable: str = "first",
+        after_variable: str = "after",
+    ) -> Iterator[JSONDict]:
+        """Stream one Sourcegraph GraphQL connection's nodes."""
+        return stream_connection_nodes(
+            self.graphql,
+            query,
+            variables,
+            connection_path=connection_path,
+            page_size=page_size,
+            first_variable=first_variable,
+            after_variable=after_variable,
+        )
+
+    def validate(self) -> JSONDict:
+        """Validate the token with a cheap current user query and return the user."""
+        current_user = json_dict(self.graphql(SOURCEGRAPH_VALIDATE_QUERY).get("currentUser"))
+        if not current_user.get("username"):
+            raise RuntimeError(
+                "Sourcegraph current user response did not include currentUser.username."
+            )
+        return current_user
+
+    def _client(self) -> GraphQLClient:
+        return GraphQLClient(
+            url=f"{self.endpoint}/.api/graphql",
+            headers={"Authorization": f"token {self.token}"},
+            label="Sourcegraph",
+            http=self.http,
+        )
+
+
+def sourcegraph_client_from_config(config: SourcegraphClientConfig) -> SourcegraphClient:
+    """Return a Sourcegraph API client from shared Sourcegraph Config fields."""
+    return SourcegraphClient(
+        endpoint=config.src_endpoint,
+        token=config.src_access_token,
+    )

src_py_lib/utils/__init__.py

@@ -0,0 +1,3 @@
+"""Foundational utilities used by src_py_lib clients and consumers."""
+
+from __future__ import annotations