readability-cli 0.5.0__tar.gz → 0.6.0__tar.gz

{readability_cli-0.5.0 → readability_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: readability-cli
-Version: 0.5.0
+Version: 0.6.0
 Summary: A CLI to lint, format, and type-check code with Google-style defaults, and pull Google style guides in markdown format.
 Project-URL: Homepage, https://github.com/owahltinez/readability
 Project-URL: Repository, https://github.com/owahltinez/readability
@@ -128,10 +128,19 @@ readability guide python --remote
 # Save a style guide to a file
 readability guide cpp --output cpp-style.md
 
+# Print where the guide already lives, to search it without copying it
+readability guide python --path
+grep -n "Naming" "$(readability guide python --path)"
+
 # Synchronize all supported style guides to the local cache
 readability sync
 ```
 
+A guide can exceed 100 KB, so `--path` is the cheap way to consult one: the
+file is already on disk, and searching it beats reading it whole or writing
+out a second copy. It is also what a coding agent should use, rather than
+redirecting the guide into a repository.
+
 ### Supported Languages
 
 Use `readability languages` to see a full list of supported languages and

{readability_cli-0.5.0 → readability_cli-0.6.0}/README.md

@@ -114,10 +114,19 @@ readability guide python --remote
 # Save a style guide to a file
 readability guide cpp --output cpp-style.md
 
+# Print where the guide already lives, to search it without copying it
+readability guide python --path
+grep -n "Naming" "$(readability guide python --path)"
+
 # Synchronize all supported style guides to the local cache
 readability sync
 ```
 
+A guide can exceed 100 KB, so `--path` is the cheap way to consult one: the
+file is already on disk, and searching it beats reading it whole or writing
+out a second copy. It is also what a coding agent should use, rather than
+redirecting the guide into a repository.
+
 ### Supported Languages
 
 Use `readability languages` to see a full list of supported languages and

{readability_cli-0.5.0 → readability_cli-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "readability-cli"
-version = "0.5.0"
+version = "0.6.0"
 description = "A CLI to lint, format, and type-check code with Google-style defaults, and pull Google style guides in markdown format."
 readme = "README.md"
 requires-python = ">=3.12"

{readability_cli-0.5.0 → readability_cli-0.6.0}/readability.py

@@ -253,6 +253,38 @@ def cli(ctx: click.Context, verbose: bool) -> None:
         logger.setLevel(logging.DEBUG)
 
 
+def _echo_guide_path(language: str) -> None:
+    """Print the local path of a language's style guide.
+
+    Args:
+        language: The language whose guide is being located.
+
+    Raises:
+        SystemExit: If the language is unsupported or its guide is absent.
+    """
+    filename = LANGUAGE_MAP.get(language.lower())
+    if not filename:
+        click.echo(
+            f"Error: Language '{language}' is not supported. Supported "
+            f"languages: {', '.join(sorted(LANGUAGE_MAP.keys()))}",
+            err=True,
+        )
+        sys.exit(1)
+
+    local_path = get_local_path(filename)
+    if not os.path.exists(local_path):
+        # Naming a file that is not there would send the caller to read
+        # nothing; fetching it is what `sync` is for.
+        click.echo(
+            f"Error: No local guide for '{language}' at {local_path}. "
+            "Run 'readability sync' to fetch it.",
+            err=True,
+        )
+        sys.exit(1)
+
+    click.echo(local_path)
+
+
 @cli.command()
 @click.argument("language")
 @click.option(
@@ -264,9 +296,20 @@ def cli(ctx: click.Context, verbose: bool) -> None:
 @click.option(
     "--remote", "-r", is_flag=True, help="Force fetching from the web."
 )
+@click.option(
+    "--path",
+    "-p",
+    "show_path",
+    is_flag=True,
+    help="Print where the guide is stored instead of its contents.",
+)
 @click.option("--verbose", "-v", is_flag=True, help="Enable verbose logging.")
 def guide(
-    language: str, output: Optional[str], remote: bool, verbose: bool
+    language: str,
+    output: Optional[str],
+    remote: bool,
+    show_path: bool,
+    verbose: bool,
 ) -> None:
     """Fetch the style guide for a specific LANGUAGE."""
     if verbose:
@@ -274,6 +317,13 @@ def guide(
 
     logger.info("Processing style guide for: %s", language)
 
+    # A guide runs to hundreds of kilobytes, so a caller that wants a few
+    # rules is better served searching the copy already on disk than
+    # reading the whole thing or writing out a second one.
+    if show_path:
+        _echo_guide_path(language)
+        return
+
     try:
         # Fetch and process the style guide
         markdown_content = get_guide(language, remote=remote)

{readability_cli-0.5.0 → readability_cli-0.6.0}/test_readability.py

@@ -151,6 +151,52 @@ def test_cli_output_file(mock_guide: MagicMock, tmp_path: Path) -> None:
     assert output_file.read_text() == "# Style Guide"
 
 
+def test_cli_path_prints_the_location(tmp_path: Path, monkeypatch) -> None:
+    """Tests that --path reports where the guide already lives on disk.
+
+    Guides ship with the package, so a caller wanting to search one needs
+    its location, not another copy of its contents.
+    """
+    monkeypatch.setenv("READABILITY_CACHE", str(tmp_path))
+    (tmp_path / "pyguide.md").write_text("# Style Guide")
+
+    runner = CliRunner()
+    result = runner.invoke(cli, ["guide", "python", "--path"])
+
+    assert result.exit_code == 0
+    assert result.output.strip() == str(tmp_path / "pyguide.md")
+    assert "# Style Guide" not in result.output
+
+
+def test_cli_path_reports_a_guide_not_yet_fetched(
+    tmp_path: Path, monkeypatch
+) -> None:
+    """Tests that a missing local guide fails instead of naming a phantom.
+
+    Printing a path to a file that is not there would send the caller to
+    read nothing at all.
+    """
+    monkeypatch.setenv("READABILITY_CACHE", str(tmp_path))
+
+    runner = CliRunner()
+    result = runner.invoke(cli, ["guide", "python", "--path"])
+
+    assert result.exit_code == 1
+    assert "sync" in result.output
+
+
+def test_cli_path_rejects_an_unsupported_language(
+    tmp_path: Path, monkeypatch
+) -> None:
+    """Tests that --path validates the language like the default path does."""
+    monkeypatch.setenv("READABILITY_CACHE", str(tmp_path))
+
+    runner = CliRunner()
+    result = runner.invoke(cli, ["guide", "nonexistent", "--path"])
+
+    assert result.exit_code == 1
+
+
 @patch("readability.get_guide")
 def test_cli_verbose(mock_guide: MagicMock) -> None:
     """Tests CLI with verbose flag.

{readability_cli-0.5.0 → readability_cli-0.6.0}/uv.lock

@@ -194,7 +194,7 @@ wheels = [
 
 [[package]]
 name = "readability-cli"
-version = "0.5.0"
+version = "0.6.0"
 source = { editable = "." }
 dependencies = [
     { name = "beautifulsoup4" },