ghost-api-cli 0.2.0__py3-none-any.whl

ghost_api/generator/templates/client.py.j2

@@ -0,0 +1,518 @@
+"""{{ spec.class_name }}: a typed Python client for {{ spec.domain }}.
+
+Generated by Ghost API {{ version }} on {{ generated_on }} from the site's own traffic.
+Two clients with the same methods: `{{ spec.class_name }}` (regular code) and
+`{{ spec.async_class }}` (asyncio). Errors are typed: catch `{{ spec.error_class }}` for
+any failure, or `{{ spec.error_classes.not_found }}`, `{{ spec.error_classes.auth }}`,
+`{{ spec.error_classes.rate_limit }}` or `{{ spec.error_classes.server }}` for one kind.
+
+This is an unofficial client for a website's internal API. It can change without
+notice, and the site's terms of service still apply. Re-run `ghost-api run` to refresh.
+"""
+
+from __future__ import annotations
+
+import asyncio
+{% if spec.credentials %}
+import os
+{% endif %}
+import json
+import time
+{% set paged = spec.methods | selectattr("page_param") | list %}
+{% if paged %}
+from collections.abc import AsyncIterator, Iterator
+{% endif %}
+from typing import Any
+{% if spec.methods | map(attribute="params") | sum(start=[]) | selectattr("location", "equalto", "path") | list %}
+from urllib.parse import quote
+{% endif %}
+
+import httpx
+from pydantic import BaseModel, TypeAdapter
+
+{% if spec.client_imports and packaged %}
+from .models import (
+{% for name in spec.client_imports %}
+    {{ name }},
+{% endfor %}
+)
+{% elif spec.client_imports %}
+try:
+    from .models import (
+{% for name in spec.client_imports %}
+        {{ name }},
+{% endfor %}
+    )
+except ImportError:  # used as loose files rather than a package
+    from models import (  # type: ignore[no-redef, unused-ignore]
+{% for name in spec.client_imports %}
+        {{ name }},
+{% endfor %}
+    )
+{% endif %}
+
+__all__ = [
+    "{{ spec.class_name }}",
+    "{{ spec.async_class }}",
+    "{{ spec.error_class }}",
+{% for name in spec.error_classes.values() %}
+    "{{ name }}",
+{% endfor %}
+]
+
+USER_AGENT = "{{ user_agent }}"
+RETRY_STATUSES = {429, 500, 502, 503, 504}
+# Guards some sites put before JSON so other sites can't read it (Google: ")]}'").
+JSON_GUARDS = (")]}'", "while(1);", "for(;;);")
+# Environment variable for each credential.
+CREDENTIAL_ENV: dict[str, str] = {{ spec.credentials | env_map | pyrepr }}
+
+
+class {{ spec.error_class }}(Exception):
+    """An API call failed. `status` is the HTTP status (0 for network errors)."""
+
+    def __init__(self, status: int, message: str, body: Any = None) -> None:
+        super().__init__(f"HTTP {status}: {message}" if status else message)
+        self.status = status
+        self.body = body
+
+
+class {{ spec.error_classes.auth }}({{ spec.error_class }}):
+    """401 or 403: a credential is missing, wrong or expired."""
+
+
+class {{ spec.error_classes.not_found }}({{ spec.error_class }}):
+    """404: no such resource (or the site moved this endpoint)."""
+
+
+class {{ spec.error_classes.rate_limit }}({{ spec.error_class }}):
+    """429 after all retries: slow down (see `max_requests_per_second`)."""
+
+
+class {{ spec.error_classes.server }}({{ spec.error_class }}):
+    """5xx after all retries: the site has a problem."""
+
+
+def _error_for(status: int, message: str, body: Any = None) -> {{ spec.error_class }}:
+    kind: type[{{ spec.error_class }}] = {{ spec.error_class }}
+    if status in (401, 403):
+        kind = {{ spec.error_classes.auth }}
+    elif status == 404:
+        kind = {{ spec.error_classes.not_found }}
+    elif status == 429:
+        kind = {{ spec.error_classes.rate_limit }}
+    elif status >= 500:
+        kind = {{ spec.error_classes.server }}
+    return kind(status, message, body)
+{% macro signature(m) %}
+        self,
+{% for p in m.required %}
+        {{ p.name }}: {{ p.annotation }},
+{% endfor %}
+{% if m.optional %}
+        *,
+{% for p in m.optional %}
+        {{ p.name }}: {{ p.annotation }} = {{ p.default_literal }},
+{% endfor %}
+{% endif %}
+{% endmacro %}
+{% macro request_args(m) %}
+            "{{ m.http_method }}",
+            {% if m.host %}"https://{{ m.host }}"{% else %}self.base_url{% endif %} + {{ m | path_expr }},
+            params={
+{% for p in m.by_location('query') %}
+                {{ p.wire | pyrepr }}: {{ p.value_expr }},
+{% endfor %}
+{% for c in m | creds(spec, 'query') %}
+                {{ c.wire | pyrepr }}: self._credential({{ c.arg | pyrepr }}),
+{% endfor %}
+            },
+{% if m.graphql %}
+            json={
+{% for key, value in m.graphql.items() %}
+                {{ key | pyrepr }}: {{ value | pyrepr }},
+{% endfor %}
+                "variables": _compact({
+{% for p in m.by_location('variable') %}
+                    {{ p.wire | pyrepr }}: {{ p.value_expr }},
+{% endfor %}
+                }),
+            },
+{% elif m.by_location('body') %}
+            json={
+{% for p in m.by_location('body') %}
+                {{ p.wire | pyrepr }}: {{ p.value_expr }},
+{% endfor %}
+            },
+{% endif %}
+            headers={
+{% for name, value in m.headers.items() %}
+                {{ name | pyrepr }}: {{ value | pyrepr }},
+{% endfor %}
+{% for c in m | creds(spec, 'header') %}
+                {{ c.wire | pyrepr }}: self._credential({{ c.arg | pyrepr }}),
+{% endfor %}
+            },
+{% endmacro %}
+{% macro iter_signature(m) %}
+{% set pp = m.page_param %}
+        self,
+{% for p in m.required %}
+        {{ p.name }}: {{ p.annotation }},
+{% endfor %}
+        *,
+{% for p in m.optional if p.name != pp.name %}
+        {{ p.name }}: {{ p.annotation }} = {{ p.default_literal }},
+{% endfor %}
+        start: {{ pp.annotation }} = {{ pp.default_literal }},
+        max_pages: int | None = None,
+{% endmacro %}
+{% macro page_loop(m, aw) %}
+{% set pp = m.page_param %}
+        """Yield each page of `{{ m.name }}()` until the results run out.
+
+        Pages by {{ m.pagination.style }} using `{{ pp.wire }}`. Set `max_pages` to stop early.
+        """
+        position: Any = start
+        previous: list[Any] | None = None
+        pages = 0
+        while max_pages is None or pages < max_pages:
+            page = {{ aw }}self.{{ m.name }}(
+{% for p in m.required %}
+                {{ p.name }},
+{% endfor %}
+{% for p in m.optional if p.name != pp.name %}
+                {{ p.name }}={{ p.name }},
+{% endfor %}
+                {{ pp.name }}=position,
+            )
+            data = _dump(page)
+            items = _find_items(data)
+            if not items or items == previous:
+                return
+            yield page
+            pages += 1
+            if _has_more(data) is False:
+                return
+            previous = items
+{% if m.pagination.style == "cursor" %}
+            position = _next_cursor(data)
+            if position is None:
+                return
+{% elif m.pagination.style == "offset" %}
+            position = (position or 0) + len(items)
+{% else %}
+            position = (position or 0) + 1
+{% endif %}
+{% endmacro %}
+
+
+class _Base:
+    BASE_URL = "{{ spec.base_url }}"
+
+    def __init__(
+        self,
+        base_url: str,
+{% for c in spec.credentials %}
+        {{ c.arg }}: str | None,
+{% endfor %}
+        max_requests_per_second: float,
+        max_retries: int,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+{% for c in spec.credentials %}
+        self.{{ c.arg }} = {{ c.arg }} or os.environ.get("{{ c.env }}")
+{% endfor %}
+        self._interval = 1.0 / max_requests_per_second if max_requests_per_second > 0 else 0.0
+        self._last_request = 0.0
+        self._max_retries = max_retries
+
+    def _credential(self, name: str) -> str:
+        value: str | None = getattr(self, name)
+        if not value:
+            env = CREDENTIAL_ENV.get(name, "")
+            raise {{ spec.error_classes.auth }}(0, f"Missing credential: pass {name}=... or set {env}")
+        return value
+
+    def _wait(self) -> float:
+        """Seconds to wait before the next request, to keep to the rate limit."""
+        wait = self._last_request + self._interval - time.monotonic()
+        self._last_request = time.monotonic() + max(wait, 0.0)
+        return max(wait, 0.0)
+
+    def _retry_delay(self, response: httpx.Response | None, attempt: int) -> float | None:
+        """How long to wait before retrying, or None to stop retrying."""
+        if attempt >= self._max_retries:
+            return None
+        if response is None:  # network error
+            return float(2**attempt)
+        if response.status_code not in RETRY_STATUSES:
+            return None
+        retry_after = response.headers.get("retry-after", "")
+        return float(retry_after) if retry_after.isdigit() else float(2**attempt)
+
+    @staticmethod
+    def _result(response: httpx.Response) -> Any:
+        if response.status_code >= 400:
+            raise _error_for(response.status_code, response.reason_phrase, _safe_json(response))
+        try:
+            return _parse_json(response.text)
+        except ValueError as exc:
+            raise {{ spec.error_class }}(
+                response.status_code, "response is not JSON", response.text[:500]
+            ) from exc
+
+
+class {{ spec.class_name }}(_Base):
+    """Client for {{ spec.domain }}.
+
+    Use it as a context manager so the connection is closed:
+
+        with {{ spec.class_name }}() as api:
+{% if spec.methods %}
+            result = api.{{ spec.methods[0].name }}({% for p in spec.methods[0].required %}{{ p.name }}={{ p.example or '...' }}{% if not loop.last %}, {% endif %}{% endfor %})
+{% endif %}
+{% if spec.credentials %}
+
+    Credentials are read from these environment variables unless passed in:
+{% for c in spec.credentials %}
+        {{ c.arg }}: {{ c.env }}
+{% endfor %}
+{% endif %}
+
+    Pass `http_client=httpx.Client(event_hooks=...)` to log or change every request.
+    """
+
+    def __init__(
+        self,
+        base_url: str = _Base.BASE_URL,
+        *,
+{% for c in spec.credentials %}
+        {{ c.arg }}: str | None = None,
+{% endfor %}
+        timeout: float = 30.0,
+        max_requests_per_second: float = 1.0,
+        max_retries: int = 3,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        super().__init__(
+            base_url,
+{% for c in spec.credentials %}
+            {{ c.arg }},
+{% endfor %}
+            max_requests_per_second,
+            max_retries,
+        )
+        self._http = http_client or httpx.Client(
+            timeout=timeout, headers={"User-Agent": USER_AGENT, "Accept": "application/json"}
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> {{ spec.class_name }}:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+{% for m in spec.methods %}
+
+    def {{ m.name }}(
+{{ signature(m) }}    ) -> {{ m.response_type }}:
+        """{{ m.summary | doc }}
+
+        `{{ m.http_method }} {{ (m.host and 'https://' ~ m.host) or spec.base_url }}{{ m.path }}`
+        """
+        data = self._request(
+{{ request_args(m) }}        )
+        return TypeAdapter({{ m.response_type }}).validate_python(data)
+{% if m.page_param %}
+
+    def iter_{{ m.name }}(
+{{ iter_signature(m) }}    ) -> Iterator[{{ m.response_type }}]:
+{{ page_loop(m, "") }}{% endif %}
+{% endfor %}
+
+    def _request(
+        self,
+        method: str,
+        url: str,
+        params: dict[str, Any],
+        headers: dict[str, str],
+        json: dict[str, Any] | None = None,
+    ) -> Any:
+        params = {k: v for k, v in params.items() if v is not None}
+        if json is not None:
+            json = {k: v for k, v in json.items() if v is not None}
+        attempt = 0
+        while True:
+            time.sleep(self._wait())
+            try:
+                response = self._http.request(
+                    method, url, params=params, headers=headers, json=json
+                )
+            except httpx.HTTPError as exc:
+                delay = self._retry_delay(None, attempt)
+                if delay is None:
+                    raise {{ spec.error_class }}(0, f"network error: {exc}") from exc
+            else:
+                delay = self._retry_delay(response, attempt)
+                if delay is None:
+                    return self._result(response)
+            time.sleep(delay)
+            attempt += 1
+
+
+class {{ spec.async_class }}(_Base):
+    """The same client for asyncio:
+
+        async with {{ spec.async_class }}() as api:
+{% if spec.methods %}
+            result = await api.{{ spec.methods[0].name }}({% for p in spec.methods[0].required %}{{ p.name }}={{ p.example or '...' }}{% if not loop.last %}, {% endif %}{% endfor %})
+{% endif %}
+
+    The rate limit applies per client: share one client between tasks.
+    """
+
+    def __init__(
+        self,
+        base_url: str = _Base.BASE_URL,
+        *,
+{% for c in spec.credentials %}
+        {{ c.arg }}: str | None = None,
+{% endfor %}
+        timeout: float = 30.0,
+        max_requests_per_second: float = 1.0,
+        max_retries: int = 3,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        super().__init__(
+            base_url,
+{% for c in spec.credentials %}
+            {{ c.arg }},
+{% endfor %}
+            max_requests_per_second,
+            max_retries,
+        )
+        self._http = http_client or httpx.AsyncClient(
+            timeout=timeout, headers={"User-Agent": USER_AGENT, "Accept": "application/json"}
+        )
+        self._lock = asyncio.Lock()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> {{ spec.async_class }}:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+{% for m in spec.methods %}
+
+    async def {{ m.name }}(
+{{ signature(m) }}    ) -> {{ m.response_type }}:
+        """{{ m.summary | doc }}"""
+        data = await self._request(
+{{ request_args(m) }}        )
+        return TypeAdapter({{ m.response_type }}).validate_python(data)
+{% if m.page_param %}
+
+    async def iter_{{ m.name }}(
+{{ iter_signature(m) }}    ) -> AsyncIterator[{{ m.response_type }}]:
+{{ page_loop(m, "await ") }}{% endif %}
+{% endfor %}
+
+    async def _request(
+        self,
+        method: str,
+        url: str,
+        params: dict[str, Any],
+        headers: dict[str, str],
+        json: dict[str, Any] | None = None,
+    ) -> Any:
+        params = {k: v for k, v in params.items() if v is not None}
+        if json is not None:
+            json = {k: v for k, v in json.items() if v is not None}
+        attempt = 0
+        while True:
+            async with self._lock:  # one request at a time keeps the rate limit honest
+                await asyncio.sleep(self._wait())
+            try:
+                response = await self._http.request(
+                    method, url, params=params, headers=headers, json=json
+                )
+            except httpx.HTTPError as exc:
+                delay = self._retry_delay(None, attempt)
+                if delay is None:
+                    raise {{ spec.error_class }}(0, f"network error: {exc}") from exc
+            else:
+                delay = self._retry_delay(response, attempt)
+                if delay is None:
+                    return self._result(response)
+            await asyncio.sleep(delay)
+            attempt += 1
+
+
+def _compact(values: dict[str, Any]) -> dict[str, Any]:
+    """GraphQL variables without the ones left out (None)."""
+    return {k: v for k, v in values.items() if v is not None}
+
+
+def _parse_json(text: str) -> Any:
+    stripped = text.lstrip()
+    for guard in JSON_GUARDS:
+        if stripped.startswith(guard):
+            stripped = stripped[len(guard) :].lstrip(",").lstrip()
+            break
+    return json.loads(stripped)
+
+
+def _safe_json(response: httpx.Response) -> Any:
+    try:
+        return _parse_json(response.text)
+    except ValueError:
+        return response.text[:500]
+
+
+def _dump(value: Any) -> Any:
+    if isinstance(value, BaseModel):
+        return value.model_dump(by_alias=True)
+    if isinstance(value, list):
+        return [_dump(v) for v in value]
+    return value
+
+
+def _find_items(data: Any, depth: int = 0) -> list[Any] | None:
+    """The main list of records in a response."""
+    if isinstance(data, list):
+        return data
+    if not isinstance(data, dict) or depth > 2:
+        return None
+    best: list[Any] | None = None
+    for value in data.values():
+        found = value if isinstance(value, list) else _find_items(value, depth + 1)
+        if found is not None and (best is None or len(found) > len(best)):
+            best = found
+    return best
+
+
+def _has_more(data: Any) -> bool | None:
+    if isinstance(data, dict):
+        for key in ("has_next", "hasNext", "has_more", "hasMore"):
+            if isinstance(data.get(key), bool):
+                return bool(data[key])
+    return None
+
+
+def _next_cursor(data: Any) -> str | None:
+    if not isinstance(data, dict):
+        return None
+    places = [data] + [data[k] for k in ("meta", "pagination", "paging", "pageInfo", "links")
+                       if isinstance(data.get(k), dict)]
+    for place in places:
+        for key in ("next_cursor", "nextCursor", "cursor", "next", "after", "endCursor",
+                    "next_page_token", "nextPageToken"):
+            value = place.get(key)
+            if isinstance(value, (str, int)) and not isinstance(value, bool) and str(value):
+                return str(value)
+    return None

ghost_api/generator/templates/client.test.ts.j2

@@ -0,0 +1,106 @@
+/**
+ * Tests for {{ spec.class_name }} (generated by Ghost API {{ version }}).
+ *
+ * Run with: node --test {{ module }}.test.ts   (Node 23.6+ runs TypeScript directly)
+ *
+ * By default they replay replies recorded from {{ spec.domain }} (cassettes.json): offline,
+ * fast and the same every time, so they fit CI. With GHOST_API_LIVE=1 they call the real
+ * API, slowly (1 request per second); a failure then usually means the site changed its API.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, readFileSync } from "node:fs";
+import { {{ spec.class_name }} } from "./{{ module }}.ts";
+
+interface Reply {
+  method: string;
+  path: string;
+  path_regex: string;
+  query: Record<string, string>;
+  operation: string | null;
+  status: number;
+  content_type: string;
+  body: string;
+}
+
+const CASSETTES = new URL("./cassettes.json", import.meta.url);
+const LIVE = process.env.GHOST_API_LIVE === "1" || !existsSync(CASSETTES);
+const REPLIES: Reply[] = LIVE ? [] : JSON.parse(readFileSync(CASSETTES, "utf-8")).replies;
+
+/** The recorded reply closest to a request: same path first, then query values. */
+async function replay(input: URL | RequestInfo, init?: RequestInit): Promise<Response> {
+  const url = new URL(String(input));
+  const method = (init?.method ?? "GET").toUpperCase();
+  let operation: string | null = null;
+  if (typeof init?.body === "string") {
+    try {
+      operation = JSON.parse(init.body).operationName ?? null;
+    } catch {
+      operation = null;
+    }
+  }
+  const found = REPLIES.filter(
+    (r) =>
+      r.method === method &&
+      new RegExp(`^${r.path_regex}$`).test(url.pathname) &&
+      (operation === null || r.operation === null || r.operation === operation),
+  );
+  if (found.length === 0) {
+    const error = `no recorded reply for ${method} ${url.pathname}`;
+    return new Response(JSON.stringify({ error }), { status: 404 });
+  }
+  const score = (r: Reply): number[] => [
+    r.path === url.pathname ? 1 : 0,
+    Object.entries(r.query).filter(([k, v]) => url.searchParams.get(k) === v).length,
+    -Math.abs(Object.keys(r.query).length - [...url.searchParams.keys()].length),
+  ];
+  const better = (a: number[], b: number[]): boolean => {
+    for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return a[i] > b[i];
+    return false;
+  };
+  const best = found.reduce((a, b) => (better(score(b), score(a)) ? b : a));
+  return new Response(best.body, { status: best.status, headers: { "content-type": best.content_type } });
+}
+
+const api = LIVE
+  ? new {{ spec.class_name }}()
+  : new {{ spec.class_name }}({
+{% for c in spec.credentials %}
+      {{ c.arg | camel }}: "offline-placeholder",
+{% endfor %}
+      fetch: replay as typeof fetch,
+      maxRequestsPerSecond: 0,
+    });
+{% for m in spec.methods if m.testable %}
+
+test("test_{{ m.name }}", async (t) => {
+{% for c in m | creds(spec, 'any') %}
+  if (LIVE && !process.env[{{ c.env | json }}]) {
+    t.skip("set {{ c.env }} to run this test against the live API");
+    return;
+  }
+{% endfor %}
+  const result = await api.{{ m.name | camel }}({% for p in m.required %}{{ p.example | js }}{% if not loop.last %}, {% endif %}{% endfor %});
+  assert.ok(result !== null && result !== undefined);
+});
+{% if m.page_param %}
+
+test("test_iter_{{ m.name }}", async (t) => {
+{% for c in m | creds(spec, 'any') %}
+  if (LIVE && !process.env[{{ c.env | json }}]) {
+    t.skip("set {{ c.env }} to run this test against the live API");
+    return;
+  }
+{% endfor %}
+  const pages = [];
+  for await (const page of api.iter{{ (m.name | camel)[:1] | upper }}{{ (m.name | camel)[1:] }}({% for p in m.required %}{{ p.example | js }}, {% endfor %}{ maxPages: 2 })) {
+    pages.push(page);
+  }
+  assert.ok(pages.length >= 1);
+});
+{% endif %}
+{% endfor %}
+{% for m in spec.methods if not m.testable %}
+
+test("test_{{ m.name }}", { skip: "no example values were captured for its required arguments" }, () => {});
+{% endfor %}