readwright 0.3.0__py3-none-any.whl

readwright/cli.py

@@ -0,0 +1,397 @@
+"""readwright command line interface."""
+
+from __future__ import annotations
+
+import difflib
+import re
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+import yaml
+from rich.console import Console
+from rich.table import Table
+
+from readwright import __version__
+from readwright.badges import BadgeRegistry
+from readwright.config import (
+    DEFAULT_CONFIG_NAME,
+    DEFAULT_TEMPLATE,
+    Config,
+    ProjectInfo,
+    config_sources,
+    deep_merge,
+    load_user_config,
+    resolve,
+)
+from readwright.renderer import BASE_TEMPLATE, MARKER_PREFIX, Renderer, RenderResult
+
+app = typer.Typer(
+    help="Render GitHub READMEs from Jinja2 templates.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+out = Console()
+err = Console(stderr=True)
+
+RootOpt = Annotated[Path, typer.Option("--root", "-C", help="Repository root.")]
+ConfigOpt = Annotated[Path | None, typer.Option("--config", "-c", help="Config file path.")]
+UserConfigOpt = Annotated[
+    bool,
+    typer.Option(
+        "--user-config", help="Merge ~/.config/readwright/config.yaml under the repo config."
+    ),
+]
+StrictOpt = Annotated[bool, typer.Option("--strict", help="Missing screenshots are errors.")]
+VerboseOpt = Annotated[
+    bool, typer.Option("--verbose", "-v", help="Show which loader served each template.")
+]
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        out.print(f"readwright {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool, typer.Option("--version", callback=version_callback, is_eager=True)
+    ] = False,
+) -> None:
+    pass
+
+
+def warn(message: str) -> None:
+    err.print("[yellow]warning:[/] ", end="")
+    err.print(message, markup=False, highlight=False)
+
+
+def fail(message: str, code: int = 1) -> None:
+    err.print("[red]error:[/] ", end="")
+    err.print(message, markup=False, highlight=False)
+    raise typer.Exit(code)
+
+
+def _load(root: Path, config: Path | None, user_config: bool, strict: bool) -> Config:
+    if config is None and len(sources := config_sources(root)) > 1:
+        warn(f"both {' and '.join(sources)} exist; using {sources[0]}")
+    try:
+        cfg = resolve(root, config_path=config, use_user_config=user_config)
+    except ValueError as exc:
+        fail(str(exc))
+    return cfg.model_copy(update={"strict": True}) if strict else cfg
+
+
+def _render_with(root: Path, cfg: Config, verbose: bool) -> RenderResult:
+    try:
+        result = Renderer(root, cfg, warn=warn).render()
+    except Exception as exc:
+        fail(f"{type(exc).__name__}: {exc}")
+    if verbose:
+        for name, source in result.sources.items():
+            err.print(f"[dim]template {name} <- {source}[/]")
+    return result
+
+
+def _render(
+    root: Path, config: Path | None, user_config: bool, strict: bool, verbose: bool = False
+) -> tuple[Config, RenderResult]:
+    cfg = _load(root, config, user_config, strict)
+    return cfg, _render_with(root, cfg, verbose)
+
+
+def _is_managed(path: Path) -> bool:
+    return path.read_text().startswith(MARKER_PREFIX)
+
+
+def _write_output(root: Path, cfg: Config, result: RenderResult, force: bool) -> None:
+    target = root / cfg.output
+    if target.is_file():
+        if target.read_text() == result.text:
+            out.print(f"{cfg.output} unchanged")
+            return
+        if not force and not _is_managed(target):
+            fail(
+                f"{cfg.output} exists and is not managed by readwright; "
+                "use --force to overwrite or `readwright init --from-readme` to adopt it"
+            )
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(result.text)
+    out.print(f"{cfg.output} updated from {result.template_name}")
+
+
+def watch_paths(root: Path, cfg: Config) -> list[Path]:
+    candidates = [
+        root / cfg.template,
+        root / DEFAULT_CONFIG_NAME,
+        root / "pyproject.toml",
+        root / "templates",
+        root / cfg.screenshots.dir,
+        root / "CHANGELOG.md",
+    ]
+    candidates += [root / t for t in cfg.templates if not t.startswith("pkg:")]
+    return [p for p in candidates if p.exists()]
+
+
+@app.command()
+def render(
+    root: RootOpt = Path("."),
+    config: ConfigOpt = None,
+    user_config: UserConfigOpt = False,
+    strict: StrictOpt = False,
+    verbose: VerboseOpt = False,
+    output: Annotated[
+        str | None, typer.Option("--output", "-o", help="Output path, or '-' for stdout.")
+    ] = None,
+    force: Annotated[
+        bool, typer.Option("--force", "-f", help="Overwrite an unmanaged existing README.")
+    ] = False,
+    watch: Annotated[
+        bool, typer.Option("--watch", "-w", help="Re-render whenever inputs change.")
+    ] = False,
+) -> None:
+    """Render the README template to the output file."""
+    cfg = _load(root, config, user_config, strict)
+    if output:
+        cfg = cfg.model_copy(update={"output": output})
+    result = _render_with(root, cfg, verbose)
+    if cfg.output == "-":
+        sys.stdout.write(result.text)
+        return
+    _write_output(root, cfg, result, force)
+    if watch:
+        _watch_loop(root, config, user_config, strict, verbose, output, force)
+
+
+def _watch_loop(
+    root: Path,
+    config: Path | None,
+    user_config: bool,
+    strict: bool,
+    verbose: bool,
+    output: str | None,
+    force: bool,
+) -> None:
+    from watchfiles import watch as watch_files
+
+    cfg = _load(root, config, user_config, strict)
+    paths = watch_paths(root, cfg)
+    err.print(
+        f"[dim]watching {', '.join(str(p.relative_to(root)) for p in paths)} (ctrl-c to stop)[/]"
+    )
+    try:
+        for _changes in watch_files(*paths):
+            try:
+                cfg = _load(root, config, user_config, strict)
+                if output:
+                    cfg = cfg.model_copy(update={"output": output})
+                _write_output(root, cfg, _render_with(root, cfg, verbose), force)
+            except typer.Exit:
+                continue
+    except KeyboardInterrupt:
+        return
+
+
+@app.command()
+def check(
+    root: RootOpt = Path("."),
+    config: ConfigOpt = None,
+    user_config: UserConfigOpt = False,
+    strict: StrictOpt = False,
+    verbose: VerboseOpt = False,
+) -> None:
+    """Exit 1 if the output file is out of date with its template."""
+    cfg, result = _render(root, config, user_config, strict, verbose)
+    for name in result.user_templates:
+        warn(f"user-level template '{name}' was used; CI renders will differ")
+    target = root / cfg.output
+    if not target.is_file():
+        fail(f"{cfg.output} does not exist; run `readwright render`")
+    current = target.read_text()
+    if not current.startswith(MARKER_PREFIX):
+        warn(f"{cfg.output} is not managed by readwright (no marker); skipping")
+        return
+    if current == result.text:
+        out.print(f"{cfg.output} is up to date")
+        return
+    diff = difflib.unified_diff(
+        current.splitlines(keepends=True),
+        result.text.splitlines(keepends=True),
+        fromfile=cfg.output,
+        tofile=f"{cfg.output} (rendered)",
+    )
+    out.print("".join(diff), end="", highlight=False, markup=False)
+    fail(f"{cfg.output} is out of date; run `readwright render`")
+
+
+INIT_TEMPLATE = """\
+{{% extends "base.md.j2" %}}
+
+{{% block usage %}}
+## Usage
+
+Describe how to use {name} here.
+{{% endblock %}}
+"""
+
+ADOPT_TEMPLATE = """\
+{{% extends "base.md.j2" %}}
+
+{{# Existing README content, moved here by `readwright init --from-readme`.
+   Trim sections now provided by the base template (install, contributing, license),
+   remove the raw tags to start using helpers like screenshot() and badge(). #}}
+{{% block usage %}}
+{open}{body}{close}
+{{% endblock %}}
+
+{{% block screenshots %}}{{% endblock %}}
+{{% block install %}}{{% endblock %}}
+{{% block contributing %}}{{% endblock %}}
+{{% block license %}}{{% endblock %}}
+"""
+
+CONFIG_HEADER = """\
+# readwright configuration. All keys are optional; autodetected values are shown.
+# Keys: template, templates, output, strict, allow_exec, screenshots{dir,width,style}, badges,
+#       badges_style, badges_custom, donate, donate_handles, related, project{...}, vars.
+# Run `readwright badges` / `readwright blocks` to list badge presets and template blocks.
+"""
+
+H1 = re.compile(r"^#\s+.+\n+", re.MULTILINE)
+JINJA_SYNTAX = re.compile(r"{[{%#]")
+
+
+def _init_config_data(root: Path) -> dict:
+    cfg = resolve(root)
+    data = cfg.model_dump(exclude_defaults=True, exclude_none=True)
+    if (user := load_user_config()) is not None:
+        data = deep_merge(user.model_dump(exclude_defaults=True, exclude_none=True), data)
+    data.setdefault("badges", [])
+    project = data.setdefault("project", {})
+    for key in ("python_versions", "project_type", "version"):
+        project.pop(key, None)
+    return data
+
+
+def _adopted_body(readme: Path) -> str:
+    body = H1.sub("", readme.read_text(), count=1).strip("\n") + "\n"
+    if JINJA_SYNTAX.search(body):
+        return ADOPT_TEMPLATE.format(open="{% raw %}\n", body=body, close="{% endraw +%}\n")
+    return ADOPT_TEMPLATE.format(open="", body=body, close="")
+
+
+def _write_pyproject_config(root: Path, data: dict) -> None:
+    import tomli_w
+
+    path = root / "pyproject.toml"
+    text = path.read_text() if path.is_file() else ""
+    if "[tool.readme]" in text:
+        fail("pyproject.toml already has a [tool.readme] section; refusing to overwrite")
+    section = tomli_w.dumps({"tool": {"readme": data}})
+    path.write_text(text.rstrip("\n") + "\n\n" + section if text else section)
+
+
+@app.command()
+def init(
+    root: RootOpt = Path("."),
+    from_readme: Annotated[
+        bool,
+        typer.Option("--from-readme", help="Move an existing README.md body into the template."),
+    ] = False,
+    pyproject: Annotated[
+        bool,
+        typer.Option("--pyproject", help="Write config to [tool.readme] instead of readme.yaml."),
+    ] = False,
+) -> None:
+    """Scaffold readme.yaml and README.md.j2 in the repository."""
+    config_path = root / DEFAULT_CONFIG_NAME
+    template_path = root / DEFAULT_TEMPLATE
+    existing = [
+        p for p in ((template_path,) if pyproject else (config_path, template_path)) if p.exists()
+    ]
+    if existing:
+        fail(f"{existing[0].name} already exists; refusing to overwrite")
+    if pyproject and config_path.exists():
+        fail(f"{DEFAULT_CONFIG_NAME} already exists; refusing to overwrite")
+    data = _init_config_data(root)
+    name = data.get("project", {}).get("name") or root.resolve().name
+    readme = root / "README.md"
+    if from_readme:
+        if not readme.is_file():
+            fail("--from-readme given but README.md does not exist")
+        if _is_managed(readme):
+            fail("README.md is already managed by readwright")
+        template_path.write_text(_adopted_body(readme))
+    else:
+        template_path.write_text(INIT_TEMPLATE.format(name=name))
+    if pyproject:
+        _write_pyproject_config(root, data)
+        config_name = "pyproject.toml [tool.readme]"
+    else:
+        config_path.write_text(CONFIG_HEADER + yaml.safe_dump(data, sort_keys=False))
+        config_name = DEFAULT_CONFIG_NAME
+    if from_readme:
+        cfg = _load(root, None, False, False)
+        _write_output(root, cfg, _render_with(root, cfg, False), force=True)
+        out.print(f"created {config_name} and {DEFAULT_TEMPLATE}; README.md is now managed")
+        return
+    out.print(f"created {config_name} and {DEFAULT_TEMPLATE}; run `readwright render`")
+
+
+@app.command()
+def badges(root: RootOpt = Path("."), config: ConfigOpt = None) -> None:
+    """List available badge presets."""
+    try:
+        cfg = resolve(root, config_path=config)
+    except ValueError:
+        cfg = Config(project=ProjectInfo())
+    registry = BadgeRegistry(cfg)
+    table = Table(show_lines=False)
+    table.add_column("preset", no_wrap=True)
+    table.add_column("example", overflow="fold")
+    for name in registry.names():
+        try:
+            example = registry.render(name)
+        except ValueError as exc:
+            example = f"[dim]{exc}[/]"
+        table.add_row(name, example)
+    out.print(table)
+
+
+@app.command()
+def blocks(root: RootOpt = Path("."), config: ConfigOpt = None) -> None:
+    """List the blocks of base.md.j2 and the partials that can be shadowed."""
+    cfg = _load(root, config, False, False)
+    renderer = Renderer(root, cfg)
+    template = renderer.env.get_template(BASE_TEMPLATE)
+    out.print(f"[bold]blocks in {BASE_TEMPLATE}[/]")
+    for name in template.blocks:
+        out.print(f"  {name}")
+    out.print("[bold]partials[/] (shadow with templates/partials/<name> in the repo)")
+    for name in sorted(renderer.env.list_templates()):
+        if name.startswith("partials/"):
+            out.print(f"  {name}  [dim]<- {renderer.source_label(name)}[/]")
+
+
+@app.command()
+def show(
+    name: Annotated[str, typer.Argument(help="Template name, e.g. base.md.j2")],
+    root: RootOpt = Path("."),
+    config: ConfigOpt = None,
+) -> None:
+    """Print a template's source (useful for copying a partial to override it)."""
+    cfg = _load(root, config, False, False)
+    renderer = Renderer(root, cfg)
+    try:
+        source, _, _ = renderer.env.loader.get_source(renderer.env, name)
+    except Exception:
+        fail(f"template '{name}' not found")
+    err.print(f"[dim]# {name} <- {renderer.source_label(name)}[/]")
+    sys.stdout.write(source)
+
+
+if __name__ == "__main__":
+    app()

readwright/config.py

@@ -0,0 +1,230 @@
+"""Configuration models and loading (readme.yaml, [tool.readme], user-level config)."""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, model_serializer, model_validator
+
+from readwright.metadata import detect
+
+DEFAULT_CONFIG_NAME = "readme.yaml"
+DEFAULT_TEMPLATE = "README.md.j2"
+
+
+class StrictModel(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class ProjectInfo(StrictModel):
+    name: str | None = None
+    owner: str | None = None
+    repo: str | None = None
+    tagline: str | None = None
+    version: str | None = None
+    pypi: str | None = None
+    npm: str | None = None
+    crate: str | None = None
+    go_module: str | None = None
+    nuget: str | None = None
+    mod_id: str | None = None
+    minecraft_version: str | None = None
+    modrinth: str | None = None
+    curseforge: str | None = None
+    ha_min_version: str | None = None
+    flow_plugin: str | None = None
+    license: str | None = None
+    ci_workflow: str | None = None
+    python_versions: list[str] = Field(default_factory=list)
+    project_type: str = "generic"
+
+    @property
+    def url(self) -> str | None:
+        if self.owner and self.repo:
+            return f"https://github.com/{self.owner}/{self.repo}"
+        return None
+
+
+class ScreenshotsConfig(StrictModel):
+    dir: str = "docs/screenshots"
+    width: int | None = 720
+    style: Literal["markdown", "html"] = "markdown"
+
+
+class CustomBadge(StrictModel):
+    label: str
+    message: str
+    color: str = "blue"
+    link: str | None = None
+    logo: str | None = None
+    style: str | None = None
+
+
+class BadgeSpec(StrictModel):
+    preset: str | None = None
+    options: dict[str, Any] = Field(default_factory=dict)
+    shield: CustomBadge | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def coerce(cls, value: Any) -> Any:
+        if isinstance(value, str):
+            return {"preset": value}
+        if isinstance(value, dict) and "shield" in value and "preset" not in value:
+            return {"shield": value["shield"]}
+        if isinstance(value, dict) and "options" not in value and "shield" not in value:
+            value = dict(value)
+            preset = value.pop("preset", None)
+            if preset is None:
+                raise ValueError("badge entry needs 'preset' or 'shield'")
+            return {"preset": preset, "options": value}
+        return value
+
+    @model_serializer
+    def compact(self) -> Any:
+        if self.shield is not None:
+            return {"shield": self.shield.model_dump(exclude_defaults=True, exclude_none=True)}
+        if self.options:
+            return {"preset": self.preset, **self.options}
+        return self.preset
+
+
+class BannerConfig(StrictModel):
+    unsplash: str | None = None
+    image: str | None = None
+    alt: str | None = None
+    width: int | None = 1200
+    height: int | None = None
+    credit: str | None = None
+    user: str | None = None
+    photo_id: str | None = None
+    link: str | None = None
+    html: bool = False
+
+
+class RelatedRepo(StrictModel):
+    repo: str
+    description: str = ""
+    url: str | None = None
+
+
+class Config(StrictModel):
+    template: str = DEFAULT_TEMPLATE
+    templates: list[str] = Field(default_factory=list)
+    output: str = "README.md"
+    strict: bool = False
+    allow_exec: bool = False
+    badges_style: str | None = None
+    related: list[RelatedRepo] = Field(default_factory=list)
+    banner: BannerConfig | None = None
+    screenshots: ScreenshotsConfig = Field(default_factory=ScreenshotsConfig)
+    badges: list[BadgeSpec] = Field(default_factory=list)
+    badges_custom: dict[str, CustomBadge] = Field(default_factory=dict)
+    donate: list[BadgeSpec] = Field(default_factory=list)
+    donate_handles: dict[str, str | None] = Field(default_factory=dict)
+    project: ProjectInfo = Field(default_factory=ProjectInfo)
+    vars: dict[str, Any] = Field(default_factory=dict)
+
+
+def deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    merged = dict(base)
+    for key, value in override.items():
+        if isinstance(value, dict) and isinstance(merged.get(key), dict):
+            merged[key] = deep_merge(merged[key], value)
+        else:
+            merged[key] = value
+    return merged
+
+
+def _validate(data: dict[str, Any], source: str) -> Config:
+    try:
+        return Config.model_validate(data)
+    except Exception as exc:
+        raise ValueError(f"invalid config in {source}: {exc}") from exc
+
+
+def _read_yaml(path: Path) -> dict[str, Any]:
+    data = yaml.safe_load(path.read_text()) or {}
+    if not isinstance(data, dict):
+        raise ValueError(f"invalid config in {path}: expected a mapping")
+    return data
+
+
+def _read_tool_readme(root: Path) -> dict[str, Any] | None:
+    path = root / "pyproject.toml"
+    if not path.is_file():
+        return None
+    data = tomllib.loads(path.read_text())
+    section = data.get("tool", {}).get("readme")
+    return dict(section) if isinstance(section, dict) else None
+
+
+def find_config_path(root: Path) -> Path | None:
+    path = root / DEFAULT_CONFIG_NAME
+    return path if path.is_file() else None
+
+
+def config_sources(root: Path) -> list[str]:
+    found = []
+    if find_config_path(root) is not None:
+        found.append(DEFAULT_CONFIG_NAME)
+    if _read_tool_readme(root) is not None:
+        found.append("pyproject.toml [tool.readme]")
+    return found
+
+
+def load_config_data(root: Path, config_path: Path | None = None) -> tuple[dict[str, Any], str]:
+    if config_path is not None:
+        return _read_yaml(config_path), str(config_path)
+    if (path := find_config_path(root)) is not None:
+        return _read_yaml(path), str(path)
+    if (section := _read_tool_readme(root)) is not None:
+        return section, str(root / "pyproject.toml [tool.readme]")
+    return {}, "<defaults>"
+
+
+def load_config(root: Path, config_path: Path | None = None) -> Config:
+    data, source = load_config_data(root, config_path)
+    return _validate(data, source)
+
+
+def user_config_path() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(base) / "readwright" / "config.yaml"
+
+
+def user_templates_dir() -> Path:
+    return user_config_path().parent / "templates"
+
+
+def load_user_config() -> Config | None:
+    path = user_config_path()
+    if not path.is_file():
+        return None
+    return _validate(_read_yaml(path), str(path))
+
+
+def _dump(model: BaseModel) -> dict[str, Any]:
+    return model.model_dump(exclude_defaults=True, exclude_none=True)
+
+
+def resolve(
+    root: Path,
+    config_path: Path | None = None,
+    use_user_config: bool = False,
+) -> Config:
+    detected = detect(root)
+    layers: list[dict[str, Any]] = [{"project": _dump(ProjectInfo(**detected.__dict__))}]
+    if use_user_config and (user := load_user_config()) is not None:
+        layers.append(_dump(user))
+    repo_data, source = load_config_data(root, config_path)
+    _validate(repo_data, source)
+    layers.append(repo_data)
+    merged: dict[str, Any] = {}
+    for layer in layers:
+        merged = deep_merge(merged, layer)
+    return _validate(merged, source)