readability-cli 0.10.0__tar.gz → 0.10.1__tar.gz

{readability_cli-0.10.0 → readability_cli-0.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: readability-cli
-Version: 0.10.0
+Version: 0.10.1
 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
@@ -180,8 +180,9 @@ caller happened to be standing in.
 
 Ruff and Pyrefly defaults follow the
 [Google Python style guide](https://google.github.io/styleguide/pyguide.html):
-80-column lines, Google docstrings, import ordering, and full type checking. The
-Biome default applies the 80-column lines and two-space indentation of the
+80-column lines, Google docstrings, one import per line sorted as isort's
+`google` profile does, and full type checking. The Biome default applies the
+80-column lines and two-space indentation of the
 [Google JavaScript style guide](https://google.github.io/styleguide/jsguide.html)
 and enables Biome's recommended lint rules. Project `biome.json` and
 `biome.jsonc` files replace those bundled defaults for Biome-owned formats.

{readability_cli-0.10.0 → readability_cli-0.10.1}/README.md

@@ -166,8 +166,9 @@ caller happened to be standing in.
 
 Ruff and Pyrefly defaults follow the
 [Google Python style guide](https://google.github.io/styleguide/pyguide.html):
-80-column lines, Google docstrings, import ordering, and full type checking. The
-Biome default applies the 80-column lines and two-space indentation of the
+80-column lines, Google docstrings, one import per line sorted as isort's
+`google` profile does, and full type checking. The Biome default applies the
+80-column lines and two-space indentation of the
 [Google JavaScript style guide](https://google.github.io/styleguide/jsguide.html)
 and enables Biome's recommended lint rules. Project `biome.json` and
 `biome.jsonc` files replace those bundled defaults for Biome-owned formats.

{readability_cli-0.10.0 → readability_cli-0.10.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "readability-cli"
-version = "0.10.0"
+version = "0.10.1"
 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"
@@ -47,6 +47,12 @@ ignore = ["PLR0911", "PLR0912", "PLR0913", "PLR0915", "PLR2004"]
 [tool.ruff.lint.pydocstyle]
 convention = "google"
 
+[tool.ruff.lint.isort]
+force-single-line = true
+force-sort-within-sections = true
+single-line-exclusions = ["typing"]
+order-by-type = false
+
 [tool.ruff.lint.per-file-ignores]
 "test_*.py" = ["D"]
 "*_test.py" = ["D"]

{readability_cli-0.10.0 → readability_cli-0.10.1}/readability/checking.py

@@ -1,21 +1,19 @@
 """Run readability checks and report their coverage."""
 
+from collections.abc import Sequence
 import dataclasses
 import logging
-import subprocess
-from collections.abc import Sequence
 from pathlib import Path
+import subprocess
 
 import click
 
-from readability.tools import (
-    ToolPlan,
-    _command_batches,
-    _get_tool_definitions,
-    _repository_root,
-    _should_run_tool,
-    _tool_is_installed,
-)
+from readability.tools import _command_batches
+from readability.tools import _get_tool_definitions
+from readability.tools import _repository_root
+from readability.tools import _should_run_tool
+from readability.tools import _tool_is_installed
+from readability.tools import ToolPlan
 
 logger = logging.getLogger("readability")
 DEFAULT_TIMEOUT = 60

{readability_cli-0.10.0 → readability_cli-0.10.1}/readability/cli.py

@@ -1,21 +1,20 @@
 """Command-line interface for readability."""
 
+from collections.abc import Sequence
 import logging
 import os
 import sys
-from collections.abc import Sequence
 
 import click
 
 from readability.checking import check_paths
-from readability.guide import (
-    LANGUAGE_MAP,
-    get_guide,
-    get_guides_dir,
-    get_local_path,
-    refresh_guide,
-)
-from readability.outline import _echo_outline, _select_section
+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 refresh_guide
+from readability.outline import _echo_outline
+from readability.outline import _select_section
 
 logger = logging.getLogger("readability")
 

{readability_cli-0.10.0 → readability_cli-0.10.1}/readability/configs/ruff.toml

@@ -14,6 +14,14 @@ ignore = ["PLR0911", "PLR0912", "PLR0913", "PLR0915", "PLR2004"]
 [lint.pydocstyle]
 convention = "google"
 
+[lint.isort]
+# Mirrors isort's google profile; its lexicographical and group-by-package
+# options have no ruff equivalent
+force-single-line = true
+force-sort-within-sections = true
+single-line-exclusions = ["typing"]
+order-by-type = false
+
 [lint.per-file-ignores]
 # Docstring requirements are noise in test files
 "test_*.py" = ["D"]

{readability_cli-0.10.0 → readability_cli-0.10.1}/readability/guide.py

@@ -1,14 +1,15 @@
 """Fetch and cache Google style guides."""
 
+from importlib.resources import files
 import logging
 import os
 import warnings
-from importlib.resources import files
 
+from bs4 import BeautifulSoup
+from bs4 import XMLParsedAsHTMLWarning
 import click
-import requests
-from bs4 import BeautifulSoup, XMLParsedAsHTMLWarning
 from markdownify import markdownify as md
+import requests
 
 warnings.filterwarnings("ignore", category=XMLParsedAsHTMLWarning)
 
@@ -55,10 +56,7 @@ LANGUAGE_MAP = {
 
 BASE_URL = "https://google.github.io/styleguide/"
 
-# Style guides are dense with snake_case and dunder identifiers, and escaping
-# their underscores leaves 'from \_\_future\_\_ import' in the text a caller
-# greps or reads. CommonMark would render a bare '__future__' as emphasis, but
-# these guides are consumed as plain text, where fidelity matters more.
+# Escaping underscores would leave 'from \_\_future\_\_ import' in the text
 MARKDOWNIFY_OPTIONS = {"heading_style": "ATX", "escape_underscores": False}
 
 

{readability_cli-0.10.0 → readability_cli-0.10.1}/readability/outline.py

@@ -1,31 +1,27 @@
 """Parse, search, and render style-guide outlines."""
 
+from collections.abc import Iterator
+from collections.abc import Sequence
+from dataclasses import dataclass
 import re
 import sys
-from collections.abc import Iterator, Sequence
-from dataclasses import dataclass
 from typing import Any
 
 import click
 
-# A fence opens or closes a code block; anything inside is sample code, not
-# document structure. Guides for `#`-commented languages (shell, Python) would
-# otherwise report hundreds of code comments as headings.
+# Inside a fence is sample code, where a '#' comment is not a heading
 FENCE_PATTERN = re.compile(r"^\s{0,3}(?:```|~~~)")
 
-# Closing hashes are optional in ATX headings and must be space-separated, so
-# a title such as 'C#' keeps its trailing character.
+# Closing hashes are space-separated, so a title like 'C#' keeps its own
 HEADING_PATTERN = re.compile(r"^(#{1,6})\s+(.*?)(?:\s+#+)?\s*$")
 
-# A section number the document itself prints, e.g. '2.2' in '2.2 Imports'.
+# A number the document prints itself, e.g. '2.2' in '2.2 Imports'
 DOCUMENT_NUMBER_PATTERN = re.compile(r"^(\d+(?:\.\d+)*)\.?\s+(.+)$")
 
-# Guides put a heading's link targets on the lines above it, which would
-# otherwise trail the end of the preceding section.
+# Link targets sit above their heading, not at the end of the one before
 ANCHOR_PATTERN = re.compile(r'^<a id="[^"]*"></a>$')
 
-# The separator in a scoped reference such as 'Imports > Decision'. Spaces on
-# both sides are required so that a heading like '`Array<T>` Type' stays whole.
+# Scoped reference separator; spaces required so '`Array<T>` Type' stays whole
 PATH_SEPARATOR_PATTERN = re.compile(r"\s+>\s+")
 
 
@@ -148,8 +144,7 @@ def parse_headings(content: str) -> list[Heading]:
     if not raw:
         return []
 
-    # Only three of the shipped guides number their headings. A dotted number
-    # ('2.2') is the reliable signal; a bare leading digit is not.
+    # A dotted number is the reliable signal; a bare leading digit is not
     document_numbers = [
         match.group(1)
         for _, _, text in raw
@@ -157,8 +152,7 @@ def parse_headings(content: str) -> list[Heading]:
     ]
     numbered = any("." in number for number in document_numbers)
 
-    # A lone top-level heading is the document title: it roots the tree rather
-    # than being the first section, so numbering starts with its children.
+    # A lone top-level heading is the title, so numbering starts below it
     top_level = min(level for _, level, _ in raw)
     top_level_lines = [line for line, level, _ in raw if level == top_level]
     title_line = top_level_lines[0] if len(top_level_lines) == 1 else None
@@ -169,12 +163,7 @@ def parse_headings(content: str) -> list[Heading]:
         index = "" if line == title_line else _next_index(open_headings, level)
         number, title = _split_document_number(text, numbered)
 
-        # A guide that numbers its own sections is the authority on what they
-        # are called, so its numbers address them. A positional index would
-        # drift wherever the guide skips one — pyguide has no 2.15 at all,
-        # and calling its 2.16 by that name would cite a section that does
-        # not exist. The tree still advances above, so headings the guide
-        # leaves unnumbered keep a positional index to be reachable by.
+        # A guide's own numbers address its sections; an index would drift
         if number:
             index = number
         headings.append(
@@ -203,10 +192,7 @@ def _slugify(text: str) -> str:
     return re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
 
 
-# Sections this long are worth warning about before one is fetched. Measured
-# over the shipped corpus, it marks the 4% that are expensive while leaving
-# the rest unannotated: a size on every line would read '0' on 59% of them,
-# which is noise in the one output whose job is to be scanned quickly.
+# Marks the expensive 4% of the corpus; a size on every line would be noise
 LARGE_SECTION_WORDS = 1200
 
 
@@ -263,8 +249,7 @@ def format_outline(headings: Sequence[Heading], content: str = "") -> str:
             section = extract_section(content, headings, position)
             size = _format_size(len(section.split()))
 
-        # The index already carries the guide's own number where it has one,
-        # so printing the heading verbatim would show it twice.
+        # The index already carries the guide's number where it has one
         lines.append(f"{indent}{prefix}{heading.title}{size}")
 
     return "\n".join(lines)
@@ -281,8 +266,7 @@ def _matches_component(heading: Heading, component: str, exact: bool) -> bool:
     Returns:
         True if the component identifies the heading.
     """
-    # Numbers are only ever compared in full; a substring of a number would
-    # match unrelated sections.
+    # Numbers compare in full; a substring would match unrelated sections
     wanted = component.strip().rstrip(".")
     if wanted and wanted in {heading.index, heading.number}:
         return True
@@ -369,8 +353,7 @@ def find_headings(headings: Sequence[Heading], reference: str) -> list[int]:
     if not components:
         return []
 
-    # Prefer whole matches; fall back to substrings only when nothing matches
-    # in full, so 'Imports' does not also select 'Imports and Exports'.
+    # Whole matches first, so 'Imports' does not select 'Imports and Exports'
     for exact in (True, False):
         matches = [
             position
@@ -512,9 +495,7 @@ def find_mentions(
 
     lines = content.splitlines()
 
-    # Only an indexed heading can be offered. The document title has no index
-    # because it is the whole guide rather than a section within it, so
-    # crediting the preamble to it would suggest reading everything.
+    # The title has no index, so crediting it would suggest reading everything
     sections = [
         (position, _section_bounds(lines, headings, position))
         for position in range(len(headings))
@@ -526,10 +507,7 @@ def find_mentions(
         if needle not in line.lower():
             continue
 
-        # Bounds nest, so the last section still covering the line is the
-        # innermost one that prints it. A section sheds the anchors of the
-        # heading below it, and those fall to an ancestor rather than to the
-        # section they merely trail.
+        # Bounds nest, so the last one covering a line is what prints it
         holders = [
             position
             for position, (start, end) in sections
@@ -577,8 +555,7 @@ def _echo_outline(content: str, language: str) -> None:
     example = _example_reference(headings)
     if example:
         count = sum(1 for heading in headings if heading.index)
-        # stdout is block-buffered when redirected, so without this the hint
-        # lands above the outline it is meant to follow
+        # Redirected stdout is block-buffered, so the hint would land first
         sys.stdout.flush()
         click.echo(
             f"# {count} sections · print one:  "
@@ -656,8 +633,7 @@ def _select_section(content: str, reference: str, language: str) -> str:
     if not matches:
         _report_no_heading(content, headings, reference, language)
 
-    # Reporting every candidate beats returning the first one silently, since
-    # guides repeat headings ('Decision' appears under every Python rule).
+    # Guides repeat headings, so name every candidate rather than guess
     if len(matches) > 1:
         click.echo(
             f"Error: '{reference}' matches {len(matches)} headings in the "

{readability_cli-0.10.0 → readability_cli-0.10.1}/test_checking.py

@@ -1,20 +1,21 @@
 import json
+from pathlib import Path
 import subprocess
 import tomllib
-from pathlib import Path
-from unittest.mock import MagicMock, call, patch
+from unittest.mock import call
+from unittest.mock import MagicMock
+from unittest.mock import patch
 
-import pytest
 from click.testing import CliRunner
+import pytest
 
-from readability.checking import CheckReport, check_paths
+from readability.checking import check_paths
+from readability.checking import CheckReport
 from readability.cli import cli
-from readability.tools import (
-    TOOL_RUNNERS,
-    _bundled_config,
-    _get_tool_definitions,
-    _has_project_config,
-)
+from readability.tools import _bundled_config
+from readability.tools import _get_tool_definitions
+from readability.tools import _has_project_config
+from readability.tools import TOOL_RUNNERS
 
 
 def _source_file(directory: Path, name: str) -> Path:
@@ -1035,6 +1036,14 @@ def test_bundled_default_configs_are_valid() -> None:
     assert ruff_config["line-length"] == 80
     assert ruff_config["lint"]["pydocstyle"]["convention"] == "google"
 
+    # Import sorting mirrors isort's google profile
+    assert ruff_config["lint"]["isort"] == {
+        "force-single-line": True,
+        "force-sort-within-sections": True,
+        "single-line-exclusions": ["typing"],
+        "order-by-type": False,
+    }
+
 
 @patch("readability.checking._check_path")
 def test_check_paths_aggregates_str_and_path_inputs(

{readability_cli-0.10.0 → readability_cli-0.10.1}/test_guide.py

@@ -1,20 +1,19 @@
 import os
 from pathlib import Path
-from unittest.mock import MagicMock, patch
+from unittest.mock import MagicMock
+from unittest.mock import patch
 
 import click
+from click.testing import CliRunner
 import pytest
 import requests
-from click.testing import CliRunner
 
 from readability.cli import cli
-from readability.guide import (
-    convert_to_markdown,
-    get_guide,
-    get_guide_content,
-    get_guides_dir,
-    get_local_path,
-)
+from readability.guide import convert_to_markdown
+from readability.guide import get_guide
+from readability.guide import get_guide_content
+from readability.guide import get_guides_dir
+from readability.guide import get_local_path
 
 
 def test_get_guide_unsupported() -> None:
@@ -159,8 +158,7 @@ def test_sync_command(
         result = runner.invoke(cli, ["sync"])
 
         assert result.exit_code == 0
-        # Progress is an outcome the caller asked for, so it is reported
-        # regardless of log level rather than logged as narration.
+        # An asked-for outcome, so reported regardless of log level
         assert "Sync complete" in result.stderr
         # Check if at least one guide was "synced" (written to tmp_path)
         assert len(os.listdir(tmp_path)) > 0

{readability_cli-0.10.0 → readability_cli-0.10.1}/test_outline.py

@@ -1,23 +1,21 @@
 import logging
 import os
 from pathlib import Path
-from unittest.mock import MagicMock, patch
+from unittest.mock import MagicMock
+from unittest.mock import patch
 
 from click.testing import CliRunner
 
-from readability.cli import cli, main
-from readability.guide import (
-    LANGUAGE_MAP,
-    get_local_path,
-)
-from readability.outline import (
-    _iter_heading_lines,
-    _unique_reference,
-    extract_section,
-    find_headings,
-    find_mentions,
-    parse_headings,
-)
+from readability.cli import cli
+from readability.cli import main
+from readability.guide import get_local_path
+from readability.guide import LANGUAGE_MAP
+from readability.outline import _iter_heading_lines
+from readability.outline import _unique_reference
+from readability.outline import extract_section
+from readability.outline import find_headings
+from readability.outline import find_mentions
+from readability.outline import parse_headings
 
 NUMBERED_GUIDE = """# Sample Style Guide
 
@@ -456,10 +454,7 @@ def test_cli_section_heading_containing_an_angle_bracket(
     assert "Array body." in result.stdout
 
 
-# The heading scanner is deliberately not a Markdown parser (see the note on
-# _iter_heading_lines). These tests are the evidence for that decision: the
-# scope it covers, the constructs it rejects, and its behaviour over every
-# guide actually shipped. A failure here means the scope has been outgrown.
+# Evidence the scanner need not be a Markdown parser; a failure means it is
 
 
 def test_heading_scanner_rejects_non_headings() -> None:
@@ -551,8 +546,7 @@ def test_every_shipped_guide_parses_into_unique_sections() -> None:
             f"{language}: duplicate positional indices"
         )
 
-        # A heading taken from inside a fence would carry a comment marker
-        # or a shebang, neither of which appears in a real guide heading.
+        # A fenced line would carry a comment marker or a shebang
         for heading in headings:
             assert not heading.title.startswith("!"), (
                 f"{language}: shebang parsed as heading: {heading.title!r}"
@@ -575,9 +569,7 @@ def test_every_shipped_guide_heading_is_addressable() -> None:
         )
         assert titles[0] is headings[0], f"{language}: title is not first"
 
-        # An index alone is not always enough: where a guide prints its own
-        # numbers those drift from the tree, so one string can name two
-        # headings. What must always hold is that some reference resolves.
+        # A guide's own numbers drift, so only 'some reference resolves' holds
         for position, heading in enumerate(headings):
             reference = _unique_reference(headings, position).strip('"')
             matches = find_headings(headings, reference)
@@ -587,9 +579,7 @@ def test_every_shipped_guide_heading_is_addressable() -> None:
             )
 
 
-# Words the corpus uses often enough to exercise many sections at once.
-# 'truefalse' appears only inside pyguide's anchors, which is the shape that
-# used to be credited to whichever section happened to precede them.
+# Common words, plus 'truefalse' which appears only inside pyguide's anchors
 MENTION_PROBES = (
     "truefalse",
     "indent",

{readability_cli-0.10.0 → readability_cli-0.10.1}/test_package.py

@@ -1,8 +1,10 @@
 from importlib.resources import files
 
 import readability
-from readability.checking import CheckReport, check_paths
-from readability.cli import cli, main
+from readability.checking import check_paths
+from readability.checking import CheckReport
+from readability.cli import cli
+from readability.cli import main
 
 
 def test_public_modules_are_importable() -> None:

{readability_cli-0.10.0 → readability_cli-0.10.1}/uv.lock

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

{readability_cli-0.10.0 → readability_cli-0.10.1}/readability/tools.py

@@ -1,13 +1,13 @@
 """Build executable plans for readability's canonical tools."""
 
-import logging
-import os
-import shutil
-import tomllib
 from collections.abc import Sequence
 from dataclasses import dataclass
 from importlib.resources import files
+import logging
+import os
 from pathlib import Path
+import shutil
+import tomllib
 
 logger = logging.getLogger("readability")