readwright 0.4.0__tar.gz → 0.5.0__tar.gz

{readwright-0.4.0 → readwright-0.5.0}/.agents/skills/readwright/SKILL.md

@@ -37,6 +37,7 @@ template/config, then re-render.
 | `readwright blocks` | List overridable template blocks/partials |
 | `readwright skill [--install] [--dest DIR] [--force]` | Print the bundled copy of this skill, or install it into a project's `.agents/skills/` (or `--dest`) |
 | `readwright show <template>` | Print a packaged template (`base.md.j2` for the block order, or e.g. `partials/install.md.j2`) to copy and customize |
+| `readwright completion <shell>` | Print a bash/zsh/fish/PowerShell completion script |
 
 All accept `-C/--root` (repo root) and `-c/--config` (explicit config path) as
 options *after* the subcommand, e.g. `readwright render -C /path/to/repo` —

{readwright-0.4.0 → readwright-0.5.0}/AGENTS.md

@@ -51,7 +51,7 @@ regenerating rather than hand-editing expected output.
 ## Layout
 
 - `src/readwright/cli.py` — Typer commands: `init`, `render`, `check`, `badges`,
-  `blocks`, `show`, `skill`.
+  `blocks`, `show`, `skill`, `completion`.
 - `src/readwright/renderer.py` — Jinja2 environment setup and rendering pipeline.
 - `src/readwright/helpers.py`, `badges.py`, `images.py`, `toc.py`, `changelog.py`,
   `metadata.py` — the template helper functions exposed to `README.md.j2`

{readwright-0.4.0 → readwright-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: readwright
-Version: 0.4.0
+Version: 0.5.0
 Summary: Render GitHub READMEs from Jinja2 templates with badge and screenshot helpers
 Project-URL: Homepage, https://github.com/Garulf/readwright
 Project-URL: Issues, https://github.com/Garulf/readwright/issues
@@ -36,6 +36,7 @@ Render GitHub READMEs from Jinja2 templates with badge and screenshot helpers.
 - [Template helpers](#template-helpers)
 - [Configuration](#configuration)
 - [pre-commit and GitHub Actions](#pre-commit-and-github-actions)
+- [Shell completion](#shell-completion)
 - [Agent skill](#agent-skill)
 - [Contributing](#contributing)
 - [License](#license)
@@ -168,18 +169,29 @@ stays reproducible in CI. `readwright render --user-config` merges them ad hoc.
 ```yaml
 # .pre-commit-config.yaml
 - repo: https://github.com/Garulf/readwright
-  rev: v0.4.0
+  rev: v0.5.0
   hooks:
     - id: readwright-check
 ```
 
 ```yaml
 # .github/workflows/ci.yml
-- uses: Garulf/readwright@v0.4.0
+- uses: Garulf/readwright@v0.5.0
   with:
     mode: check     # or render
 ```
 
+## Shell completion
+
+`readwright completion <shell>` prints a completion script for bash, zsh, fish or PowerShell.
+It completes subcommands, options and the template names `readwright show` accepts.
+
+```sh
+eval "$(readwright completion bash)"   # add to ~/.bashrc
+eval "$(readwright completion zsh)"    # add to ~/.zshrc, after compinit
+readwright completion fish > ~/.config/fish/completions/readwright.fish
+```
+
 ## Agent skill
 
 The repo ships an [agent skill](https://agentskills.io) at `.agents/skills/readwright/`

{readwright-0.4.0 → readwright-0.5.0}/README.md

@@ -10,6 +10,7 @@ Render GitHub READMEs from Jinja2 templates with badge and screenshot helpers.
 - [Template helpers](#template-helpers)
 - [Configuration](#configuration)
 - [pre-commit and GitHub Actions](#pre-commit-and-github-actions)
+- [Shell completion](#shell-completion)
 - [Agent skill](#agent-skill)
 - [Contributing](#contributing)
 - [License](#license)
@@ -142,18 +143,29 @@ stays reproducible in CI. `readwright render --user-config` merges them ad hoc.
 ```yaml
 # .pre-commit-config.yaml
 - repo: https://github.com/Garulf/readwright
-  rev: v0.4.0
+  rev: v0.5.0
   hooks:
     - id: readwright-check
 ```
 
 ```yaml
 # .github/workflows/ci.yml
-- uses: Garulf/readwright@v0.4.0
+- uses: Garulf/readwright@v0.5.0
   with:
     mode: check     # or render
 ```
 
+## Shell completion
+
+`readwright completion <shell>` prints a completion script for bash, zsh, fish or PowerShell.
+It completes subcommands, options and the template names `readwright show` accepts.
+
+```sh
+eval "$(readwright completion bash)"   # add to ~/.bashrc
+eval "$(readwright completion zsh)"    # add to ~/.zshrc, after compinit
+readwright completion fish > ~/.config/fish/completions/readwright.fish
+```
+
 ## Agent skill
 
 The repo ships an [agent skill](https://agentskills.io) at `.agents/skills/readwright/`

{readwright-0.4.0 → readwright-0.5.0}/README.md.j2

@@ -134,6 +134,17 @@ stays reproducible in CI. `readwright render --user-config` merges them ad hoc.
     mode: check     # or render
 ```
 
+## Shell completion
+
+`readwright completion <shell>` prints a completion script for bash, zsh, fish or PowerShell.
+It completes subcommands, options and the template names `readwright show` accepts.
+
+```sh
+eval "$(readwright completion bash)"   # add to ~/.bashrc
+eval "$(readwright completion zsh)"    # add to ~/.zshrc, after compinit
+readwright completion fish > ~/.config/fish/completions/readwright.fish
+```
+
 ## Agent skill
 
 The repo ships an [agent skill](https://agentskills.io) at `.agents/skills/readwright/`

{readwright-0.4.0 → readwright-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "readwright"
-version = "0.4.0"
+version = "0.5.0"
 description = "Render GitHub READMEs from Jinja2 templates with badge and screenshot helpers"
 authors = [
     { name = "Garulf", email = "535299+Garulf@users.noreply.github.com" }

readwright-0.5.0/src/readwright/__init__.py

@@ -0,0 +1,12 @@
+"""Render GitHub READMEs from Jinja2 templates."""
+
+
+def __getattr__(name: str) -> str:
+    if name != "__version__":
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        return version("readwright")
+    except PackageNotFoundError:
+        return "0.0.0"

{readwright-0.4.0 → readwright-0.5.0}/src/readwright/cli.py

@@ -6,35 +6,44 @@ import difflib
 import re
 import shutil
 import sys
+from functools import cache
 from pathlib import Path
-from typing import Annotated
+from typing import TYPE_CHECKING, 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
+from typer.completion import Shells, completion_init, get_completion_script
+
+# Every shell Tab press imports this module, so heavy imports live in the functions that use them.
+
+if TYPE_CHECKING:
+    from rich.console import Console
+
+    from readwright.config import Config
+    from readwright.renderer import RenderResult
+
+completion_init()
 
 app = typer.Typer(
     help="Render GitHub READMEs from Jinja2 templates.",
     no_args_is_help=True,
     add_completion=False,
 )
-out = Console()
-err = Console(stderr=True)
+
+
+@cache
+def _console(stderr: bool) -> Console:
+    from rich.console import Console
+
+    return Console(stderr=stderr)
+
+
+def out() -> Console:
+    return _console(stderr=False)
+
+
+def err() -> Console:
+    return _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.")]
@@ -52,7 +61,9 @@ VerboseOpt = Annotated[
 
 def version_callback(value: bool) -> None:
     if value:
-        out.print(f"readwright {__version__}")
+        from readwright import __version__
+
+        out().print(f"readwright {__version__}")
         raise typer.Exit()
 
 
@@ -66,17 +77,19 @@ def main(
 
 
 def warn(message: str) -> None:
-    err.print("[yellow]warning:[/] ", end="")
-    err.print(message, markup=False, highlight=False)
+    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)
+    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:
+    from readwright.config import config_sources, resolve
+
     if config is None and len(sources := config_sources(root)) > 1:
         warn(f"both {' and '.join(sources)} exist; using {sources[0]}")
     try:
@@ -87,13 +100,15 @@ def _load(root: Path, config: Path | None, user_config: bool, strict: bool) -> C
 
 
 def _render_with(root: Path, cfg: Config, verbose: bool) -> RenderResult:
+    from readwright.renderer import Renderer
+
     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}[/]")
+            err().print(f"[dim]template {name} <- {source}[/]")
     return result
 
 
@@ -105,6 +120,8 @@ def _render(
 
 
 def _is_managed(path: Path) -> bool:
+    from readwright.renderer import MARKER_PREFIX
+
     return path.read_text(encoding="utf-8").startswith(MARKER_PREFIX)
 
 
@@ -112,7 +129,7 @@ def _write_output(root: Path, cfg: Config, result: RenderResult, force: bool) ->
     target = root / cfg.output
     if target.is_file():
         if target.read_text(encoding="utf-8") == result.text:
-            out.print(f"{cfg.output} unchanged")
+            out().print(f"{cfg.output} unchanged")
             return
         if not force and not _is_managed(target):
             fail(
@@ -121,10 +138,12 @@ def _write_output(root: Path, cfg: Config, result: RenderResult, force: bool) ->
             )
     target.parent.mkdir(parents=True, exist_ok=True)
     target.write_text(result.text, encoding="utf-8")
-    out.print(f"{cfg.output} updated from {result.template_name}")
+    out().print(f"{cfg.output} updated from {result.template_name}")
 
 
 def watch_paths(root: Path, cfg: Config) -> list[Path]:
+    from readwright.config import DEFAULT_CONFIG_NAME
+
     candidates = [
         root / cfg.template,
         root / DEFAULT_CONFIG_NAME,
@@ -180,7 +199,7 @@ def _watch_loop(
 
     cfg = _load(root, config, user_config, strict)
     paths = watch_paths(root, cfg)
-    err.print(
+    err().print(
         f"[dim]watching {', '.join(str(p.relative_to(root)) for p in paths)} (ctrl-c to stop)[/]"
     )
     try:
@@ -205,6 +224,8 @@ def check(
     verbose: VerboseOpt = False,
 ) -> None:
     """Exit 1 if the output file is out of date with its template."""
+    from readwright.renderer import MARKER_PREFIX
+
     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")
@@ -216,7 +237,7 @@ def check(
         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")
+        out().print(f"{cfg.output} is up to date")
         return
     diff = difflib.unified_diff(
         current.splitlines(keepends=True),
@@ -224,7 +245,7 @@ def check(
         fromfile=cfg.output,
         tofile=f"{cfg.output} (rendered)",
     )
-    out.print("".join(diff), end="", highlight=False, markup=False)
+    out().print("".join(diff), end="", highlight=False, markup=False)
     fail(f"{cfg.output} is out of date; run `readwright render`")
 
 
@@ -266,6 +287,8 @@ JINJA_SYNTAX = re.compile(r"{[{%#]")
 
 
 def _init_config_data(root: Path) -> dict:
+    from readwright.config import deep_merge, load_user_config, resolve
+
     cfg = resolve(root)
     data = cfg.model_dump(exclude_defaults=True, exclude_none=True)
     if (user := load_user_config()) is not None:
@@ -308,6 +331,10 @@ def init(
     ] = False,
 ) -> None:
     """Scaffold readme.yaml and README.md.j2 in the repository."""
+    import yaml
+
+    from readwright.config import DEFAULT_CONFIG_NAME, DEFAULT_TEMPLATE
+
     config_path = root / DEFAULT_CONFIG_NAME
     template_path = root / DEFAULT_TEMPLATE
     existing = [
@@ -339,14 +366,19 @@ def init(
     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")
+        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`")
+    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."""
+    from rich.table import Table
+
+    from readwright.badges import BadgeRegistry
+    from readwright.config import Config, ProjectInfo, resolve
+
     try:
         cfg = resolve(root, config_path=config)
     except ValueError:
@@ -361,38 +393,53 @@ def badges(root: RootOpt = Path("."), config: ConfigOpt = None) -> None:
         except ValueError as exc:
             example = f"[dim]{exc}[/]"
         table.add_row(name, example)
-    out.print(table)
+    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."""
+    from readwright.renderer import BASE_TEMPLATE, Renderer
+
     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}[/]")
+    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)")
+        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)}[/]")
+            out().print(f"  {name}  [dim]<- {renderer.source_label(name)}[/]")
+
+
+def bundled_template_names(incomplete: str) -> list[str]:
+    templates = Path(__file__).resolve().parent / "templates"
+    names = sorted(p.relative_to(templates).as_posix() for p in templates.rglob("*") if p.is_file())
+    return [name for name in names if name.startswith(incomplete)]
 
 
 @app.command()
 def show(
-    name: Annotated[str, typer.Argument(help="Template name, e.g. base.md.j2")],
+    name: Annotated[
+        str,
+        typer.Argument(
+            help="Template name, e.g. base.md.j2", autocompletion=bundled_template_names
+        ),
+    ],
     root: RootOpt = Path("."),
     config: ConfigOpt = None,
 ) -> None:
     """Print a template's source (useful for copying a partial to override it)."""
+    from readwright.renderer import Renderer
+
     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)}[/]")
+    err().print(f"[dim]# {name} <- {renderer.source_label(name)}[/]")
     sys.stdout.write(source)
 
 
@@ -428,7 +475,7 @@ def skill(
     """Print the bundled agent skill's location, or --install it into a project."""
     source = bundled_skill_dir()
     if not install:
-        out.print(str(source), highlight=False, soft_wrap=True)
+        out().print(str(source), highlight=False, soft_wrap=True)
         return
     skills_dir = dest if dest is not None else root / DEFAULT_SKILL_DEST
     target = skills_dir / SKILL_NAME
@@ -437,7 +484,18 @@ def skill(
             fail(f"{target} already exists (use --force to replace it)")
         shutil.rmtree(target)
     shutil.copytree(source, target)
-    out.print(f"[green]installed[/] skill to {target}", highlight=False, soft_wrap=True)
+    out().print(f"[green]installed[/] skill to {target}", highlight=False, soft_wrap=True)
+
+
+@app.command()
+def completion(
+    shell: Annotated[Shells, typer.Argument(help="Shell to generate the script for.")],
+) -> None:
+    """Print a shell completion script, e.g. eval "$(readwright completion zsh)"."""
+    script = get_completion_script(
+        prog_name="readwright", complete_var="_READWRIGHT_COMPLETE", shell=shell.value
+    )
+    sys.stdout.write(script + "\n")
 
 
 if __name__ == "__main__":

{readwright-0.4.0 → readwright-0.5.0}/tests/conftest.py

@@ -1,3 +1,4 @@
+import os
 import subprocess
 from pathlib import Path
 
@@ -19,6 +20,13 @@ classifiers = [
 PNG_BYTES = b"\x89PNG\r\n\x1a\n"
 
 
+@pytest.fixture(autouse=True)
+def isolated_git_env(monkeypatch):
+    # git hooks export GIT_DIR, which would point test repos at the real repository
+    for name in [name for name in os.environ if name.startswith("GIT_")]:
+        monkeypatch.delenv(name)
+
+
 @pytest.fixture
 def tmp_repo(tmp_path: Path) -> Path:
     subprocess.run(["git", "init", "-q"], cwd=tmp_path, check=True)

{readwright-0.4.0 → readwright-0.5.0}/tests/test_cli.py

@@ -1,3 +1,5 @@
+import subprocess
+import sys
 from pathlib import Path
 
 import yaml
@@ -237,3 +239,35 @@ def test_skill_install_custom_dest_and_refuses_overwrite(tmp_path):
     assert again.exit_code == 1
     assert "already exists" in again.output
     assert run("skill", "--install", "--dest", dest, "--force").exit_code == 0
+
+
+def test_completion_prints_script_for_shell():
+    for shell in ("bash", "zsh", "fish"):
+        result = run("completion", shell)
+        assert result.exit_code == 0, result.output
+        assert "_READWRIGHT_COMPLETE=complete_" in result.output
+
+
+def test_completion_rejects_unknown_shell():
+    assert run("completion", "tcsh").exit_code != 0
+
+
+def test_completion_suggests_commands_and_templates():
+    def complete(words, cword):
+        env = {"_READWRIGHT_COMPLETE": "complete_bash", "COMP_WORDS": words, "COMP_CWORD": cword}
+        return runner.invoke(app, [], env=env, prog_name="readwright").output.split()
+
+    assert {"render", "completion"} <= set(complete("readwright ", "1"))
+    assert "partials/install.md.j2" in complete("readwright show partials/", "2")
+    assert complete("readwright show base", "2") == ["base.md.j2"]
+
+
+def test_import_skips_heavy_dependencies():
+    code = (
+        "import sys, readwright.cli; "
+        "print(sorted(m for m in ('pydantic', 'jinja2', 'rich', 'yaml') if m in sys.modules))"
+    )
+    result = subprocess.run(
+        [sys.executable, "-c", code], capture_output=True, text=True, check=True
+    )
+    assert result.stdout.strip() == "[]"

{readwright-0.4.0 → readwright-0.5.0}/uv.lock

@@ -577,7 +577,7 @@ wheels = [
 
 [[package]]
 name = "readwright"
-version = "0.4.0"
+version = "0.5.0"
 source = { editable = "." }
 dependencies = [
     { name = "jinja2" },

readwright-0.4.0/src/readwright/__init__.py

@@ -1,8 +0,0 @@
-"""Render GitHub READMEs from Jinja2 templates."""
-
-from importlib.metadata import PackageNotFoundError, version
-
-try:
-    __version__ = version("readwright")
-except PackageNotFoundError:
-    __version__ = "0.0.0"