pdoc.web

  1"""
  2This module implements pdoc's live-reloading webserver.
  3
  4We want to keep the number of dependencies as small as possible,
  5so we are content with the builtin `http.server` module.
  6It is a bit unergonomic compared to let's say flask, but good enough for our purposes.
  7"""
  8
  9from __future__ import annotations
 10
 11import http.server
 12import traceback
 13import warnings
 14import webbrowser
 15from collections.abc import Iterable, Iterator
 16from typing import Mapping
 17
 18from pdoc import doc, extract, render
 19from pdoc._compat import cache, removesuffix
 20
 21
 22class DocHandler(http.server.BaseHTTPRequestHandler):
 23    """A handler for individual requests."""
 24
 25    server: DocServer
 26    """A reference to the main web server."""
 27
 28    def do_HEAD(self):
 29        try:
 30            return self.handle_request()
 31        except ConnectionError:  # pragma: no cover
 32            pass
 33
 34    def do_GET(self):
 35        try:
 36            self.wfile.write(self.handle_request().encode())
 37        except ConnectionError:  # pragma: no cover
 38            pass
 39
 40    def handle_request(self) -> str | None:
 41        """Actually handle a request. Called by `do_HEAD` and `do_GET`."""
 42        path = self.path.split("?", 1)[0]
 43
 44        if path == "/" or path == "/index.html":
 45            out = render.html_index(self.server.all_modules)
 46        elif path == "/search.js":
 47            self.send_response(200)
 48            self.send_header("content-type", "application/javascript")
 49            self.end_headers()
 50            return self.server.render_search_index()
 51        else:
 52            module_name = removesuffix(path.lstrip("/"), ".html").replace("/", ".")
 53            if module_name not in self.server.all_modules:
 54                self.send_response(404)
 55                self.send_header("content-type", "text/html")
 56                self.end_headers()
 57                return render.html_error(error=f"Module {module_name!r} not found")
 58
 59            mtime = ""
 60            t = extract.module_mtime(module_name)
 61            if t:
 62                mtime = f"{t:.1f}"
 63            if "mtime=1" in self.path:
 64                self.send_response(200)
 65                self.send_header("content-type", "text/plain")
 66                self.end_headers()
 67                return mtime
 68
 69            try:
 70                extract.invalidate_caches(module_name)
 71                mod = self.server.all_modules[module_name]
 72                out = render.html_module(
 73                    module=mod,
 74                    all_modules=self.server.all_modules,
 75                    mtime=mtime,
 76                )
 77            except Exception:
 78                self.send_response(500)
 79                self.send_header("content-type", "text/html")
 80                self.end_headers()
 81                return render.html_error(
 82                    error=f"Error importing {module_name!r}",
 83                    details=traceback.format_exc(),
 84                )
 85
 86        self.send_response(200)
 87        self.send_header("content-type", "text/html")
 88        self.end_headers()
 89        return out
 90
 91    def log_request(self, code: int | str = ..., size: int | str = ...) -> None:
 92        """Override logging to disable it."""
 93        pass
 94
 95
 96class DocServer(http.server.HTTPServer):
 97    """pdoc's live-reloading web server"""
 98
 99    all_modules: AllModules
100
101    def __init__(self, addr: tuple[str, int], specs: list[str], **kwargs):
102        super().__init__(addr, DocHandler, **kwargs)  # type: ignore
103        module_names = extract.walk_specs(specs)
104        self.all_modules = AllModules(module_names)
105
106    @cache
107    def render_search_index(self) -> str:
108        """Render the search index. For performance reasons this is always cached."""
109        # Some modules may not be importable, which means that they would raise an RuntimeError
110        # when accessed. We "fix" this by pre-loading all modules here and only passing the ones that work.
111        all_modules_safe = {}
112        for mod in self.all_modules:
113            try:
114                all_modules_safe[mod] = doc.Module.from_name(mod)
115            except RuntimeError:
116                warnings.warn(f"Error importing {mod!r}:\n{traceback.format_exc()}")
117        return render.search_index(all_modules_safe)
118
119
120class AllModules(Mapping[str, doc.Module]):
121    """A lazy-loading implementation of all_modules.
122
123    This behaves like a regular dict, but modules are only imported on demand for performance reasons.
124    This has the somewhat annoying side effect that __getitem__ may raise a RuntimeError.
125    We can ignore that when rendering HTML as the default templates do not access all_modules values,
126    but we need to perform additional steps for the search index.
127    """
128
129    def __init__(self, allowed_modules: Iterable[str]):
130        # use a dict to preserve order
131        self.allowed_modules: dict[str, None] = dict.fromkeys(allowed_modules)
132
133    def __len__(self) -> int:
134        return self.allowed_modules.__len__()
135
136    def __iter__(self) -> Iterator[str]:
137        return self.allowed_modules.__iter__()
138
139    def __contains__(self, item):
140        return self.allowed_modules.__contains__(item)
141
142    def __getitem__(self, item: str):
143        if item in self.allowed_modules:
144            return doc.Module.from_name(item)
145        else:  # pragma: no cover
146            raise KeyError(item)
147
148
149# https://github.com/mitmproxy/mitmproxy/blob/af3dfac85541ce06c0e3302a4ba495fe3c77b18a/mitmproxy/tools/web/webaddons.py#L35-L61
150def open_browser(url: str) -> bool:  # pragma: no cover
151    """
152    Open a URL in a browser window.
153    In contrast to `webbrowser.open`, we limit the list of suitable browsers.
154    This gracefully degrades to a no-op on headless servers, where `webbrowser.open`
155    would otherwise open lynx.
156
157    Returns:
158
159    - `True`, if a browser has been opened
160    - `False`, if no suitable browser has been found.
161    """
162    browsers = (
163        "windows-default",
164        "macosx",
165        "wslview %s",
166        "x-www-browser %s",
167        "gnome-open %s",
168        "google-chrome",
169        "chrome",
170        "chromium",
171        "chromium-browser",
172        "firefox",
173        "opera",
174        "safari",
175    )
176    for browser in browsers:
177        try:
178            b = webbrowser.get(browser)
179        except webbrowser.Error:
180            pass
181        else:
182            if b.open(url):
183                return True
184    return False