ruff-explain 1.0.0__tar.gz

ruff_explain-1.0.0/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.3
+Name: ruff-explain
+Version: 1.0.0
+Summary: Render Ruff rule docs in the terminal or open them in a browser
+Author: Jakob Guldberg Aaes
+Author-email: Jakob Guldberg Aaes <jakob1379@gmali.com>
+Requires-Dist: rich>=14.3.3
+Requires-Dist: typer>=0.24.1
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# ruff-explain
+
+`ruff-explain` looks up Ruff rule documentation by rule ID and renders the docs page directly in your terminal with Rich.
+
+![Example render](example.png)
+
+## What it does
+
+- Renders Ruff rule docs in the terminal by default.
+- Opens the canonical docs page in your browser with `-o` / `--open`.
+- Resolves rule IDs like `FAST001`, `F401`, and `ARG001` from a bundled rule map.
+- Keeps the output focused on the actual rule content instead of full site chrome.
+
+## Usage
+
+```bash
+uv run ruff-explain FAST001
+uv run ruff-explain F401
+uv run ruff-explain ARG001 -o
+```
+
+## Run from source
+
+Run it from the repo with `uv`:
+
+```bash
+uv run ruff-explain FAST001
+```
+
+## Notes
+
+- Default behavior is terminal rendering.
+- `--open` skips rendering, opens the docs page immediately, and exits.
+- Unknown rule IDs return a non-zero exit code and show close matches when available.

ruff_explain-1.0.0/README.md

@@ -0,0 +1,34 @@
+# ruff-explain
+
+`ruff-explain` looks up Ruff rule documentation by rule ID and renders the docs page directly in your terminal with Rich.
+
+![Example render](example.png)
+
+## What it does
+
+- Renders Ruff rule docs in the terminal by default.
+- Opens the canonical docs page in your browser with `-o` / `--open`.
+- Resolves rule IDs like `FAST001`, `F401`, and `ARG001` from a bundled rule map.
+- Keeps the output focused on the actual rule content instead of full site chrome.
+
+## Usage
+
+```bash
+uv run ruff-explain FAST001
+uv run ruff-explain F401
+uv run ruff-explain ARG001 -o
+```
+
+## Run from source
+
+Run it from the repo with `uv`:
+
+```bash
+uv run ruff-explain FAST001
+```
+
+## Notes
+
+- Default behavior is terminal rendering.
+- `--open` skips rendering, opens the docs page immediately, and exits.
+- Unknown rule IDs return a non-zero exit code and show close matches when available.

ruff_explain-1.0.0/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "ruff-explain"
+version = "1.0.0"
+description = "Render Ruff rule docs in the terminal or open them in a browser"
+readme = "README.md"
+authors = [
+    { name = "Jakob Guldberg Aaes", email = "jakob1379@gmali.com" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "rich>=14.3.3",
+    "typer>=0.24.1",
+]
+
+[project.scripts]
+ruff-explain = "ruff_explain:main"
+
+[build-system]
+requires = ["uv_build>=0.10.9,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+]

ruff_explain-1.0.0/src/ruff_explain/__init__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+__all__ = ["main"]

ruff_explain-1.0.0/src/ruff_explain/cli.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from difflib import get_close_matches
+import webbrowser
+
+import typer
+from rich.console import Console
+
+from .render import RulePageError, build_rule_renderable
+from .rules import BASE_URL, RULES
+
+app = typer.Typer(
+    add_completion=False, help="Look up Ruff rule documentation by rule ID."
+)
+console = Console()
+error_console = Console(stderr=True)
+
+
+def _rule_url(rule_id: str) -> str | None:
+    rule = RULES.get(rule_id.strip().upper())
+    if rule is None:
+        return None
+    return f"{BASE_URL}{rule['slug']}/"
+
+
+def _unknown_rule(rule_id: str) -> None:
+    normalized = rule_id.strip().upper()
+    matches = get_close_matches(normalized, RULES, n=3, cutoff=0.6)
+    error_console.print(f"[bold red]Unknown Ruff rule:[/bold red] {normalized}")
+    if matches:
+        error_console.print(f"Did you mean: {', '.join(matches)}")
+    raise typer.Exit(code=1)
+
+
+@app.command()
+def lookup(
+    rule_id: str = typer.Argument(..., help="Ruff rule ID, for example FAST001."),
+    open_page: bool = typer.Option(
+        False, "--open", "-o", help="Open the docs page in your browser."
+    ),
+) -> None:
+    url = _rule_url(rule_id)
+    if url is None:
+        _unknown_rule(rule_id)
+
+    if open_page:
+        webbrowser.open_new_tab(url)
+        return
+
+    normalized = rule_id.strip().upper()
+    try:
+        console.print(build_rule_renderable(normalized, url, width=console.size.width))
+    except RulePageError as exc:
+        error_console.print(f"[bold red]Render failed:[/bold red] {exc}")
+        console.print(f"[bold]{normalized}[/bold]")
+        console.print(f"[link={url}]{url}[/link]")
+        raise typer.Exit(code=1) from exc
+
+
+def main() -> None:
+    app()

ruff_explain-1.0.0/src/ruff_explain/render.py

@@ -0,0 +1,390 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from html.parser import HTMLParser
+import re
+from typing import Callable
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from rich.console import Group, RenderableType
+from rich.panel import Panel
+from rich.syntax import Syntax
+from rich.table import Table
+from rich.text import Text
+
+from .rules import RULES
+
+_WHITESPACE_RE = re.compile(r"\s+")
+_TITLE_RE = re.compile(r"^(?P<name>.+?)\s+\((?P<code>[A-Z]+\d+)\)$")
+_FIX_STYLES = {
+    "Always": "bold green",
+    "Sometimes": "bold yellow",
+    "None": "bold red",
+}
+
+
+class RulePageError(RuntimeError):
+    pass
+
+
+@dataclass
+class HtmlNode:
+    tag: str
+    attrs: dict[str, str]
+    children: list[HtmlNode | str] = field(default_factory=list)
+
+
+@dataclass
+class ParagraphBlock:
+    text: str
+
+
+@dataclass
+class ListBlock:
+    items: list[str]
+
+
+@dataclass
+class CodeBlock:
+    code: str
+
+
+@dataclass
+class Section:
+    title: str
+    blocks: list[ParagraphBlock | ListBlock | CodeBlock] = field(default_factory=list)
+
+
+@dataclass
+class RulePage:
+    name: str
+    code: str
+    linter: str
+    status: str
+    since: str
+    fix: str
+    url: str
+    intro_blocks: list[ParagraphBlock | ListBlock | CodeBlock]
+    sections: list[Section]
+
+
+class _DomParser(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.root = HtmlNode("document", {})
+        self._stack = [self.root]
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        node = HtmlNode(tag, {key: value or "" for key, value in attrs})
+        self._stack[-1].children.append(node)
+        self._stack.append(node)
+
+    def handle_endtag(self, tag: str) -> None:
+        for index in range(len(self._stack) - 1, 0, -1):
+            if self._stack[index].tag == tag:
+                del self._stack[index:]
+                return
+
+    def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        node = HtmlNode(tag, {key: value or "" for key, value in attrs})
+        self._stack[-1].children.append(node)
+
+    def handle_data(self, data: str) -> None:
+        if data:
+            self._stack[-1].children.append(data)
+
+
+def fetch_rule_page(url: str) -> str:
+    request = Request(url, headers={"User-Agent": "ruff-explain"})
+    try:
+        with urlopen(request, timeout=15) as response:
+            charset = response.headers.get_content_charset() or "utf-8"
+            return response.read().decode(charset)
+    except (HTTPError, URLError) as exc:
+        raise RulePageError(f"Could not fetch {url}: {exc}") from exc
+
+
+def build_rule_renderable(
+    rule_id: str, url: str, html: str | None = None, width: int = 80
+) -> RenderableType:
+    normalized = rule_id.strip().upper()
+    document = parse_rule_page(normalized, url, html or fetch_rule_page(url))
+
+    renderables: list[RenderableType] = [_render_header_panel(document)]
+    for section in document.sections:
+        renderables.append(_render_section(section, width))
+    return Group(*renderables)
+
+
+def parse_rule_page(rule_id: str, url: str, html: str) -> RulePage:
+    parser = _DomParser()
+    parser.feed(html)
+    article = _find_first(
+        parser.root,
+        lambda node: node.tag == "article" and _has_class(node, "md-content__inner"),
+    )
+    if article is None:
+        raise RulePageError("Could not find the Ruff article content in the page.")
+
+    rule = RULES[rule_id]
+    title = _extract_title(article) or f"{rule['slug']} ({rule_id})"
+    match = _TITLE_RE.match(title)
+    name = match.group("name") if match else title
+    code = match.group("code") if match else rule_id
+
+    sections = _extract_sections(article)
+    intro_blocks: list[ParagraphBlock | ListBlock | CodeBlock] = []
+    if sections and sections[0].title == "Overview":
+        intro_blocks = sections.pop(0).blocks
+
+    return RulePage(
+        name=name,
+        code=code,
+        linter=rule["linter"],
+        status=rule["status"],
+        since=rule["since"],
+        fix=rule["fix"],
+        url=url,
+        intro_blocks=intro_blocks,
+        sections=sections,
+    )
+
+
+def _extract_title(article: HtmlNode) -> str | None:
+    heading = _first_child(article, "h1")
+    if heading is None:
+        return None
+    title = _collapse(_inline_text(heading))
+    return title or None
+
+
+def _extract_sections(article: HtmlNode) -> list[Section]:
+    sections: list[Section] = []
+    current = Section("Overview")
+    saw_content = False
+
+    for child in article.children:
+        if isinstance(child, str):
+            continue
+        if child.tag == "h1":
+            continue
+        if child.tag == "p" and _contains_tag(child, "small"):
+            continue
+        if child.tag in {"h2", "h3"}:
+            title = _collapse(_inline_text(child))
+            if current.blocks:
+                sections.append(current)
+            current = Section(title)
+            saw_content = True
+            continue
+
+        block = _extract_block(child)
+        if block is None:
+            continue
+
+        if not saw_content and not current.blocks:
+            current = Section("Overview")
+        current.blocks.append(block)
+
+    if current.blocks:
+        sections.append(current)
+
+    return sections
+
+
+def _extract_block(node: HtmlNode) -> ParagraphBlock | ListBlock | CodeBlock | None:
+    if node.tag == "p":
+        text = _collapse(_inline_text(node))
+        return ParagraphBlock(text) if text else None
+    if node.tag in {"ul", "ol"}:
+        items = []
+        for child in node.children:
+            if isinstance(child, HtmlNode) and child.tag == "li":
+                text = _collapse(_inline_text(child))
+                if text:
+                    items.append(text)
+        return ListBlock(items) if items else None
+    if node.tag == "div" and _has_class(node, "highlight"):
+        code = _extract_code(node)
+        return CodeBlock(code) if code else None
+    if node.tag == "pre":
+        code = _extract_code(node)
+        return CodeBlock(code) if code else None
+    return None
+
+
+def _extract_code(node: HtmlNode) -> str:
+    code_node = _find_first(node, lambda child: child.tag == "code")
+    source = code_node or node
+    code = _node_text(source)
+    lines = [line.rstrip() for line in code.splitlines()]
+    while lines and not lines[0]:
+        lines.pop(0)
+    while lines and not lines[-1]:
+        lines.pop()
+    return "\n".join(lines)
+
+
+def _render_header_panel(page: RulePage) -> Panel:
+    title = Text(page.name)
+    title.append(f" ({page.code})")
+    title.stylize(f"link {page.url}")
+    title.stylize("underline cyan")
+
+    header = Text()
+    header.append("Linter: ", style="bold")
+    header.append(page.linter)
+    header.append(" - ")
+    header.append("Status: ", style="bold")
+    header.append(page.status)
+    header.append(" - ")
+    header.append("Added: ", style="bold")
+    header.append(page.since)
+    header.append(" - ")
+    header.append("Fix: ", style="bold")
+    header.append(page.fix, style=_FIX_STYLES.get(page.fix, "bold"))
+    header.justify = "center"
+
+    body_renderables: list[RenderableType] = [header]
+    intro = _render_blocks(page.intro_blocks)
+    if intro is not None:
+        body_renderables.append(Text())
+        body_renderables.append(intro)
+
+    return Panel(
+        Group(*body_renderables),
+        title=title,
+        border_style="cyan",
+        padding=(0, 1),
+    )
+
+
+def _render_section(section: Section, width: int) -> RenderableType:
+    if section.title.casefold() == "example":
+        return _render_example_section(section, width)
+
+    body = _render_blocks(section.blocks)
+    return Panel(body, title=section.title, border_style="blue", padding=(0, 1))
+
+
+def _render_example_section(section: Section, width: int) -> RenderableType:
+    example_blocks: list[ParagraphBlock | ListBlock | CodeBlock] = []
+    preferred_blocks: list[ParagraphBlock | ListBlock | CodeBlock] = []
+    target = example_blocks
+
+    for block in section.blocks:
+        if isinstance(block, ParagraphBlock) and block.text.casefold().startswith(
+            "use instead"
+        ):
+            target = preferred_blocks
+            continue
+        target.append(block)
+
+    example_panel = Panel(
+        _render_blocks(example_blocks),
+        title="Example: Python",
+        border_style="yellow",
+        padding=(0, 1),
+    )
+    if not preferred_blocks:
+        return example_panel
+
+    preferred_panel = Panel(
+        _render_blocks(preferred_blocks),
+        title="Use instead: Python",
+        border_style="green",
+        padding=(0, 1),
+    )
+    if width >= 120:
+        table = Table.grid(expand=True, padding=(0, 1))
+        table.add_column(ratio=1)
+        table.add_column(ratio=1)
+        table.add_row(example_panel, preferred_panel)
+        return table
+    return Group(example_panel, preferred_panel)
+
+
+def _render_blocks(
+    blocks: list[ParagraphBlock | ListBlock | CodeBlock],
+) -> RenderableType | None:
+    if not blocks:
+        return None
+    renderables: list[RenderableType] = []
+    for block in blocks:
+        if isinstance(block, ParagraphBlock):
+            renderables.append(Text(block.text))
+        elif isinstance(block, ListBlock):
+            renderables.extend(Text(f"- {item}") for item in block.items)
+        else:
+            renderables.append(
+                Syntax(block.code, "python", line_numbers=False, word_wrap=False)
+            )
+    spaced: list[RenderableType] = []
+    for index, renderable in enumerate(renderables):
+        if index:
+            spaced.append(Text())
+        spaced.append(renderable)
+    return Group(*spaced)
+
+
+def _first_child(node: HtmlNode, tag: str) -> HtmlNode | None:
+    for child in node.children:
+        if isinstance(child, HtmlNode) and child.tag == tag:
+            return child
+    return None
+
+
+def _find_first(
+    node: HtmlNode, predicate: Callable[[HtmlNode], bool]
+) -> HtmlNode | None:
+    if predicate(node):
+        return node
+    for child in node.children:
+        if isinstance(child, HtmlNode):
+            found = _find_first(child, predicate)
+            if found is not None:
+                return found
+    return None
+
+
+def _walk(node: HtmlNode) -> list[HtmlNode]:
+    nodes = [node]
+    for child in node.children:
+        if isinstance(child, HtmlNode):
+            nodes.extend(_walk(child))
+    return nodes
+
+
+def _has_class(node: HtmlNode, class_name: str) -> bool:
+    return class_name in node.attrs.get("class", "").split()
+
+
+def _contains_tag(node: HtmlNode, tag: str) -> bool:
+    return _find_first(node, lambda child: child.tag == tag) is not None
+
+
+def _node_text(node: HtmlNode | str) -> str:
+    if isinstance(node, str):
+        return node
+    if node.tag == "br":
+        return "\n"
+    return "".join(_node_text(child) for child in node.children)
+
+
+def _inline_text(node: HtmlNode | str) -> str:
+    if isinstance(node, str):
+        return node
+    if node.tag == "br":
+        return "\n"
+    if node.tag == "code":
+        return f"`{_collapse(_node_text(node))}`"
+    return "".join(_inline_text(child) for child in node.children)
+
+
+def _collapse(text: str) -> str:
+    parts = [
+        _WHITESPACE_RE.sub(" ", line).strip()
+        for line in text.replace("\xa0", " ").splitlines()
+    ]
+    return " ".join(part for part in parts if part).strip()