readability-cli 0.10.3__tar.gz → 0.10.5__tar.gz

{readability_cli-0.10.3 → readability_cli-0.10.5}/PKG-INFO

@@ -1,15 +1,16 @@
 Metadata-Version: 2.5
 Name: readability-cli
-Version: 0.10.3
+Version: 0.10.5
 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
 License-File: LICENSE
 Requires-Python: >=3.12
-Requires-Dist: beautifulsoup4>=4.14.3
 Requires-Dist: click>=8.3.1
-Requires-Dist: markdownify>=1.2.2
-Requires-Dist: requests>=2.33.0
+Provides-Extra: sync
+Requires-Dist: beautifulsoup4>=4.14.3; extra == 'sync'
+Requires-Dist: markdownify>=1.2.2; extra == 'sync'
+Requires-Dist: requests>=2.33.0; extra == 'sync'
 Description-Content-Type: text/markdown
 
 # Readability
@@ -372,9 +373,13 @@ Supported languages and their aliases:
   - vim [cached]
 ```
 
-Refresh the cache with `sync`, which takes languages or refetches everything:
+Refresh the cache with `sync`, which takes languages or refetches everything.
+It fetches and converts HTML, so it needs the `sync` extra; the bundled guides
+are already converted, and every other command reads those:
 
 ```bash
+pip install 'readability-cli[sync]'
+
 # Refetch one guide, or a few
 readability sync python shell
 
@@ -389,8 +394,8 @@ The tool stores local copies of the style guides in the
 the `guide` command uses these local files when they exist. The bundled copies
 are automatically synchronized weekly from the official
 [Google Style Guides](https://google.github.io/styleguide/) repository via
-GitHub Actions, and you can refresh your local cache at any time with the `sync`
-command.
+GitHub Actions, so upgrading the package is usually enough. To refresh a local
+cache yourself, install the `sync` extra and run the `sync` command.
 
 You can override the default guide directory by setting the
 `READABILITY_CACHE` environment variable. This is useful if you want to store

{readability_cli-0.10.3 → readability_cli-0.10.5}/README.md

@@ -358,9 +358,13 @@ Supported languages and their aliases:
   - vim [cached]
 ```
 
-Refresh the cache with `sync`, which takes languages or refetches everything:
+Refresh the cache with `sync`, which takes languages or refetches everything.
+It fetches and converts HTML, so it needs the `sync` extra; the bundled guides
+are already converted, and every other command reads those:
 
 ```bash
+pip install 'readability-cli[sync]'
+
 # Refetch one guide, or a few
 readability sync python shell
 
@@ -375,8 +379,8 @@ The tool stores local copies of the style guides in the
 the `guide` command uses these local files when they exist. The bundled copies
 are automatically synchronized weekly from the official
 [Google Style Guides](https://google.github.io/styleguide/) repository via
-GitHub Actions, and you can refresh your local cache at any time with the `sync`
-command.
+GitHub Actions, so upgrading the package is usually enough. To refresh a local
+cache yourself, install the `sync` extra and run the `sync` command.
 
 You can override the default guide directory by setting the
 `READABILITY_CACHE` environment variable. This is useful if you want to store

readability_cli-0.10.5/biome.json

@@ -0,0 +1,5 @@
+{
+  "extends": ["./readability/configs/biome-default.json"],
+  "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
+  "files": { "includes": ["**", "!readability/guides"] }
+}

{readability_cli-0.10.3 → readability_cli-0.10.5}/pyproject.toml

@@ -1,12 +1,17 @@
 [project]
 name = "readability-cli"
-version = "0.10.3"
+version = "0.10.5"
 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"
 dependencies = [
-    "beautifulsoup4>=4.14.3",
     "click>=8.3.1",
+]
+
+# Only `sync` fetches and converts guides; the rest reads bundled copies.
+[project.optional-dependencies]
+sync = [
+    "beautifulsoup4>=4.14.3",
     "markdownify>=1.2.2",
     "requests>=2.33.0",
 ]
@@ -34,6 +39,8 @@ testpaths = ["."]
 [dependency-groups]
 dev = [
     "pytest>=9.0.2",
+    # The suite and the weekly guide refresh both exercise `sync`.
+    "readability-cli[sync]",
     "ruff>=0.15.8",
 ]
 

{readability_cli-0.10.3 → readability_cli-0.10.5}/readability/cli.py

@@ -12,6 +12,7 @@ from readability.guide import get_guide
 from readability.guide import get_guides_dir
 from readability.guide import get_local_path
 from readability.guide import LANGUAGE_MAP
+from readability.guide import load_sync_deps
 from readability.guide import refresh_guide
 from readability.outline import _echo_outline
 from readability.outline import _select_section
@@ -123,6 +124,9 @@ def sync(languages: Sequence[str], verbose: bool) -> None:
     if verbose:
         logger.setLevel(logging.DEBUG)
 
+    # A precondition, not a per-guide failure the loop should report N times
+    load_sync_deps()
+
     filenames = _resolve_filenames(languages)
     click.echo(f"Synchronizing {len(filenames)} style guide(s)...", err=True)
 
@@ -147,6 +151,10 @@ def sync(languages: Sequence[str], verbose: bool) -> None:
         err=True,
     )
 
+    # A guide that did not refetch leaves a stale local copy behind
+    if failure_count:
+        sys.exit(1)
+
 
 def _echo_languages() -> None:
     """Print the languages that have a guide, with their aliases."""
@@ -240,7 +248,6 @@ def check(paths: Sequence[str], fix: bool, unsafe: bool, verbose: bool) -> None:
     )
 
 
-# Main entry point for the CLI
 def main() -> None:
     """Main entry point for the CLI."""
     # Configured here, not at import, so library use has no side effects

{readability_cli-0.10.3 → readability_cli-0.10.5}/readability/configs/biome-default.json

@@ -8,7 +8,7 @@
   "linter": {
     "enabled": true,
     "rules": {
-      "recommended": true
+      "preset": "recommended"
     }
   },
   "html": {

{readability_cli-0.10.3 → readability_cli-0.10.5}/readability/guide.py

@@ -1,21 +1,46 @@
 """Fetch and cache Google style guides."""
 
+import functools
 from importlib.resources import files
 import logging
 import os
+import types
 import warnings
 
-from bs4 import BeautifulSoup
-from bs4 import XMLParsedAsHTMLWarning
 import click
-from markdownify import markdownify as md
-import requests
-
-warnings.filterwarnings("ignore", category=XMLParsedAsHTMLWarning)
 
 logger = logging.getLogger("readability")
 
 
+@functools.cache
+def load_sync_deps() -> tuple[
+    types.ModuleType, types.ModuleType, types.ModuleType
+]:
+    """Imports the libraries only the guide refresh needs.
+
+    Guides ship pre-converted, so this stack stays out of the default
+    install rather than charging every user for `sync`.
+
+    Returns:
+        The requests, bs4, and markdownify modules.
+
+    Raises:
+        click.ClickException: If the sync extra is not installed.
+    """
+    try:
+        import bs4  # noqa: PLC0415
+        import markdownify  # noqa: PLC0415
+        import requests  # noqa: PLC0415
+    except ImportError as e:
+        raise click.ClickException(
+            "Refreshing style guides needs extra libraries. Install them "
+            "with: pip install 'readability-cli[sync]'"
+        ) from e
+
+    warnings.filterwarnings("ignore", category=bs4.XMLParsedAsHTMLWarning)
+    return requests, bs4, markdownify
+
+
 def get_guides_dir() -> str:
     """Get the directory where style guides are cached.
 
@@ -29,7 +54,6 @@ def get_guides_dir() -> str:
     return os.getenv("READABILITY_CACHE") or str(bundled_guides)
 
 
-# Mapping of languages to their Google Style Guide file paths
 LANGUAGE_MAP = {
     "python": "pyguide.md",
     "shell": "shellguide.md",
@@ -72,9 +96,9 @@ def get_guide_content(url: str) -> str:
     Raises:
         click.ClickException: If the HTTP request fails.
     """
+    requests, _, _ = load_sync_deps()
     logger.info("Fetching style guide from %s", url)
 
-    # Perform the HTTP GET request with a timeout
     try:
         response = requests.get(url, timeout=10)
         response.raise_for_status()
@@ -97,9 +121,9 @@ def convert_to_markdown(content: str, filename: str) -> str:
     Returns:
         The converted markdown content.
     """
+    _, bs4, markdownify = load_sync_deps()
     logger.debug("Converting content for %s", filename)
 
-    # Handle Markdown files directly
     if filename.endswith(".md"):
         return content
 
@@ -107,11 +131,10 @@ def convert_to_markdown(content: str, filename: str) -> str:
     if content.lstrip().startswith("<?xml"):
         content = content.split("?>", 1)[-1].lstrip()
 
-    # Handle XML files (used for Vim script guide and JSON style guide)
+    # The Vim script and JSON guides are only published as XML
     if filename.endswith(".xml"):
-        soup = BeautifulSoup(content, "html.parser")
+        soup = bs4.BeautifulSoup(content, "html.parser")
 
-        # Add titles as headers
         guide = soup.find("guide")
         if guide:
             title = guide.get("title")
@@ -136,11 +159,10 @@ def convert_to_markdown(content: str, filename: str) -> str:
 
         for summary in soup.find_all("summary"):
             summary.name = "p"
-            # Wrap content in strong tags
             content_str = summary.decode_contents()
             summary.clear()
             strong = soup.new_tag("strong")
-            strong.append(BeautifulSoup(content_str, "html.parser"))
+            strong.append(bs4.BeautifulSoup(content_str, "html.parser"))
             summary.append(strong)
 
         for snippet in soup.find_all(["code_snippet", "bad_code_snippet"]):
@@ -157,14 +179,11 @@ def convert_to_markdown(content: str, filename: str) -> str:
                 snippet.append(p)
             snippet.append(code)
 
-        # Convert the modified soup to string and then to markdown
-        return md(str(soup), **MARKDOWNIFY_OPTIONS)
+        return markdownify.markdownify(str(soup), **MARKDOWNIFY_OPTIONS)
 
-    # Handle HTML files by converting them to Markdown
     if filename.endswith(".html"):
-        return md(content, **MARKDOWNIFY_OPTIONS)
+        return markdownify.markdownify(content, **MARKDOWNIFY_OPTIONS)
 
-    # Fallback to returning raw content
     return content
 
 
@@ -181,9 +200,7 @@ def get_local_path(filename: str) -> str:
     Returns:
         The full local path to the cached markdown file.
     """
-    # Flatten the filename by replacing '/' with '-'
     flattened = filename.replace("/", "-")
-    # Use the flattened filename and change extension to .md for uniform storage
     base_name = flattened.rsplit(".", 1)[0]
     return os.path.join(get_guides_dir(), f"{base_name}.md")
 
@@ -227,7 +244,6 @@ def get_guide(language: str, remote: bool = False) -> str:
     Raises:
         click.UsageError: If the language is not supported.
     """
-    # Look up the filename in the mapping
     filename = LANGUAGE_MAP.get(language.lower())
     if not filename:
         error_msg = f"Language '{language}' is not supported."
@@ -239,7 +255,6 @@ def get_guide(language: str, remote: bool = False) -> str:
 
     local_path = get_local_path(filename)
 
-    # If remote is False, check for local file first
     if not remote and os.path.exists(local_path):
         logger.info("Reading style guide from local file: %s", local_path)
         with open(local_path, encoding="utf-8") as f:

{readability_cli-0.10.3 → readability_cli-0.10.5}/test_checking.py

@@ -1030,7 +1030,7 @@ def test_bundled_default_configs_are_valid() -> None:
         "indentWidth": 2,
         "lineWidth": 80,
     }
-    assert biome_config["linter"]["rules"]["recommended"] is True
+    assert biome_config["linter"]["rules"]["preset"] == "recommended"
     assert biome_config["html"]["parser"]["interpolation"] is True
 
     # The ruff defaults follow the Google Python style guide

{readability_cli-0.10.3 → readability_cli-0.10.5}/test_outline.py

@@ -4,6 +4,7 @@ from pathlib import Path
 from unittest.mock import MagicMock
 from unittest.mock import patch
 
+import click
 from click.testing import CliRunner
 
 from readability.cli import cli
@@ -787,6 +788,21 @@ def test_sync_deduplicates_aliases(
     assert mock_get_content.call_count == 1
 
 
+@patch("readability.guide.get_guide_content")
+def test_sync_reports_a_failed_fetch_in_its_exit_code(
+    mock_get_content: MagicMock, tmp_path: Path
+) -> None:
+    """A stale local copy left behind is a failure, not a quiet success."""
+    mock_get_content.side_effect = click.ClickException("network is down")
+
+    with patch("readability.guide.get_guides_dir", return_value=str(tmp_path)):
+        runner = CliRunner()
+        result = runner.invoke(cli, ["sync", "python"])
+
+    assert result.exit_code != 0
+    assert "Failures: 1" in result.stderr
+
+
 def test_sync_rejects_an_unsupported_language(tmp_path: Path) -> None:
     """An unknown language is a typo, not a reason to sync everything."""
     with patch("readability.guide.get_guides_dir", return_value=str(tmp_path)):

{readability_cli-0.10.3 → readability_cli-0.10.5}/uv.lock

@@ -1,7 +1,11 @@
 version = 1
-revision = 3
+revision = 5
 requires-python = ">=3.12"
 
+[options]
+exclude-newer = "0001-01-01T00:00:00Z" # This has no effect and is included for backwards compatibility when using relative exclude-newer values.
+exclude-newer-span = "PT24H"
+
 [[package]]
 name = "beautifulsoup4"
 version = "4.14.3"
@@ -194,11 +198,15 @@ wheels = [
 
 [[package]]
 name = "readability-cli"
-version = "0.10.3"
+version = "0.10.5"
 source = { editable = "." }
 dependencies = [
-    { name = "beautifulsoup4" },
     { name = "click" },
+]
+
+[package.optional-dependencies]
+sync = [
+    { name = "beautifulsoup4" },
     { name = "markdownify" },
     { name = "requests" },
 ]
@@ -206,20 +214,23 @@ dependencies = [
 [package.dev-dependencies]
 dev = [
     { name = "pytest" },
+    { name = "readability-cli", extra = ["sync"] },
     { name = "ruff" },
 ]
 
 [package.metadata]
 requires-dist = [
-    { name = "beautifulsoup4", specifier = ">=4.14.3" },
+    { name = "beautifulsoup4", marker = "extra == 'sync'", specifier = ">=4.14.3" },
     { name = "click", specifier = ">=8.3.1" },
-    { name = "markdownify", specifier = ">=1.2.2" },
-    { name = "requests", specifier = ">=2.33.0" },
+    { name = "markdownify", marker = "extra == 'sync'", specifier = ">=1.2.2" },
+    { name = "requests", marker = "extra == 'sync'", specifier = ">=2.33.0" },
 ]
+provides-extras = ["sync"]
 
 [package.metadata.requires-dev]
 dev = [
     { name = "pytest", specifier = ">=9.0.2" },
+    { name = "readability-cli", extras = ["sync"] },
     { name = "ruff", specifier = ">=0.15.8" },
 ]