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

ghost_api/generator/package.py

@@ -0,0 +1,197 @@
+"""Turn a generated client into a package you can install, publish or vendor.
+
+Next to the loose files (which you can copy into a project as they are), each generate
+writes:
+
+    package/python/       pyproject.toml, README.md, src/<module>/ (client, models, py.typed)
+    package/typescript/   package.json, tsconfig.json, README.md, src/index.ts
+
+`pip install output/<site>/package/python` and `npm install output/<site>/package/typescript`
+then work, and `from <module> import <Client>` is the same import as with the loose files.
+"""
+
+from __future__ import annotations
+
+import ast
+import json
+import shlex
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlencode
+
+from jinja2 import Environment, FileSystemLoader, StrictUndefined
+
+from ghost_api import __version__
+from ghost_api.generator.spec import ClientSpec, MethodSpec
+from ghost_api.generator.ts_gen import camel
+
+TEMPLATES = Path(__file__).parent / "templates"
+
+
+def dist_name(module: str) -> str:
+    return module.replace("_", "-")
+
+
+def example_value(literal: str | None) -> Any:
+    """'"dune"' -> 'dune', '12' -> 12: a generated test's example as a plain value."""
+    if literal is None:
+        return None
+    try:
+        return ast.literal_eval(literal)
+    except (ValueError, SyntaxError):
+        return literal
+
+
+def curl_example(spec: ClientSpec, method: MethodSpec) -> str:
+    """A copy-paste curl command for a method, using values seen while exploring."""
+    base = f"https://{method.host}" if method.host else spec.base_url
+    path = method.path
+    for p in method.by_location("path"):
+        path = path.replace("{" + p.name + "}", str(example_value(p.example) or f"<{p.name}>"))
+    query = {
+        p.wire: example_value(p.example)
+        for p in method.by_location("query")
+        if p.required and p.example is not None
+    }
+    creds = {c.arg: c for c in spec.credentials if c.arg in method.credentials}
+    for cred in creds.values():
+        if cred.location == "query":
+            query[cred.wire] = f"${cred.env}"
+    url = base + path + (f"?{urlencode(query, safe='$')}" if query else "")
+    parts = ["curl"]
+    if method.http_method != "GET":
+        parts += ["-X", method.http_method]
+    parts.append(shlex.quote(url) if "$" not in url else f'"{url}"')
+    for name, value in method.headers.items():
+        parts += ["-H", shlex.quote(f"{name}: {value}")]
+    for cred in creds.values():
+        if cred.location == "header":
+            parts += ["-H", f'"{cred.wire}: ${cred.env}"']
+    body = {
+        p.wire: example_value(p.example)
+        for p in method.by_location("body")
+        if p.example is not None
+    }
+    if method.by_location("body"):
+        parts += ["-H", shlex.quote("Content-Type: application/json")]
+        parts += ["-d", shlex.quote(json.dumps(body))]
+    return " ".join(parts)
+
+
+def _env() -> Environment:
+    env = Environment(
+        loader=FileSystemLoader(TEMPLATES),
+        trim_blocks=True,
+        lstrip_blocks=True,
+        keep_trailing_newline=True,
+        undefined=StrictUndefined,
+        autoescape=False,  # Markdown and config files
+    )
+    env.filters.update(camel=camel, json=json.dumps)
+    return env
+
+
+def readme(spec: ClientSpec, module: str, lang: str) -> str:
+    methods = [
+        {
+            "method": m,
+            "curl": curl_example(spec, m),
+            "py_args": ", ".join(f"{p.name}={p.example}" for p in m.required if p.example),
+            "ts_args": ", ".join(
+                json.dumps(example_value(p.example)) for p in m.required if p.example
+            ),
+            "ts_name": camel(m.name),
+            "ts_iter": "iter" + camel(m.name)[:1].upper() + camel(m.name)[1:],
+        }
+        for m in spec.methods
+    ]
+    return (
+        _env()
+        .get_template("package_readme.md.j2")
+        .render(
+            spec=spec,
+            module=module,
+            dist=dist_name(module),
+            lang=lang,
+            methods=methods,
+            version=__version__,
+            client_version=spec.version,
+        )
+    )
+
+
+def python_package(spec: ClientSpec, module: str, files: dict[str, str], out_dir: Path) -> Path:
+    """`files`: the rendered loose files ({module}.py, models.py, test_{module}.py)."""
+    root = out_dir / "package" / "python"
+    src = root / "src" / module
+    src.mkdir(parents=True, exist_ok=True)
+    (root / "tests").mkdir(exist_ok=True)
+    clients = [spec.class_name, spec.async_class, spec.error_class, *spec.error_classes.values()]
+    doc = f"{spec.class_name}: a typed client for {spec.domain} (generated by Ghost API)."
+    lines = [f'"""{doc}"""', ""]
+    lines += ["from .client import (", *(f"    {name}," for name in clients), ")"]
+    if spec.model_names:
+        lines += ["from .models import (", *(f"    {name}," for name in spec.model_names), ")"]
+    lines += ["", f"__all__ = {[*clients, *spec.model_names]!r}", ""]
+    init = "\n".join(lines)
+    contents = {
+        src / "__init__.py": init,
+        src / "client.py": files[f"{module}.py"],
+        src / "models.py": files["models.py"],
+        src / "py.typed": "",
+        root / "tests" / f"test_{module}.py": files[f"test_{module}.py"],
+        root / "pyproject.toml": _env()
+        .get_template("pyproject.toml.j2")
+        .render(spec=spec, module=module, dist=dist_name(module), version=spec.version),
+        root / "README.md": readme(spec, module, "python"),
+    }
+    if spec.changelog:
+        contents[root / "CHANGELOG.md"] = spec.changelog
+    for path, text in contents.items():
+        path.write_text(text, encoding="utf-8", newline="\n")
+    return root
+
+
+def typescript_package(spec: ClientSpec, module: str, client_source: str, out_dir: Path) -> Path:
+    root = out_dir / "package" / "typescript"
+    (root / "src").mkdir(parents=True, exist_ok=True)
+    package_json = {
+        "name": dist_name(module),
+        "version": spec.version,
+        "description": f"Unofficial typed client for {spec.domain} (generated by Ghost API)",
+        "type": "module",
+        "main": "./dist/index.js",
+        "types": "./dist/index.d.ts",
+        "exports": {".": {"types": "./dist/index.d.ts", "default": "./dist/index.js"}},
+        "files": ["dist", "README.md"],
+        "engines": {"node": ">=18"},
+        "scripts": {"build": "tsc -p .", "prepare": "tsc -p ."},
+        "devDependencies": {"typescript": "^5.4.0"},
+        "keywords": [spec.domain, "api-client", "ghost-api"],
+        "license": "UNLICENSED",
+    }
+    tsconfig = {
+        "compilerOptions": {
+            "target": "es2022",
+            "module": "es2022",
+            "moduleResolution": "bundler",
+            "lib": ["es2022", "dom"],
+            "strict": True,
+            "declaration": True,
+            "outDir": "dist",
+            "rootDir": "src",
+            "skipLibCheck": True,
+        },
+        "include": ["src"],
+    }
+    contents = {
+        root / "src" / "index.ts": client_source,
+        root / "package.json": json.dumps(package_json, indent=2) + "\n",
+        root / "tsconfig.json": json.dumps(tsconfig, indent=2) + "\n",
+        root / "README.md": readme(spec, module, "typescript"),
+    }
+    if spec.changelog:
+        contents[root / "CHANGELOG.md"] = spec.changelog
+    for path, text in contents.items():
+        path.write_text(text, encoding="utf-8", newline="\n")
+    return root

ghost_api/generator/python_gen.py

@@ -0,0 +1,172 @@
+"""Render a ClientSpec into Python files, then check them (Stage 6).
+
+Output, in output/<domain>/:
+    <name>_client.py   the client class
+    models.py          pydantic models
+    test_<name>.py     live tests (run in Stage 7)
+
+Checks before anything is written:
+    - every file compiles
+    - no secret-looking value and no [REDACTED] placeholder is present (NFR-16)
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from jinja2 import Environment, FileSystemLoader, StrictUndefined
+
+from ghost_api import __version__
+from ghost_api.capture.filters import REDACTED, redact_text
+from ghost_api.config import USER_AGENT_SUFFIX
+from ghost_api.generator.naming import snake
+from ghost_api.generator.spec import ClientSpec, CredentialSpec, MethodSpec
+
+TEMPLATES = Path(__file__).parent / "templates"
+
+
+class GenerationError(Exception):
+    pass
+
+
+@dataclass
+class GeneratedClient:
+    directory: Path
+    module: str  # import name of the client module
+    client_path: Path
+    models_path: Path
+    tests_path: Path
+    formatted: bool
+
+
+def module_name(spec: ClientSpec) -> str:
+    return snake(spec.class_name.removesuffix("Client")) + "_client"
+
+
+def render(spec: ClientSpec, packaged: bool = False) -> dict[str, str]:
+    """Render all files to strings: {filename: source}. `packaged`: for package/python
+    (the client imports its models only as `.models`)."""
+    env = Environment(
+        loader=FileSystemLoader(TEMPLATES),
+        trim_blocks=True,
+        lstrip_blocks=True,
+        keep_trailing_newline=True,
+        undefined=StrictUndefined,
+        autoescape=False,  # generating Python, not HTML
+    )
+    env.filters["pyrepr"] = repr
+    env.filters["doc"] = _doc
+    env.filters["path_expr"] = _path_expr
+    env.filters["creds"] = _creds
+    env.filters["env_map"] = lambda creds: {c.arg: c.env for c in creds}
+
+    module = module_name(spec)
+    model_types = " ".join(f.type for m in spec.models for f in m.fields)
+    context: dict[str, Any] = {
+        "spec": spec,
+        "module": module,
+        "version": __version__,
+        "generated_on": datetime.now(UTC).strftime("%Y-%m-%d"),
+        "user_agent": f"{module}/{__version__} (generated by {USER_AGENT_SUFFIX})",
+        "uses_any": bool(re.search(r"\bAny\b", model_types)),
+        "uses_field": any(f.alias for m in spec.models for f in m.fields),
+        "packaged": packaged,
+    }
+    return {
+        f"{module}.py": env.get_template("client.py.j2").render(context),
+        "models.py": env.get_template("models.py.j2").render(context),
+        f"test_{module}.py": env.get_template("test_client.py.j2").render(context),
+    }
+
+
+def check(files: dict[str, str]) -> None:
+    for name, source in files.items():
+        try:
+            compile(source, name, "exec")
+        except SyntaxError as exc:
+            raise GenerationError(f"{name} does not compile: {exc}") from exc
+        if REDACTED in source:
+            raise GenerationError(f"{name} contains a redacted placeholder")
+        if redact_text(source) != source:
+            raise GenerationError(f"{name} contains a value that looks like a secret")
+
+
+def write(spec: ClientSpec, out_dir: Path) -> GeneratedClient:
+    files = render(spec)
+    check(files)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    for name, source in files.items():
+        (out_dir / name).write_text(source, encoding="utf-8", newline="\n")
+    formatted = _format(out_dir, list(files))
+    if formatted:  # formatting must not break anything
+        check({n: (out_dir / n).read_text(encoding="utf-8") for n in files})
+    module = module_name(spec)
+    from ghost_api.generator.package import python_package  # ts_gen imports this module
+
+    packaged = render(spec, packaged=True)
+    check(packaged)
+    root = python_package(spec, module, packaged, out_dir)
+    _format(root / "src" / module, ["client.py", "models.py"])
+    return GeneratedClient(
+        directory=out_dir,
+        module=module,
+        client_path=out_dir / f"{module}.py",
+        models_path=out_dir / "models.py",
+        tests_path=out_dir / f"test_{module}.py",
+        formatted=formatted,
+    )
+
+
+def _format(directory: Path, names: list[str]) -> bool:
+    """Format with ruff if it's installed; generated code is readable without it too."""
+    cmd = [sys.executable, "-m", "ruff"] if _has_module("ruff") else None
+    if cmd is None and shutil.which("ruff"):
+        cmd = ["ruff"]
+    if cmd is None:
+        return False
+    try:
+        subprocess.run(
+            [*cmd, "format", "--quiet", "--line-length", "100", *names],
+            cwd=directory,
+            check=True,
+            capture_output=True,
+            timeout=60,
+        )
+    except (subprocess.SubprocessError, OSError):
+        return False
+    return True
+
+
+def _has_module(name: str) -> bool:
+    import importlib.util
+
+    return importlib.util.find_spec(name) is not None
+
+
+# --- template filters ------------------------------------------------------------------------
+
+
+def _doc(text: str) -> str:
+    """Safe inside a triple-quoted docstring."""
+    return text.replace("\\", "/").replace('"""', "'''").strip()
+
+
+def _path_expr(method: MethodSpec) -> str:
+    """'/api/books/{id}' -> f"/api/books/{quote(str(id), safe='')}"."""
+    if "{" not in method.path:
+        return repr(method.path)
+    escaped = method.path.replace("'", "\\'")
+    expr = re.sub(r"\{(\w+)\}", lambda m: "{quote(str(" + m.group(1) + "), safe='')}", escaped)
+    return 'f"' + expr.replace('"', '\\"') + '"'
+
+
+def _creds(method: MethodSpec, spec: ClientSpec, location: str) -> list[CredentialSpec]:
+    wanted = set(method.credentials)
+    return [c for c in spec.credentials if c.arg in wanted and location in ("any", c.location)]