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

src_py_lib/__init__.py

@@ -0,0 +1,170 @@
+"""Public interface for src-py-lib consumers."""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable, Mapping
+from contextlib import AbstractContextManager
+from pathlib import Path
+from typing import Any
+
+from src_py_lib.clients.github import GitHubClient, PullRequest, gh_cli_token, pr_ref_from_url
+from src_py_lib.clients.google_sheets import (
+    GoogleSheetsClient,
+    GoogleSheetsError,
+    gcloud_adc_access_token,
+    quota_project_from_adc,
+)
+from src_py_lib.clients.graphql import (
+    GraphQLClient,
+    GraphQLError,
+    aliased_batched_query,
+    introspect_schema,
+    stream_connection_nodes,
+)
+from src_py_lib.clients.linear import (
+    LinearClient,
+    LinearClientConfig,
+    linear_client_from_config,
+)
+from src_py_lib.clients.slack import (
+    SlackClient,
+    SlackClientConfig,
+    SlackError,
+    SlackPacer,
+    slack_client_from_config,
+)
+from src_py_lib.clients.sourcegraph import (
+    SourcegraphClient,
+    SourcegraphClientConfig,
+    normalize_sourcegraph_endpoint,
+    sourcegraph_client_from_config,
+)
+from src_py_lib.utils.config import (
+    Config,
+    ConfigError,
+    config_field,
+    config_snapshot,
+)
+from src_py_lib.utils.config import (
+    config_parse_args as parse_args,
+)
+from src_py_lib.utils.http import HTTPClient, HTTPClientError
+from src_py_lib.utils.json_cache import load_json_cache, load_json_subset, save_json_cache
+from src_py_lib.utils.json_types import (
+    JSONDict,
+    json_dict,
+    json_dicts,
+    json_int,
+    json_list,
+    json_str,
+    json_strs,
+)
+from src_py_lib.utils.logging import (
+    LoggingConfig,
+    LoggingSettings,
+    configure_logging,
+    critical,
+    debug,
+    error,
+    event,
+    info,
+    log,
+    log_context,
+    logging_context,
+    logging_settings_from_config,
+    resolve_log_level_name,
+    stage,
+    startup_event,
+    submit_with_log_context,
+    warning,
+)
+from src_py_lib.utils.tsv import write_tsv
+
+
+def logging(
+    config: object | None = None,
+    *,
+    command: str | None = None,
+    git_cwd: Path | str | None = None,
+    logging_config: LoggingSettings | None = None,
+    run_fields: Mapping[str, Any] | None = None,
+    run_summary: Callable[[], Mapping[str, Any]] | None = None,
+) -> AbstractContextManager[Path | None]:
+    """Configure standard CLI logging and emit startup metadata."""
+    return logging_context(
+        command or _script_name(),
+        config,
+        git_cwd=git_cwd,
+        logging_config=logging_config,
+        run_fields=run_fields,
+        run_summary=run_summary,
+    )
+
+
+def _script_name() -> str:
+    return Path(sys.argv[0]).stem or "python"
+
+
+__all__ = [
+    "Config",
+    "ConfigError",
+    "GraphQLError",
+    "GraphQLClient",
+    "GitHubClient",
+    "GoogleSheetsClient",
+    "GoogleSheetsError",
+    "HTTPClient",
+    "HTTPClientError",
+    "JSONDict",
+    "LinearClient",
+    "LinearClientConfig",
+    "LoggingConfig",
+    "LoggingSettings",
+    "PullRequest",
+    "SlackClient",
+    "SlackClientConfig",
+    "SlackError",
+    "SlackPacer",
+    "SourcegraphClient",
+    "SourcegraphClientConfig",
+    "aliased_batched_query",
+    "config_field",
+    "config_snapshot",
+    "configure_logging",
+    "critical",
+    "debug",
+    "error",
+    "event",
+    "gh_cli_token",
+    "gcloud_adc_access_token",
+    "info",
+    "introspect_schema",
+    "json_dict",
+    "json_dicts",
+    "json_int",
+    "json_list",
+    "json_str",
+    "json_strs",
+    "linear_client_from_config",
+    "load_json_cache",
+    "load_json_subset",
+    "logging",
+    "logging_settings_from_config",
+    "log",
+    "log_context",
+    "normalize_sourcegraph_endpoint",
+    "parse_args",
+    "pr_ref_from_url",
+    "quota_project_from_adc",
+    "resolve_log_level_name",
+    "save_json_cache",
+    "slack_client_from_config",
+    "sourcegraph_client_from_config",
+    "stage",
+    "startup_event",
+    "stream_connection_nodes",
+    "submit_with_log_context",
+    "warning",
+    "write_tsv",
+]

src_py_lib/clients/__init__.py

@@ -0,0 +1,3 @@
+"""API clients built on src_py_lib HTTP and logging primitives."""
+
+from __future__ import annotations

src_py_lib/clients/github.py

@@ -0,0 +1,157 @@
+"""GitHub GraphQL API client."""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+from dataclasses import dataclass, field
+from typing import TypedDict, cast
+from urllib.parse import urlsplit
+
+from src_py_lib.clients.graphql import GraphQLClient, aliased_batched_query
+from src_py_lib.utils.http import HTTPClient
+from src_py_lib.utils.json_types import JSONDict, json_dict, json_str
+
+DEFAULT_GITHUB_URL = "https://github.com"
+DEFAULT_PR_BATCH_SIZE = 50
+GITHUB_VALIDATE_QUERY = """
+query GitHubClientValidate {
+  viewer {
+    login
+  }
+}
+"""
+PR_REF_RE = re.compile(r"^(?P<owner>[^/]+)/(?P<repo>[^/#]+)#(?P<number>\d+)$")
+PR_URL_RE = re.compile(
+    r"https?://[^/\s)>|]+/(?P<owner>[^/\s)>|]+)/(?P<repo>[^/\s)>|]+)/pull/(?P<number>\d+)"
+)
+
+
+class PullRequest(TypedDict):
+    title: str
+    url: str
+    state: str
+    createdAt: str
+    mergedAt: str
+    closedAt: str
+    author: str
+
+
+@dataclass
+class GitHubClient:
+    token: str
+    github_url: str = DEFAULT_GITHUB_URL
+    http: HTTPClient = field(default_factory=HTTPClient)
+
+    @classmethod
+    def from_gh_cli(
+        cls, *, github_url: str = DEFAULT_GITHUB_URL, http: HTTPClient | None = None
+    ) -> GitHubClient:
+        token = gh_cli_token(github_url=github_url)
+        if not token:
+            raise RuntimeError("No GitHub token from `gh auth token`.")
+        return cls(token=token, github_url=github_url, http=http or HTTPClient())
+
+    def graphql(self, query: str, variables: JSONDict | None = None) -> JSONDict:
+        return GraphQLClient(
+            url=graphql_api_url(self.github_url),
+            headers={"Authorization": f"bearer {self.token}"},
+            label="GitHub",
+            http=self.http,
+            tolerate_partial_errors=True,
+        ).execute(query, variables)
+
+    def validate(self) -> JSONDict:
+        """Validate the token with a cheap viewer query and return the viewer."""
+        viewer = json_dict(self.graphql(GITHUB_VALIDATE_QUERY).get("viewer"))
+        if not viewer.get("login"):
+            raise RuntimeError("GitHub viewer response did not include viewer.login.")
+        return viewer
+
+    def get_pull_requests(
+        self, refs: list[str], *, batch_size: int = DEFAULT_PR_BATCH_SIZE
+    ) -> dict[str, PullRequest]:
+        return cast(
+            dict[str, PullRequest],
+            aliased_batched_query(
+                refs,
+                batch_size=batch_size,
+                build_alias=_build_pr_alias,
+                parse_node=_project_pull_request,
+                post=self.graphql,
+            ),
+        )
+
+
+def graphql_api_url(github_url: str = DEFAULT_GITHUB_URL) -> str:
+    """Return the GraphQL API URL for github.com or a GitHub Enterprise host."""
+    normalized = _normalize_github_url(github_url)
+    split = urlsplit(normalized)
+    if split.hostname == "github.com":
+        return f"{split.scheme}://api.github.com/graphql"
+    return f"{normalized}/api/graphql"
+
+
+def gh_cli_token(*, github_url: str = DEFAULT_GITHUB_URL) -> str | None:
+    """Return `gh auth token`, or None when gh is unavailable/not logged in."""
+    split = urlsplit(_normalize_github_url(github_url))
+    command = ["gh", "auth", "token"]
+    if split.hostname and split.hostname != "github.com":
+        command.extend(["--hostname", split.netloc])
+    try:
+        result = subprocess.run(command, capture_output=True, text=True, timeout=5, check=False)
+    except OSError:
+        return None
+    except subprocess.SubprocessError:
+        return None
+    token = result.stdout.strip()
+    return token if result.returncode == 0 and token else None
+
+
+def _normalize_github_url(github_url: str) -> str:
+    stripped = github_url.strip().rstrip("/")
+    if "://" not in stripped:
+        stripped = f"https://{stripped}"
+    return stripped
+
+
+def parse_pr_ref(ref: str) -> tuple[str, str, int]:
+    match = PR_REF_RE.match(ref)
+    if not match:
+        raise ValueError(f"invalid GitHub PR ref: {ref!r}")
+    return match.group("owner"), match.group("repo"), int(match.group("number"))
+
+
+def pr_ref_from_url(url: str) -> str | None:
+    match = PR_URL_RE.search(url)
+    if not match:
+        return None
+    return f"{match.group('owner')}/{match.group('repo')}#{match.group('number')}"
+
+
+def _build_pr_alias(_index: int, ref: str) -> str | None:
+    try:
+        owner, repo, number = parse_pr_ref(ref)
+    except ValueError:
+        return None
+    return (
+        f"repository(owner: {json.dumps(owner)}, name: {json.dumps(repo)}) "
+        f"{{ pullRequest(number: {number}) "
+        "{ title url state createdAt mergedAt closedAt author { login } } }"
+    )
+
+
+def _project_pull_request(node: JSONDict) -> PullRequest | None:
+    pull_request = json_dict(node.get("pullRequest"))
+    if not pull_request:
+        return None
+    return {
+        "title": json_str(pull_request, "title"),
+        "url": json_str(pull_request, "url"),
+        "state": json_str(pull_request, "state"),
+        "createdAt": json_str(pull_request, "createdAt"),
+        "mergedAt": json_str(pull_request, "mergedAt"),
+        "closedAt": json_str(pull_request, "closedAt"),
+        "author": json_str(json_dict(pull_request.get("author")), "login"),
+    }

src_py_lib/clients/google_sheets.py

@@ -0,0 +1,131 @@
+"""Google Sheets API client using an already-available OAuth access token."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import cast
+
+from src_py_lib.utils.http import HTTPClient, HTTPClientError
+from src_py_lib.utils.json_types import JSONDict, json_dict, json_int, json_list, json_str
+
+SHEETS_API_URL = "https://sheets.googleapis.com/v4/spreadsheets"
+DEFAULT_ADC_FILE = Path("~/.config/gcloud/application_default_credentials.json").expanduser()
+
+
+class GoogleSheetsError(RuntimeError):
+    """Raised for Google Sheets client errors."""
+
+
+@dataclass(frozen=True)
+class LinkRun:
+    start: int
+    end: int
+    uri: str
+
+
+@dataclass(frozen=True)
+class Cell:
+    text: str
+    links: tuple[LinkRun, ...] = ()
+
+
+CellValue = str | Cell
+
+
+@dataclass
+class GoogleSheetsClient:
+    spreadsheet_id: str
+    access_token: str
+    quota_project: str | None = None
+    http: HTTPClient = field(default_factory=HTTPClient)
+
+    @classmethod
+    def from_gcloud_adc(
+        cls,
+        spreadsheet_id: str,
+        *,
+        credentials_file: Path = DEFAULT_ADC_FILE,
+        http: HTTPClient | None = None,
+    ) -> GoogleSheetsClient:
+        return cls(
+            spreadsheet_id=spreadsheet_id,
+            access_token=gcloud_adc_access_token(credentials_file),
+            quota_project=quota_project_from_adc(credentials_file),
+            http=http or HTTPClient(),
+        )
+
+    def request(self, method: str, path: str, body: JSONDict | None = None) -> JSONDict:
+        headers = {"Authorization": f"Bearer {self.access_token}"}
+        if self.quota_project:
+            headers["X-Goog-User-Project"] = self.quota_project
+        try:
+            return self.http.json(
+                method,
+                f"{SHEETS_API_URL}/{self.spreadsheet_id}{path}",
+                headers=headers,
+                json_body=body,
+            )
+        except HTTPClientError as exception:
+            raise GoogleSheetsError(
+                f"Google Sheets {method} {path} failed: {exception}"
+            ) from exception
+
+    def metadata(self) -> JSONDict:
+        return self.request("GET", "?fields=sheets.properties(sheetId,title,gridProperties)")
+
+    def validate(self) -> JSONDict:
+        """Validate spreadsheet access and return spreadsheet metadata."""
+        metadata = self.metadata()
+        if not isinstance(metadata.get("sheets"), list):
+            raise GoogleSheetsError("Google Sheets metadata response did not include sheets.")
+        return metadata
+
+    def tab_ids_by_title(self) -> dict[str, int]:
+        return {
+            json_str(properties, "title"): json_int(properties, "sheetId")
+            for sheet in json_list(self.metadata().get("sheets"))
+            if (properties := json_dict(json_dict(sheet).get("properties")))
+        }
+
+    def batch_update(self, requests: list[JSONDict]) -> JSONDict:
+        return self.request("POST", ":batchUpdate", cast(JSONDict, {"requests": requests}))
+
+
+def hyperlink_cell(url: str, text: str) -> CellValue:
+    if not url:
+        return ""
+    return Cell(text=text, links=(LinkRun(0, len(text), url),))
+
+
+def quota_project_from_adc(credentials_file: Path = DEFAULT_ADC_FILE) -> str:
+    if not credentials_file.exists():
+        raise GoogleSheetsError(f"Application Default Credentials not found at {credentials_file}.")
+    data = json_dict(json.loads(credentials_file.read_text(encoding="utf-8")))
+    quota_project = json_str(data, "quota_project_id")
+    if not quota_project:
+        raise GoogleSheetsError(f"{credentials_file} does not contain quota_project_id.")
+    return quota_project
+
+
+def gcloud_adc_access_token(credentials_file: Path = DEFAULT_ADC_FILE) -> str:
+    env = os.environ.copy()
+    env["GOOGLE_APPLICATION_CREDENTIALS"] = str(credentials_file)
+    try:
+        result = subprocess.run(
+            ["gcloud", "auth", "application-default", "print-access-token"],
+            env=env,
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError) as exception:
+        raise GoogleSheetsError("Could not run gcloud to fetch an ADC access token.") from exception
+    token = result.stdout.strip()
+    if result.returncode != 0 or not token:
+        raise GoogleSheetsError(result.stderr.strip() or "gcloud did not return an access token.")
+    return token