python-arch-wiki 0.1.0__py3-none-any.whl

python_arch_wiki/toc.py

@@ -0,0 +1,468 @@
+import logging
+import os
+import re
+import sys
+import time
+from collections.abc import Iterator
+
+import requests
+from bs4 import BeautifulSoup
+from bs4.element import Tag
+from rich import box
+from rich.console import Console
+from rich.markup import escape
+from rich.table import Table
+
+# use Console() for paging, set default text color
+console = Console(style="color(248)")
+# set less as the pager
+os.environ["MANPAGER"] = "less --raw-control-chars --mouse"
+
+logger = logging.getLogger(__name__)
+
+
+class Toc:
+    """Arch wiki table of contents."""
+
+    root_url = "https://wiki.archlinux.org"
+    toc_session = requests.Session()
+    link_url: bool | None = None
+
+    Section = tuple[int, ...] | None
+    TocItem = tuple[Section, str, str, int]
+    MenuItem = tuple[Section, str]
+    Article = tuple[str, str]
+
+    section: Section
+    title: str
+    href: str
+    articles: list[Article]
+    num_articles: int
+    subsections: list["Toc"]
+    folded: bool
+
+    def __init__(
+        self,
+        section: Tag | TocItem | None = None,
+        folded=True,
+        link_url=False,
+    ) -> None:
+        """Initialize Toc section."""
+        if type(self).link_url is None:
+            type(self).link_url = link_url
+
+        self.subsections = []
+        self.articles = []
+
+        if section is None:
+            for i in range(1, 4):
+                try:
+                    r = self.toc_session.get(
+                        self._url_from_parts(
+                            [self.root_url, "/title/Table_of_contents"]
+                        ),
+                        timeout=2,
+                    )
+                    r.raise_for_status()
+
+                    soup = BeautifulSoup(r.text, "lxml")
+                    rows = soup.select("#wiki-scripts-toc-table tr")
+                    section = rows[0]
+                    for row in rows[1:]:
+                        self.add_subsection(row, folded=folded)
+
+                    break
+
+                except requests.exceptions.ConnectionError as e:
+                    time.sleep(0.5 * i)
+                    logger.warning(f"Connection reset: {i=}: {e}")
+                    continue
+
+                except requests.exceptions.RequestException as e:
+                    logger.error(f"{e}")
+                    sys.exit(f"{e}")
+
+        if isinstance(section, tuple):
+            self.section, self.title, self.href, self.num_articles = section
+        elif isinstance(section, Tag):
+            self.section, self.title, self.href, self.num_articles = (
+                self.parse_tag(section)
+            )
+
+        self.folded = False if self.section is None else folded
+
+    def close(self) -> None:
+        """Close session."""
+        self.toc_session.close()
+
+    def add_subsection(self, tag: Tag, folded: bool = False) -> None:
+        """Add a subsection to table of contents."""
+        subsection = self.parse_tag(tag)
+        assert subsection[0], "Can not add subsection without section"
+
+        # create a nested structure using section as a tuple of indices
+        parent = self
+        for i in subsection[0][:-1]:
+            parent = parent.subsections[i - 1]
+
+        parent.subsections.append(Toc(subsection, folded=folded))
+
+    def parse_tag(self, trtag: Tag) -> TocItem:
+        """Extract section info from tr tag into a tuple."""
+        a = trtag.find("a") if trtag else None
+        if a is None:
+            raise ValueError("'a' tag not found")
+
+        title = a.get_text()
+        href = str(a["href"])
+
+        try:
+            section = tuple(
+                int(x)
+                for x in a.find_previous_sibling("small")
+                .get_text()  # type: ignore
+                .strip(".")
+                .split(".")
+            )
+
+        except (AttributeError, ValueError):
+            section = None
+
+        try:
+            num_articles = int(
+                a.find_next_sibling("small")
+                .get_text()  # type: ignore
+                .strip("()")
+            )
+
+        except (AttributeError, ValueError):
+            num_articles = 0
+
+        if not title or not href:
+            raise ValueError(f"Failed to parse tag: {a}")
+        else:
+            return section, title, href, num_articles
+
+    def get_entries(
+        self,
+        section: "Toc | None" = None,
+        toc_list: list[MenuItem] | None = None,
+    ) -> list[MenuItem]:
+        """Return a list of section/title tuples."""
+        if section is None:
+            section = self
+        if toc_list is None:
+            toc_list = []
+
+        if section.section:
+            section_str = (
+                f"{' ' * 4 * (len(section.section) - 1)}"
+                f"{section.section[-1]:>2}. "
+            )
+
+            if section.num_articles:
+                num_art_str = f" ({section.num_articles})"
+            else:
+                num_art_str = ""
+
+            if section.folded and section.subsections:
+                subsect_str = f" *{len(section.subsections)}"
+            else:
+                subsect_str = ""
+
+            toc_list.append(
+                (
+                    section.section,
+                    f"{section_str}{section.title}{num_art_str}{subsect_str}",
+                )
+            )
+
+        if section.subsections and not section.folded:
+            for subsection in section.subsections:
+                self.get_entries(subsection, toc_list)
+
+        return toc_list
+
+    def __iter__(self) -> Iterator[MenuItem]:
+        """Return Toc iterator."""
+        return iter(self.get_entries())
+
+    def fold(self, section: Section) -> None:
+        """Toggle displaying subsections."""
+
+        if isinstance(section, tuple):
+            subsection = self
+            for i in section:
+                subsection = subsection.subsections[i - 1]
+            subsection.folded = not subsection.folded
+
+    @staticmethod
+    def _url_from_parts(parts: list) -> str:
+        return "/".join(part.strip("/") for part in parts)
+
+    def get_submenu(self, section: Section) -> list[Article]:
+        """Return list of articles."""
+        assert section, "Valid section required"
+        subsection = self
+        for i in section:
+            subsection = subsection.subsections[i - 1]
+
+        if not subsection.articles:
+            try:
+                with self.toc_session.get(
+                    self._url_from_parts([self.root_url, subsection.href]),
+                    timeout=2,
+                ) as r:
+                    r.raise_for_status()
+
+                    soup = BeautifulSoup(r.text, "lxml")
+                    categories = soup.select_one(".mw-category")
+                    if categories:
+                        for a in categories.select("a"):
+                            subsection.articles.append(
+                                (str(a["href"]), str(a["title"]))
+                            )
+
+            except requests.exceptions.RequestException as e:
+                self.close()
+                logger.error(f"{e}")
+                sys.exit(f"{e}")
+
+        return subsection.articles
+
+    @staticmethod
+    def _console_print(text: str) -> None:
+        """Add escape sequences and print."""
+        text = re.sub(  # Command highlight
+            r"""
+                (^|:\s)         # 1) start of the line or colon space
+                ([#\$])         # 2) hash or dollar
+                (\s[a-z]\S*)    # 3) space, letter, one or more of not a space
+                (.*)            # 4) rest of the line
+            """,
+            r"\1[bold][green]\2[/][bright_white]\3[/]\4[/]",
+            text,
+            flags=re.MULTILINE | re.VERBOSE,
+        )
+        text = re.sub(  # Option highlight
+            r"(\s-[\w-]+\b)",
+            r"[bold color(103)]\1[/]",
+            text,
+        )
+        console.print(text)
+
+    @staticmethod
+    def get_table_rows(tr_list: list[Tag]) -> list[list[str]] | None:
+        """Return a list of lists (rows) of strings (cols)."""
+        nrows = len(tr_list)
+        if nrows == 0:
+            return None
+
+        rows = [[] for _ in range(nrows)]
+        rgx = re.compile("t[dh]")
+
+        for col in tr_list[0](rgx):
+            colspan = col.get("colspan")
+            rowspan = col.get("rowspan")
+            coltext = col.get_text()
+            rowspan = rowspan if rowspan is None else int(str(rowspan)) - 1
+
+            if colspan is None:
+                rows[0].append(coltext)
+                for row in rows[1:]:
+                    if rowspan:
+                        row.append("")
+                        rowspan -= 1
+                    else:
+                        row.append(None)
+            else:
+                for _ in range(int(str(colspan))):
+                    rows[0].append(f"[underline]{coltext}[/]")
+                    for row in rows[1:]:
+                        if rowspan:
+                            row.append("")
+                            rowspan -= 1
+                        else:
+                            row.append(None)
+
+        for i, row in enumerate(tr_list[1:]):
+            for j, col in enumerate(row(rgx)):
+                colspan = col.get("colspan")
+                rowspan = col.get("rowspan")
+                coltext = col.get_text()
+                rowspan = 1 if rowspan is None else int(str(rowspan))
+
+                while rows[i + 1][j] is not None:
+                    j += 1
+
+                if colspan is None:
+                    for n in range(rowspan):
+                        rows[i + 1 + n][j] = coltext if n == 0 else ""
+                else:
+                    j -= 1
+                    for _ in range(int(str(colspan))):
+                        j += 1
+                        for n in range(rowspan):
+                            rows[i + 1 + n][j] = (
+                                f"[underline]{coltext}[/]" if n == 0 else ""
+                            )
+
+        return rows
+
+    @classmethod
+    def _parse_section(cls, section: Tag | None) -> None:
+        """Extract text from tags and apply formatting."""
+        if section is None:
+            return
+
+        for tag in section.children:  # type: ignore
+            tag: Tag
+            if tag.name is None:
+                continue
+
+            for code in tag("code"):
+                code.name = "p"
+                code.string = f"[bold white]{code.get_text()}[/]"
+
+            for a in tag("a"):
+                href = str(a.get("href"))
+                text = a.string
+
+                if text and href != text:
+                    a.name = "p"
+                    if href.startswith("/title"):
+                        href = cls._url_from_parts([cls.root_url, href])
+
+                    # do we follow link with url?
+                    text_len = len(text)
+                    href_len = len(href)
+                    if cls.link_url and href.startswith("http"):
+                        text += rf" \[[#515478]{href}[/]]"
+                        if text_len + href_len < console.width:
+                            text = text.replace(" ", "[#515478]_[/]")
+
+                    a.string = f"[bold color(251)]{text}[/]"
+
+            if "mw-heading" in tag.get_attribute_list("class"):
+                console.rule(
+                    f"[white]{tag.get_text()}[/]", style="bright_black"
+                )
+
+            elif "archwiki-template-box" in tag.get_attribute_list("class"):
+                strong: Tag | str | None = tag.find("strong")
+                if strong:
+                    strong = strong.extract().get_text()
+                    color = "bold"
+
+                    match strong.lower():
+                        case "tip":
+                            color += " green"
+                        case "note":
+                            color += " blue"
+                        case "warning":
+                            color += " yellow"
+
+                    cls._console_print(
+                        f"[{color}]{strong}:[/]{tag.get_text()}\n"
+                    )
+                else:
+                    cls._console_print(tag.get_text())
+
+            elif "archwiki-template-message" in tag.get_attribute_list(
+                "class"
+            ):
+                cls._console_print(tag.get_text())
+
+            elif "mw-hidden-catlinks" in tag.get_attribute_list("class"):
+                continue
+
+            elif tag.name == "div":
+                cls._parse_section(tag)
+
+            elif tag.name == "table":
+                caption = tag.find("caption")
+                title = caption.get_text() if caption else None
+                table = Table(
+                    title=title,
+                    box=box.ROUNDED,
+                    highlight=True,
+                    show_lines=True,
+                )
+
+                rows = cls.get_table_rows(tag("tr"))
+                if not rows:
+                    logger.warning(f"Empty table: {tag}")
+                    continue
+
+                for col in rows[0]:
+                    table.add_column(col)
+                for row in rows[1:]:
+                    table.add_row(*row)
+
+                console.print(table)
+
+            else:
+                cls._console_print(tag.get_text())
+
+    @classmethod
+    def display_contents(cls, href: str | tuple[str]) -> None:
+        """Display article."""
+        if isinstance(href, tuple):
+            href = "/title/" + "_".join(href)
+        try:
+            with cls.toc_session.get(
+                cls._url_from_parts([cls.root_url, href]),
+                timeout=1,
+            ) as r:
+                r.raise_for_status()
+                soup = BeautifulSoup(escape(r.text), "lxml")
+
+        except requests.exceptions.RequestException as e:
+            cls.toc_session.close()
+            logger.error(f"{e}")
+            sys.exit(f"{e}")
+
+        with console.pager(styles=True):
+            cls._parse_section(soup.select_one("#bodyContent"))
+
+    def search(self, text: str) -> list[Article]:
+        """Search arch wiki."""
+        search_text = text.strip().replace(" ", "+")
+        payload = {
+            "search": search_text,
+            "title": "Special%3ASearch",
+            "profile": "default",
+            "fulltext": "1",
+        }
+        results = []
+
+        try:
+            with self.toc_session.get(
+                self._url_from_parts([self.root_url, "index.php"]),
+                params=payload,
+                timeout=1,
+            ) as r:
+                r.raise_for_status()
+                soup = BeautifulSoup(r.text, "lxml")
+
+        except requests.exceptions.RequestException as e:
+            logger.error(f"{e}")
+
+        else:
+            for tag in soup.select(".mw-search-result"):
+                heading = tag.find(class_="mw-search-result-heading")
+                if heading and (a := heading.find("a")):
+                    results.append((str(a["href"]), str(a["title"])))
+
+        return results
+
+
+def main() -> None:
+    toc = Toc(folded=False)
+
+    print(toc.get_submenu((1, 1)))
+    toc.close()
+
+
+if __name__ == "__main__":
+    main()

python_arch_wiki-0.1.0.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: python-arch-wiki
+Version: 0.1.0
+Summary: A terminal interface for browsing the Arch Linux Wiki
+Author: Anton Kaplan
+Author-email: Anton Kaplan <anton.kaplan@live.ca>
+License-Expression: GPL-3.0-or-later
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Dist: autocommand>=2.2.2
+Requires-Dist: bs4>=0.0.2
+Requires-Dist: lxml>=6.0.2
+Requires-Dist: platformdirs>=4.11.0
+Requires-Dist: requests>=2.32.5
+Requires-Dist: rich>=14.2.0
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/termctrlseq/python-arch-wiki
+Project-URL: Issues, https://github.com/termctrlseq/python-arch-wiki/issues
+Description-Content-Type: text/markdown
+
+# python-arch-wiki
+
+A terminal interface for browsing the [Arch Linux Wiki](https://wiki.archlinux.org/), with an interactive table of contents and article search.
+
+## Installation
+
+To install in the virtual environment in the directory `python_arch_wiki` and create a link with a name *wiki* (assuming `~/.local/bin` is in the **PATH**):
+```bash
+mkdir python_arch_wiki
+cd python_arch_wiki
+python3 -m venv venv
+venv/bin/python -m pip install \
+    -e 'python-arch-wiki @ git+https://github.com/termctrlseq/python-arch-wiki.git'
+ln -s "$PWD/venv/bin/python-arch-wiki" "$HOME/.local/bin/wiki"
+```
+
+To add `~/.local/bin` to **PATH** put this in your `~/.bashrc`
+```bash
+# add ~/.local/bin to PATH if not in it
+[[ ":${PATH}:" != *:"${HOME}/.local/bin":* ]] \
+    && export PATH="${HOME}/.local/bin:${PATH}"
+```
+
+Then the source code can be found in `~/python_arch_wiki/venv/src/`.
+
+## Usage
+
+```
+wiki [-l] [-v] [article name]
+```
+
+## Options
+
+```text
+-l, --link-url    Show URLs in links
+-v, --verbose     Enable debug logging
+```
+
+## Examples
+
+Open the table of contents:
+
+```bash
+wiki
+```
+
+From there, press `/` to search the Arch Wiki. The search uses the Arch Wiki's own search engine, and the results are presented in a navigable menu. For convenience, this can be preferable to specifying a longer query on the command line:
+
+```text
+/install
+```
+
+For short, specific searches, giving the article name on the command line is often more convenient:
+
+```bash
+wiki zram
+```
+
+## Controls
+
+| Key                                | Action              |
+| ---------------------------------- | ------------------- |
+| `↑` / `k` / `Ctrl-P` / `Shift-Tab` | Previous            |
+| `↓` / `j` / `Ctrl-N` / `Tab`       | Next                |
+| `H`                                | First visible item  |
+| `M`                                | Middle visible item |
+| `L`                                | Last visible item   |
+| `Enter`                            | Open                |
+| `Space` / `l`                      | Fold/unfold         |
+| `h` / `u` / `Esc`                  | Go up               |
+| `/` / `?`                          | Search              |
+| `q` / `Ctrl-D`                     | Quit                |
+
+Mouse input is also supported:
+| Button              | Action      |
+| ------------------- | ----------- |
+| *Left click*        | select      |
+| *Double left click* | open        |
+| *Right click*       | fold/unfold |
+| *Wheel*             | navigate    |
+
+Articles are rendered in the terminal and paged with `less`.
+
+## Requirements
+
+* Python 3.13+
+* A terminal with `curses` support
+* Internet connection

python_arch_wiki-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+python_arch_wiki/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+python_arch_wiki/__main__.py,sha256=Koj2bOv0fnNW9BFQ6dhs1kXhr5ZY9bLt1-aggJv1VX0,1114
+python_arch_wiki/menu.py,sha256=sjtfLww7OcFPpdniGyoWmof_Eu94NRKJiRCf5hWhUIM,10075
+python_arch_wiki/toc.py,sha256=LL7O0k9Cw3f3w5bKS572w9drhAzQd-xtpBwZt9LjhWE,14999
+python_arch_wiki-0.1.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+python_arch_wiki-0.1.0.dist-info/WHEEL,sha256=Kot-FOXwz2no6rGIg4et79Z7m6vcKPAXr2Y6fTFpZuI,81
+python_arch_wiki-0.1.0.dist-info/entry_points.txt,sha256=JgtU2VxggJtVjpkcj8GxmpTNzPqD0a4wcjxqqWfMCXs,69
+python_arch_wiki-0.1.0.dist-info/METADATA,sha256=U9ew55rU3XjNjUhd4lxl5IcMbkuS63kVuZ0x3iQoeG0,3378
+python_arch_wiki-0.1.0.dist-info/RECORD,,

python_arch_wiki-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.10
+Root-Is-Purelib: true
+Tag: py3-none-any

python_arch_wiki-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+python-arch-wiki = python_arch_wiki.__main__:main
+