asyncgh 0.1.0__py3-none-any.whl

asyncgh/__init__.py

@@ -0,0 +1,42 @@
+"""asyncgh -- the GitHub REST API transport shared by repo-admin's scripts.
+
+Auth via the token `gh` already holds, one shared async client, raw and
+raise-on-error request helpers, `Link`-header pagination, and thin wrappers
+over the few endpoints more than one script needs (account-wide repo
+listing, Actions secrets). No config-file loading, no repo filtering -- those
+stay with the caller.
+"""
+
+from __future__ import annotations
+
+from .client import (
+    API_BASE,
+    GhError,
+    aclose_client,
+    api_json,
+    api_request,
+    error_message,
+    graphql,
+    paginated,
+)
+from .endpoints import (
+    encrypt_secret_value,
+    fetch_repos_json,
+    public_repos_json,
+    set_repo_secret,
+)
+
+__all__ = [
+    "API_BASE",
+    "GhError",
+    "aclose_client",
+    "api_json",
+    "api_request",
+    "encrypt_secret_value",
+    "error_message",
+    "fetch_repos_json",
+    "graphql",
+    "paginated",
+    "public_repos_json",
+    "set_repo_secret",
+]

asyncgh/client.py

@@ -0,0 +1,242 @@
+"""GitHub REST API transport: auth, the shared async client, and the
+request / pagination helpers every endpoint wrapper is built on.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import subprocess
+from typing import Any
+
+import httpx2
+import stamina
+
+API_BASE = "https://api.github.com"
+
+# Retry transport failures and transient statuses (429 + 5xx). `attempts` is
+# total tries, so MAX_RETRIES=3 means one call plus three retries. There is no
+# wall-clock timeout: GitHub's Retry-After on a secondary rate limit is often
+# a minute or more, and honouring it is the whole point.
+MAX_RETRIES = int(os.environ.get("GH_MAX_RETRIES", "3"))
+RETRY_STATUSES = frozenset({429, 500, 502, 503, 504})
+RETRY_WAIT_INITIAL = 1.0
+RETRY_WAIT_MAX = 60.0
+RETRY_WAIT_JITTER = 1.0
+
+
+class GhError(RuntimeError):
+    """A GitHub API call -- or a caller's worker function -- failed
+    unexpectedly.
+
+    status_code is set for HTTP errors raised by api_json(), so callers can
+    branch on the real status code (e.g. 403 vs 404) instead of
+    string-matching an error message. Plain RuntimeError rather than a
+    reconcilekit.ReconcileError subclass -- asyncgh has no dependency on
+    reconcilekit, so it stays installable standalone; reconcilekit's own
+    run_parallel(..., error_cls=) only requires type[Exception], so GhError
+    still works there unchanged.
+    """
+
+    def __init__(self, message: str, *, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+def _auth_token() -> str:
+    """Reads the token `gh` already has -- keychain storage, SSO, and 2FA are
+    already solved by `gh auth login`, so this reuses that instead of
+    managing a separate credential.
+    """
+    result = subprocess.run(
+        ["gh", "auth", "token"], capture_output=True, text=True, check=False
+    )
+    if result.returncode != 0:
+        raise GhError(f"gh auth token failed: {result.stderr.strip()}")
+    return result.stdout.strip()
+
+
+_client: httpx2.AsyncClient | None = None
+_client_lock = asyncio.Lock()
+
+
+async def _get_client() -> httpx2.AsyncClient:
+    # One shared AsyncClient rather than one per thread: there's no thread
+    # pool, and gh auth token only needs to be paid once per process.
+    global _client
+    if _client is None:
+        async with _client_lock:
+            if _client is None:
+                _client = httpx2.AsyncClient(
+                    headers={
+                        "Authorization": f"Bearer {_auth_token()}",
+                        "Accept": "application/vnd.github+json",
+                        "X-GitHub-Api-Version": "2022-11-28",
+                    },
+                    timeout=30,
+                )
+    return _client
+
+
+async def aclose_client() -> None:
+    global _client
+    if _client is not None:
+        await _client.aclose()
+        _client = None
+
+
+def _should_retry(exc: Exception) -> bool | float:
+    """stamina backoff hook. A `Retry-After` header (GitHub sends one on
+    secondary rate limits) sets the exact wait; otherwise transport errors
+    and RETRY_STATUSES responses retry on stamina's default backoff, and
+    everything else propagates.
+    """
+    response = getattr(exc, "response", None)
+    if response is not None:
+        header = response.headers.get("retry-after")
+        if header:
+            try:
+                return float(header)
+            except ValueError:
+                pass
+        return response.status_code in RETRY_STATUSES
+    return isinstance(exc, httpx2.TransportError)
+
+
+async def api_request(
+    method: str, path: str, *, json: Any = None, params: dict | None = None
+) -> httpx2.Response:
+    """Makes one GitHub REST API call and returns the raw Response --
+    callers decide what a given status means for their endpoint (e.g. a 404
+    means "feature disabled" for vulnerability-alerts but "not found"
+    everywhere else). Raises GhError only for genuine transport failures
+    (DNS, timeout, connection reset); HTTP error statuses are returned, not
+    raised.
+
+    Transport errors and transient statuses (429, 5xx) are retried up to
+    MAX_RETRIES times, honouring `Retry-After`. GitHub's writes here are
+    idempotent (secret PUTs replace), so retrying any method is safe.
+    """
+    url = path if path.startswith("http") else f"{API_BASE}{path}"
+    http = await _get_client()
+    try:
+        async for attempt in stamina.retry_context(
+            on=_should_retry,
+            attempts=MAX_RETRIES + 1,
+            timeout=None,
+            wait_initial=RETRY_WAIT_INITIAL,
+            wait_max=RETRY_WAIT_MAX,
+            wait_jitter=RETRY_WAIT_JITTER,
+        ):
+            with attempt:
+                try:
+                    response = await http.request(method, url, json=json, params=params)
+                except httpx2.TransportError:
+                    raise
+                except httpx2.HTTPError as exc:
+                    raise GhError(str(exc)) from exc
+                if response.status_code in RETRY_STATUSES:
+                    response.raise_for_status()
+                return response
+    except httpx2.HTTPStatusError as exc:
+        return exc.response  # retryable status, retries spent -- let the caller judge
+    except httpx2.TransportError as exc:
+        raise GhError(str(exc)) from exc
+    raise GhError("api_request retry loop exited without a response")  # unreachable
+
+
+def error_message(response: httpx2.Response) -> str:
+    """Extracts GitHub's own `message` field from an error response body,
+    falling back to the raw response text if the body isn't JSON.
+    """
+    try:
+        return response.json().get("message", response.text)
+    except ValueError:
+        return response.text
+
+
+async def api_json(
+    method: str, path: str, *, json: Any = None, params: dict | None = None
+) -> dict:
+    """Like api_request, but raises GhError (with status_code and GitHub's
+    own error message) on any non-2xx response, and returns the parsed JSON
+    body -- or {} for a body-less response like 204 No Content -- on success.
+    """
+    response = await api_request(method, path, json=json, params=params)
+    if not response.is_success:
+        raise GhError(error_message(response), status_code=response.status_code)
+    return response.json() if response.content else {}
+
+
+class _GraphQLRateLimited(Exception):
+    """Internal marker: GraphQL answered 200 with errors[].type ==
+    RATE_LIMITED, which api_request's transport/5xx retry never sees since
+    it only looks at the HTTP status. Retried at this layer instead.
+    """
+
+
+async def graphql(query: str, variables: dict | None = None) -> dict:
+    """Runs one GraphQL query and returns its `data` object.
+
+    GraphQL always answers HTTP 200, even for query errors, so success lives
+    in the body: `errors` present (with `data` null or partial) raises
+    GhError with the joined messages -- callers have no partial-data story,
+    so partial loss is worse than a loud failure. RATE_LIMITED errors retry
+    (stamina, same backoff as api_request) since they're the one transient
+    GraphQL failure mode; other GraphQL errors (bad query, not found) are
+    not transient and raise immediately.
+    """
+    try:
+        async for attempt in stamina.retry_context(
+            on=lambda exc: isinstance(exc, _GraphQLRateLimited),
+            attempts=MAX_RETRIES + 1,
+            timeout=None,
+            wait_initial=RETRY_WAIT_INITIAL,
+            wait_max=RETRY_WAIT_MAX,
+            wait_jitter=RETRY_WAIT_JITTER,
+        ):
+            with attempt:
+                response = await api_request(
+                    "POST",
+                    "/graphql",
+                    json={"query": query, "variables": variables or {}},
+                )
+                if not response.is_success:
+                    raise GhError(
+                        error_message(response), status_code=response.status_code
+                    )
+                body = response.json()
+                errors = body.get("errors")
+                if errors:
+                    if any(error.get("type") == "RATE_LIMITED" for error in errors):
+                        raise _GraphQLRateLimited(
+                            "; ".join(
+                                error.get("message", str(error)) for error in errors
+                            )
+                        )
+                    raise GhError(
+                        "; ".join(error.get("message", str(error)) for error in errors)
+                    )
+                return body["data"]
+    except _GraphQLRateLimited as exc:
+        raise GhError(str(exc)) from exc
+    raise GhError("graphql retry loop exited without a response")  # unreachable
+
+
+async def paginated(
+    method: str, path: str, *, params: dict | None = None
+) -> list[dict]:
+    """Follows GitHub's `Link: rel="next"` header, concatenating every page's
+    JSON array into one list.
+    """
+    items = []
+    url = path
+    query = params
+    while url:
+        response = await api_request(method, url, params=query)
+        if not response.is_success:
+            raise GhError(error_message(response), status_code=response.status_code)
+        items.extend(response.json())
+        url = response.links.get("next", {}).get("url")
+        query = None  # the "next" link already carries the full query string
+    return items

asyncgh/endpoints.py

@@ -0,0 +1,62 @@
+"""Thin wrappers over the handful of GitHub REST endpoints shared across
+repo-admin's scripts: account-wide repo listing and Actions secrets.
+"""
+
+from __future__ import annotations
+
+import base64
+
+from nacl import encoding, public
+
+from .client import api_json, paginated
+
+
+async def fetch_repos_json(owner: str) -> list[dict]:
+    """Lists every repo for `owner`. When `owner` is the authenticated `gh`
+    user, uses /user/repos so private repos are included; otherwise falls
+    back to /users/{owner}/repos, which only ever returns public repos.
+    """
+    viewer = (await api_json("GET", "/user")).get("login")
+    if owner == viewer:
+        return await paginated(
+            "GET", "/user/repos", params={"affiliation": "owner", "per_page": "100"}
+        )
+    return await paginated("GET", f"/users/{owner}/repos", params={"per_page": "100"})
+
+
+async def public_repos_json(owner: str) -> list[dict]:
+    """Lists `owner`'s public repos only, via /users/{owner}/repos -- unlike
+    fetch_repos_json, this always excludes private repos even when `owner`
+    is the authenticated user, so no /user call is needed to branch on it.
+    """
+    return await paginated("GET", f"/users/{owner}/repos", params={"per_page": "100"})
+
+
+def encrypt_secret_value(public_key_b64: str, value: str) -> str:
+    """Encrypts `value` for GitHub's Actions secrets API using a repo's
+    public key, per GitHub's documented libsodium sealed-box scheme.
+    """
+    public_key = public.PublicKey(
+        public_key_b64.encode("utf-8"), encoding.Base64Encoder
+    )
+    encrypted = public.SealedBox(public_key).encrypt(value.encode("utf-8"))
+    return base64.b64encode(encrypted).decode("utf-8")
+
+
+async def set_repo_secret(
+    owner: str, repo_name: str, secret_name: str, value: str
+) -> None:
+    """Sets one repo's Actions secret via GitHub's REST API: fetches the
+    repo's current public key, encrypts `value` for it, and PUTs the
+    result. The plaintext value never leaves this process -- it's encrypted
+    in memory before the request body is built.
+    """
+    key_data = await api_json(
+        "GET", f"/repos/{owner}/{repo_name}/actions/secrets/public-key"
+    )
+    encrypted_value = encrypt_secret_value(key_data["key"], value)
+    await api_json(
+        "PUT",
+        f"/repos/{owner}/{repo_name}/actions/secrets/{secret_name}",
+        json={"encrypted_value": encrypted_value, "key_id": key_data["key_id"]},
+    )

asyncgh-0.1.0.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.5
+Name: asyncgh
+Version: 0.1.0
+Summary: Minimal async GitHub REST + GraphQL transport: auth, retry, pagination -- no generated models
+Project-URL: Homepage, https://github.com/hugoh/gh-workflows/tree/main/asyncgh
+Project-URL: Issues, https://github.com/hugoh/gh-workflows/issues
+Project-URL: Repository, https://github.com/hugoh/gh-workflows
+Author: Hugo Haas
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx2>=2.10
+Requires-Dist: pynacl>=1.5
+Requires-Dist: stamina>=25.2
+Description-Content-Type: text/markdown
+
+# asyncgh
+
+A minimal async GitHub API transport — the plumbing an account-wide config
+tool needs before any of its domain logic: authentication, a shared
+connection, retrying error handling, REST pagination, and GraphQL.
+
+There is no client object to construct and no config. It reads the token
+`gh auth login` already stored, keeps one process-wide `httpx2.AsyncClient`,
+and exposes plain functions.
+
+## Why not PyGithub / githubkit / gidgethub / fast.ai's `ghapi`?
+
+| Library | Async | Shape | Trade-off vs `asyncgh` |
+|---|---|---|---|
+| [PyGithub](https://github.com/PyGithub/PyGithub) | no | typed objects | sync-only — a poor fit for anything doing concurrent, fan-out API calls |
+| [githubkit](https://github.com/yanyongyu/githubkit) | yes | Pydantic models, generated from GitHub's OpenAPI spec | full, typed surface, but pulls in codegen'd models and `pydantic`; heavier than most scripts need |
+| [gidgethub](https://github.com/gidgethub/gidgethub) | yes | sans-I/O, bring-your-own HTTP client | closest in spirit, but leaves auth, retry, and the client itself to the caller |
+| [ghapi](https://ghapi.fast.ai) (fast.ai) | no | OpenAPI-generated, dynamic attribute access | lightweight like this package, but sync-only |
+| **asyncgh** | yes | plain `dict`s, ~200 lines | no generated models, no schema — you read GitHub's own docs and index the JSON; retry and GraphQL are built in, not bolted on |
+
+If you want typed responses and full API coverage, use `githubkit`. If you
+want an async client with almost no code between you and the wire — a script
+firing dozens of concurrent calls that reads a handful of fields per
+response — that's what this is for.
+
+## API
+
+Full API reference, generated from the docstrings:
+[hugoh.github.io/gh-workflows/asyncgh](https://hugoh.github.io/gh-workflows/asyncgh/)
+(rebuilt on every push that touches this package -- see
+`.github/workflows/docs.yml`).
+
+## Auth
+
+`Authorization: Bearer $(gh auth token)`, resolved lazily on the first
+request and cached for the process. `gh` must be installed and logged in.
+
+## Retries
+
+`api_request` retries transport errors (DNS, timeout, reset) and transient
+statuses — 429, 500, 502, 503, 504 — via [`stamina`](https://stamina.hynek.me).
+A `Retry-After` header sets the exact wait; otherwise exponential backoff with
+jitter. `GH_MAX_RETRIES` (default 3) caps the retries; there is no wall-clock
+timeout, so a minute-long `Retry-After` is honoured in full. When the retries
+are spent the last response is returned unchanged for the caller to judge.
+
+`graphql()` reuses that same retry for transport errors and 429/5xx, plus one
+addition: GitHub answers GraphQL rate limiting with HTTP 200 and an
+`errors[].type == "RATE_LIMITED"` body, which `api_request`'s status-based
+retry never sees -- `graphql()` retries that case itself, on the same
+backoff. Any other GraphQL error (bad query, not found) is not transient and
+raises immediately.
+
+## Consumers
+
+`repo-admin/` (in this repo) uses it for every account-wide GitHub command --
+`repo_admin.py`'s `sync` subcommands and `activity.py` via `api_request`/
+`api_json`/pagination; `digest.py` (wrapped by `../digest-action/`) is the
+one driving `graphql()`.

asyncgh-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+asyncgh/__init__.py,sha256=iHHjQCUvKQUZ5sz8obhWTOS_p8XRrq2kx-oLMB6Su5o,957
+asyncgh/client.py,sha256=L7td1RNmfqsEhFThkRTuGlGXDhx9710kx8d-nkMhaWE,9350
+asyncgh/endpoints.py,sha256=FEDdEhRguDuHAmJRk1cec12pJA-R9Wd7SV7--yveAI0,2429
+asyncgh/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+asyncgh-0.1.0.dist-info/METADATA,sha256=jG4Uc7q9YtZkYflQ7ndXxmn4OEZ8w9aACAdtsaM6twY,4207
+asyncgh-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+asyncgh-0.1.0.dist-info/licenses/LICENSE,sha256=qCv-aayDkFcB09IGjnNETtrZ31NOA1tdCq4IJ7nZObc,1066
+asyncgh-0.1.0.dist-info/RECORD,,

asyncgh-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

asyncgh-0.1.0.dist-info/licenses/LICENSE

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