webdev 2.0.0__py3-none-any.whl

webdev/index.py

@@ -0,0 +1,298 @@
+# Copyright (C) 2026 KuraLabs S.R.L <info@kuralabs.io>
+# Copyright (C) 2015-2016 Carlos Jenkins <carlos@jenkins.co.cr>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""
+Directory index rendering.
+
+Builds the template context from a filesystem directory and renders it with a
+themed Jinja2 template. Templates live under ``webdev/templates/<theme>/`` and
+are shipped as package data, so new themes are added by dropping in a new
+sibling directory — no code changes required.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from datetime import datetime
+from functools import lru_cache
+from importlib import resources
+from pathlib import Path, PurePosixPath
+
+from jinja2 import Environment, PackageLoader, select_autoescape
+
+#: Template package and root directory inside this package.
+_TEMPLATE_PACKAGE = 'webdev'
+_TEMPLATE_DIR = 'templates'
+
+_INDEX_TEMPLATE = 'index.html.jinja2'
+
+
+class ThemeNotFoundError(Exception):
+    """
+    Raised when a requested theme directory does not exist.
+    """
+
+    def __init__(self, theme: str, available: list[str]) -> None:
+        """
+        Initialize the error with the missing theme and the known themes.
+
+        :param theme: The theme name that could not be found.
+        :param available: The list of theme names that are available.
+        """
+        self.theme = theme
+        self.available = available
+        choices = ', '.join(available) if available else '(none found)'
+        super().__init__(f'Unknown theme {theme!r}. Available themes: {choices}.')
+
+
+@dataclass(frozen=True)
+class Entry:
+    """
+    A single directory entry for the index listing.
+    """
+
+    name: str
+    href: str
+    is_dir: bool
+    size: int | None
+    size_human: str
+    mtime: float
+    mtime_human: str
+    icon: str
+
+
+@lru_cache(maxsize=1)
+def _environment() -> Environment:
+    """
+    Build and cache the Jinja2 environment used to render themes.
+
+    The environment loads templates from this package's template directory and
+    enables HTML autoescaping. The result is cached so it is built only once.
+
+    :return: The shared Jinja2 environment instance.
+    """
+    return Environment(
+        loader=PackageLoader(_TEMPLATE_PACKAGE, _TEMPLATE_DIR),
+        autoescape=select_autoescape(['html', 'xml', 'jinja2']),
+        trim_blocks=True,
+        lstrip_blocks=True,
+    )
+
+
+def available_themes() -> list[str]:
+    """
+    Return the sorted list of bundled theme names.
+
+    Scans the package template directory for subdirectories, skipping any whose
+    name starts with an underscore (reserved for shared/partial templates).
+
+    :return: The sorted list of available theme names.
+    """
+    root = resources.files(_TEMPLATE_PACKAGE).joinpath(_TEMPLATE_DIR)
+    themes = []
+    for item in root.iterdir():
+        name = item.name
+        if item.is_dir() and not name.startswith('_'):
+            themes.append(name)
+    return sorted(themes)
+
+
+def validate_theme(theme: str) -> None:
+    """
+    Validate that *theme* is one of the bundled themes.
+
+    :param theme: The theme name to validate.
+    :raises ThemeNotFoundError: If *theme* is not an available theme.
+    """
+    themes = available_themes()
+    if theme not in themes:
+        raise ThemeNotFoundError(theme, themes)
+
+
+def human_size(num_bytes: int) -> str:
+    """
+    Format a byte count as a short human-readable string.
+
+    Scales the value through binary (1024) units up to petabytes, using an
+    integer for bytes and one decimal place for larger units.
+
+    :param num_bytes: The size in bytes to format.
+    :return: The formatted size string, e.g. ``"1.5 MB"`` or ``"12 B"``.
+    """
+    size = float(num_bytes)
+    for unit in ('B', 'KB', 'MB', 'GB', 'TB', 'PB'):
+        if size < 1024.0 or unit == 'PB':
+            if unit == 'B':
+                return '{} {}'.format(int(size), unit)
+            return f'{size:.1f} {unit}'
+        size /= 1024.0
+    return f'{size:.1f} PB'  # pragma: no cover
+
+
+def _icon_for(name: str, is_dir: bool) -> str:
+    """
+    Return a coarse icon class/name based on the entry type/extension.
+
+    Directories map to ``"dir"``; files are classified by extension into a
+    small set of categories, falling back to ``"file"`` when unrecognized.
+
+    :param name: The entry file or directory name.
+    :param is_dir: Whether the entry is a directory.
+    :return: The icon identifier for the entry.
+    """
+    if is_dir:
+        return 'dir'
+    ext = Path(name).suffix.lower().lstrip('.')
+    mapping = {
+        'image': {'png', 'jpg', 'jpeg', 'gif', 'svg', 'webp', 'ico', 'bmp'},
+        'video': {'mp4', 'webm', 'mov', 'avi', 'mkv'},
+        'audio': {'mp3', 'wav', 'ogg', 'flac', 'm4a'},
+        'code': {
+            'py',
+            'js',
+            'ts',
+            'jsx',
+            'tsx',
+            'c',
+            'h',
+            'cpp',
+            'go',
+            'rs',
+            'java',
+            'rb',
+            'sh',
+            'css',
+            'html',
+            'json',
+            'yaml',
+            'yml',
+            'toml',
+            'xml',
+        },
+        'archive': {'zip', 'tar', 'gz', 'bz2', 'xz', '7z', 'rar'},
+        'doc': {'pdf', 'md', 'rst', 'txt', 'doc', 'docx', 'odt'},
+    }
+    for icon, extensions in mapping.items():
+        if ext in extensions:
+            return icon
+    return 'file'
+
+
+def _breadcrumbs(rel_path: str) -> list[dict[str, str]]:
+    """
+    Build breadcrumb segments (name + href) for *rel_path*.
+
+    The result always starts with the root segment and appends one entry per
+    path component, each with a cumulative, trailing-slashed href.
+
+    :param rel_path: The POSIX-style path relative to the served root.
+    :return: The ordered list of breadcrumb dicts with ``name`` and ``href``.
+    """
+    crumbs: list[dict[str, str]] = [{'name': '/', 'href': '/'}]
+    accumulated = PurePosixPath('/')
+    for part in PurePosixPath(rel_path).parts:
+        if part in ('', '/'):
+            continue
+        accumulated = accumulated / part
+        href = str(accumulated)
+        if not href.endswith('/'):
+            href += '/'
+        crumbs.append({'name': part, 'href': href})
+    return crumbs
+
+
+def list_directory(fs_dir: Path, url_path: str) -> list[Entry]:
+    """
+    Build the sorted list of :class:`Entry` for *fs_dir*.
+
+    Each child of *fs_dir* is stat-ed to produce an entry; children that cannot
+    be accessed are skipped. Entries are sorted with directories first and then
+    alphabetically (case-insensitive).
+
+    :param fs_dir: The filesystem directory to list.
+    :param url_path: The request URL path used as the base for entry hrefs.
+    :return: The sorted list of directory entries.
+    """
+    base = url_path if url_path.endswith('/') else url_path + '/'
+    entries: list[Entry] = []
+    with os.scandir(fs_dir) as iterator:
+        for item in iterator:
+            try:
+                is_dir = item.is_dir()
+                stat = item.stat()
+            except OSError:
+                continue
+            size = None if is_dir else stat.st_size
+            name = item.name
+            href = base + name + ('/' if is_dir else '')
+            entries.append(
+                Entry(
+                    name=name,
+                    href=href,
+                    is_dir=is_dir,
+                    size=size,
+                    size_human='' if size is None else human_size(size),
+                    mtime=stat.st_mtime,
+                    mtime_human=datetime.fromtimestamp(stat.st_mtime).strftime(
+                        '%Y-%m-%d %H:%M'
+                    ),
+                    icon=_icon_for(name, is_dir),
+                )
+            )
+    entries.sort(key=lambda e: (not e.is_dir, e.name.lower()))
+    return entries
+
+
+def render_index(
+    *,
+    fs_dir: Path,
+    url_path: str,
+    served_root: Path,
+    theme: str,
+    live_reload: bool,
+) -> str:
+    """
+    Render the directory index HTML for *fs_dir*.
+
+    Lists the directory, builds the template context (breadcrumbs, counts and
+    metadata) and renders it with the selected theme's index template.
+
+    :param fs_dir: The filesystem directory being served.
+    :param url_path: The request URL path for this directory.
+    :param served_root: The root directory the server exposes.
+    :param theme: The theme whose template is used for rendering.
+    :param live_reload: Whether live-reload support should be enabled.
+    :return: The rendered HTML document as a string.
+    """
+    from . import __version__
+
+    rel = url_path.strip('/')
+    entries = list_directory(fs_dir, url_path)
+    template = _environment().get_template(f'{theme}/{_INDEX_TEMPLATE}')
+    return template.render(
+        entries=entries,
+        version=__version__,
+        breadcrumbs=_breadcrumbs(rel),
+        url_path=url_path,
+        rel_path=rel,
+        served_root=str(served_root),
+        is_root=url_path in ('', '/'),
+        theme=theme,
+        live_reload=live_reload,
+        n_dirs=sum(1 for e in entries if e.is_dir),
+        n_files=sum(1 for e in entries if not e.is_dir),
+    )

webdev/livereload.py

@@ -0,0 +1,169 @@
+# Copyright (C) 2026 KuraLabs S.R.L <info@kuralabs.io>
+# Copyright (C) 2015-2016 Carlos Jenkins <carlos@jenkins.co.cr>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""
+Live reload: watch the served tree and tell connected browsers to refresh.
+
+Pieces:
+
+* :class:`ReloadHub` — an in-process registry of connected WebSocket clients
+  with a broadcast method.
+* :func:`watch_tree` — a background task (started from the app lifespan) that
+  runs :func:`watchfiles.awatch` over the served root and broadcasts a reload
+  on every debounced change batch. Handles the ``--future`` case by watching the
+  nearest existing ancestor until the root appears.
+* :data:`LIVERELOAD_PATH` / :data:`CLIENT_SNIPLET` — the reserved WebSocket
+  endpoint path and the auto-reconnecting client snippet injected into HTML.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+from watchfiles import awatch
+
+#: Reserved, collision-resistant path for the live-reload WebSocket endpoint.
+LIVERELOAD_PATH = '/__webdev__/livereload'
+
+
+class ReloadHub:
+    """
+    Tracks connected live-reload clients and broadcasts reload events.
+
+    Each connected WebSocket client is represented by an :class:`asyncio.Queue`
+    onto which reload messages are pushed.
+    """
+
+    def __init__(self) -> None:
+        """
+        Initialize the hub with an empty set of client queues.
+        """
+        self._clients: set[asyncio.Queue[str]] = set()
+
+    def register(self) -> asyncio.Queue[str]:
+        """
+        Register a new client and return its message queue.
+
+        :return: A fresh queue that will receive broadcast reload messages.
+        """
+        queue: asyncio.Queue[str] = asyncio.Queue()
+        self._clients.add(queue)
+        return queue
+
+    def unregister(self, queue: asyncio.Queue[str]) -> None:
+        """
+        Remove a client's queue from the hub.
+
+        :param queue: The queue previously returned by :meth:`register`.
+        """
+        self._clients.discard(queue)
+
+    def broadcast(self, message: str = 'reload') -> None:
+        """
+        Push a message to every registered client queue.
+
+        :param message: The message to deliver to each client.
+        """
+        for queue in list(self._clients):
+            queue.put_nowait(message)
+
+    @property
+    def client_count(self) -> int:
+        """
+        Return the number of currently registered clients.
+
+        :return: The count of connected live-reload clients.
+        """
+        return len(self._clients)
+
+
+def _nearest_existing(path: Path) -> Path:
+    """
+    Return *path* if it exists, else the closest existing ancestor.
+
+    :param path: The starting path to resolve.
+    :return: The first existing path among *path* and its parents, or the
+        filesystem anchor if none exist.
+    """
+    current = path
+    for candidate in (current, *current.parents):
+        if candidate.exists():
+            return candidate
+    return Path(current.anchor or '.')
+
+
+async def watch_tree(
+    root: Path,
+    hub: ReloadHub,
+    stop_event: asyncio.Event,
+) -> None:
+    """
+    Watch *root* and broadcast a reload on every change batch.
+
+    If *root* does not exist yet (``--future``), watch the nearest existing
+    ancestor so that the directory's eventual creation is observed; the watcher
+    is then restarted targeting *root* once it appears. Runs until *stop_event*
+    is set.
+
+    :param root: The directory tree to watch for changes.
+    :param hub: The hub whose clients are notified on each change batch.
+    :param stop_event: Event signalling the watcher to stop.
+    """
+    while not stop_event.is_set():
+        target = root if root.exists() else _nearest_existing(root)
+        try:
+            async for _changes in awatch(
+                target,
+                stop_event=stop_event,
+            ):
+                hub.broadcast()
+                # If we were watching an ancestor and the root now exists,
+                # break to restart the watcher on the real root.
+                if target != root and root.exists():
+                    break
+        except FileNotFoundError:
+            # The watched path vanished; wait briefly and re-resolve.
+            await asyncio.sleep(0.5)
+        if stop_event.is_set():
+            break
+        # Small debounce before (potentially) re-targeting the watcher.
+        await asyncio.sleep(0.1)
+
+
+#: Auto-reconnecting client snippet injected before </body> of HTML responses.
+CLIENT_SNIPLET = """
+<script>
+(function () {
+  var path = "__LIVERELOAD_PATH__";
+  var proto = location.protocol === "https:" ? "wss" : "ws";
+  var wasConnected = false;
+  function connect() {
+    var ws = new WebSocket(proto + "://" + location.host + path);
+    ws.onopen = function () {
+      if (wasConnected) { location.reload(); return; }
+      wasConnected = true;
+    };
+    ws.onmessage = function (event) {
+      if (event.data === "reload") { location.reload(); }
+    };
+    ws.onclose = function () { setTimeout(connect, 1000); };
+    ws.onerror = function () { try { ws.close(); } catch (e) {} };
+  }
+  connect();
+})();
+</script>
+""".replace('__LIVERELOAD_PATH__', LIVERELOAD_PATH)

webdev/net.py

@@ -0,0 +1,145 @@
+# Copyright (C) 2026 KuraLabs S.R.L <info@kuralabs.io>
+# Copyright (C) 2015-2016 Carlos Jenkins <carlos@jenkins.co.cr>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""
+Networking helpers: incremental port selection, LAN address detection and QR.
+"""
+
+from __future__ import annotations
+
+import socket
+from errno import EADDRINUSE
+
+
+class NoFreePortError(Exception):
+    """
+    Raised when no free port is found in the requested range.
+    """
+
+    def __init__(self, start: int, end: int) -> None:
+        """
+        Initialize the error with the exhausted port range.
+
+        :param start: The first port of the range that was probed.
+        :param end: The last port of the range that was probed.
+        """
+        self.start = start
+        self.end = end
+        super().__init__(f'Port(s) {start} - {end} already in use.')
+
+
+def find_free_port(ip: str, base_port: int, port_range: int) -> int:
+    """
+    Return the first bindable port in ``[base_port, base_port + port_range]``.
+
+    A port is considered free if we can bind a TCP socket to it on *ip*. The
+    probe socket is closed immediately; the caller binds the real server right
+    after. ``SO_REUSEADDR`` is set to match Uvicorn's own bind behaviour: on
+    Linux it lets us reclaim a port still lingering in ``TIME_WAIT`` from a
+    previous run (common right after Ctrl+C with keep-alive clients) while still
+    reporting a port actively held by another ``LISTEN``ing process as busy.
+
+    :param ip: The interface IP address to bind the probe socket to.
+    :param base_port: The first port to try.
+    :param port_range: How many additional ports past *base_port* to try.
+    :return: The first bindable port in the range.
+    :raises NoFreePortError: If every port in the range is already in use.
+    :raises OSError: If binding fails for a reason other than the address
+        being in use.
+    """
+    last = base_port + port_range
+    for port in range(base_port, last + 1):
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
+            probe.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            try:
+                probe.bind((ip, port))
+            except OSError as error:
+                if error.errno != EADDRINUSE:
+                    raise
+                continue
+            return port
+    raise NoFreePortError(base_port, last)
+
+
+def detect_lan_ip() -> str | None:
+    """
+    Best-effort detection of the primary LAN IPv4 address.
+
+    Uses a connected UDP socket to a public address to learn which local
+    interface the OS would route through. No packets are actually sent. Returns
+    ``None`` if detection fails or only loopback is available.
+
+    :return: The primary LAN IPv4 address, or ``None`` if it cannot be
+        determined.
+    """
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
+            sock.connect(('8.8.8.8', 80))
+            ip = sock.getsockname()[0]
+    except OSError:
+        return None
+    if not ip or ip.startswith('127.'):
+        return None
+    return ip
+
+
+def build_urls(bind_ip: str, port: int, https: bool) -> list[str]:
+    """
+    Return human-friendly URLs to reach the server.
+
+    When bound to a wildcard address, includes the loopback URL and, if
+    detectable, the LAN URL; otherwise returns a single URL for *bind_ip*.
+
+    :param bind_ip: The IP address the server is bound to.
+    :param port: The port the server is listening on.
+    :param https: Whether to use the ``https`` scheme instead of ``http``.
+    :return: The list of reachable URLs for the server.
+    """
+    scheme = 'https' if https else 'http'
+    urls: list[str] = []
+    if bind_ip in ('0.0.0.0', '::'):
+        urls.append(f'{scheme}://127.0.0.1:{port}')
+        lan = detect_lan_ip()
+        if lan:
+            urls.append(f'{scheme}://{lan}:{port}')
+    else:
+        urls.append(f'{scheme}://{bind_ip}:{port}')
+    return urls
+
+
+def render_qr(url: str) -> str | None:
+    """
+    Render *url* as an ASCII QR code suitable for a terminal.
+
+    Returns ``None`` if the optional ``qrcode`` dependency is unavailable.
+
+    :param url: The URL to encode as a QR code.
+    :return: The ASCII QR code as a string, or ``None`` if ``qrcode`` is not
+        installed.
+    """
+    try:
+        import io
+
+        import qrcode
+    except ModuleNotFoundError:  # pragma: no cover
+        return None
+
+    qr = qrcode.QRCode(border=1)
+    qr.add_data(url)
+    qr.make(fit=True)
+    buffer = io.StringIO()
+    qr.print_ascii(out=buffer, invert=True)
+    return buffer.getvalue()