markserv 1.0.0__py3-none-any.whl

markserv/__init__.py

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

markserv/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

markserv/app.py

@@ -0,0 +1,4 @@
+from .site import WatchPathFilter, build_config
+from .web import create_app
+
+__all__ = ["WatchPathFilter", "build_config", "create_app"]

markserv/cli.py

@@ -0,0 +1,279 @@
+from __future__ import annotations
+
+import contextlib
+import logging
+import os
+import select
+import sys
+import threading
+import webbrowser
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Annotated, Any, Protocol
+
+import uvicorn
+from cyclopts import App, Parameter
+from cyclopts.help import PlainFormatter
+from cyclopts.token import Token
+from rich.console import Console
+from rich.logging import RichHandler
+from uvicorn import Config, Server
+
+from .app import create_app
+from .site import build_config, build_file_site
+
+
+class StoppableServer(Protocol):
+    should_exit: bool
+
+    def run(self) -> None: ...
+
+
+console = Console(stderr=True)
+QUIT_KEYS = {"q", "Q", "\x1b"}
+DEFAULT_HOST = "localhost"
+DEFAULT_PORT = 4422
+PYTHON_RELOAD_ENV_VAR = "MARKSERV_PYTHON_RELOAD"
+TARGET_ENV_VAR = "MARKSERV_TARGET"
+PYTHON_RELOAD_DIR = Path(__file__).resolve().parent
+
+app = App(
+    name="markserv",
+    help="Render a folder of GitHub-flavored markdown with live reload.",
+    help_formatter=PlainFormatter(),
+    result_action="return_value",
+)
+
+
+def _validate_target(_type_: Any, tokens: tuple[Token, ...]) -> Path:
+    raw_path = Path(tokens[0].value)
+    build_config(raw_path)
+    return raw_path
+
+
+def configure_logging() -> None:
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(message)s",
+        handlers=[
+            RichHandler(
+                show_time=False,
+                show_level=False,
+                show_path=False,
+                markup=False,
+                rich_tracebacks=True,
+                console=console,
+            )
+        ],
+        force=True,
+    )
+
+
+def browser_url(host: str, port: int) -> str:
+    public_host = "localhost" if host in {"127.0.0.1", "0.0.0.0", "localhost"} else host
+    return f"http://{public_host}:{port}"
+
+
+def python_reload_enabled() -> bool:
+    value = os.environ.get(PYTHON_RELOAD_ENV_VAR, "")
+    return value.lower() in {"1", "true", "yes", "on"}
+
+
+@contextlib.contextmanager
+def temporary_env(updates: Mapping[str, str]) -> Any:
+    previous = {key: os.environ.get(key) for key in updates}
+    os.environ.update(updates)
+    try:
+        yield
+    finally:
+        for key, value in previous.items():
+            if value is None:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = value
+
+
+def print_startup_banner(*, source: str, root_dir: str, url: str, open_browser: bool, python_reload: bool) -> None:
+    quit_hint = (
+        "Press Ctrl+C to quit."
+        if python_reload
+        else "Press Q or Esc to quit."
+        if _supports_quit_prompt()
+        else "Press Ctrl+C to quit."
+    )
+    browser_hint = "Browser opens automatically." if open_browser else "Browser auto-open disabled."
+    reload_hint = "Python reload enabled via MARKSERV_PYTHON_RELOAD." if python_reload else None
+    display_url = url.removeprefix("http://")
+
+    console.print(f"[bold cyan]markserv[/] serving {source}")
+    console.print(f"[cyan]root[/] {root_dir}")
+    console.print(f"[cyan]url[/] [link={url}][underline]{display_url}[/underline][/link]")
+    console.print(f"[dim]{browser_hint}[/]")
+    if reload_hint is not None:
+        console.print(f"[dim]{reload_hint}[/]")
+    console.print(f"[dim]{quit_hint}[/]")
+
+
+def create_server(app: Any, *, host: str, port: int) -> Server:
+    return Server(
+        Config(
+            app,
+            host=host,
+            port=port,
+            log_level="warning",
+            access_log=False,
+            log_config=None,
+        )
+    )
+
+
+def run_python_reloading_server(app_factory_import: str, *, host: str, port: int) -> None:
+    uvicorn.run(
+        app_factory_import,
+        factory=True,
+        host=host,
+        port=port,
+        reload=True,
+        reload_dirs=[str(PYTHON_RELOAD_DIR)],
+        log_level="warning",
+        access_log=False,
+        log_config=None,
+    )
+
+
+def _supports_quit_prompt() -> bool:
+    return sys.stdin.isatty() and os.name != "nt"
+
+
+def _request_server_shutdown(server: StoppableServer, stop_event: threading.Event) -> None:
+    if stop_event.is_set():
+        return
+    console.print("[dim]Stopping server...[/dim]")
+    server.should_exit = True
+    stop_event.set()
+
+
+def _listen_for_quit_keys(server: StoppableServer, stop_event: threading.Event) -> None:
+    import termios
+    import tty
+
+    with contextlib.suppress(termios.error, ValueError, OSError):
+        fd = sys.stdin.fileno()
+        original_attrs = termios.tcgetattr(fd)
+        try:
+            tty.setcbreak(fd)
+            while not stop_event.is_set():
+                readable, _writable, _errors = select.select([sys.stdin], [], [], 0.1)
+                if not readable:
+                    continue
+                key = sys.stdin.read(1)
+                if key in QUIT_KEYS:
+                    _request_server_shutdown(server, stop_event)
+                    return
+        finally:
+            termios.tcsetattr(fd, termios.TCSADRAIN, original_attrs)
+
+
+def run_server(server: StoppableServer) -> None:
+    stop_event = threading.Event()
+    listener: threading.Thread | None = None
+
+    if _supports_quit_prompt():
+        listener = threading.Thread(
+            target=_listen_for_quit_keys,
+            args=(server, stop_event),
+            daemon=True,
+            name="markserv-quit-listener",
+        )
+        listener.start()
+
+    try:
+        server.run()
+    finally:
+        stop_event.set()
+        if listener is not None:
+            listener.join(timeout=0.2)
+
+
+def serve_application(
+    application: Any | None,
+    *,
+    source: str,
+    root_dir: str,
+    host: str,
+    port: int,
+    open_browser: bool,
+    app_factory_import: str | None = None,
+    env_updates: Mapping[str, str] | None = None,
+) -> None:
+    configure_logging()
+    url = browser_url(host, port)
+    python_reload = python_reload_enabled()
+    print_startup_banner(
+        source=source,
+        root_dir=root_dir,
+        url=url,
+        open_browser=open_browser,
+        python_reload=python_reload,
+    )
+
+    if open_browser:
+        threading.Timer(0.8, lambda: webbrowser.open(url)).start()
+
+    if python_reload:
+        if app_factory_import is None:
+            raise ValueError("app_factory_import is required when Python reload is enabled")
+        with temporary_env(dict(env_updates or {})):
+            run_python_reloading_server(app_factory_import, host=host, port=port)
+        return
+
+    if application is None:
+        raise ValueError("application is required when Python reload is disabled")
+
+    server = create_server(application, host=host, port=port)
+    run_server(server)
+
+
+@app.default
+def serve(
+    path: Annotated[
+        Path,
+        Parameter(
+            converter=_validate_target,
+            help="Markdown file or directory to serve.",
+        ),
+    ] = Path("."),
+    /,
+    *,
+    host: Annotated[str, Parameter(help="Host interface to bind.")] = DEFAULT_HOST,
+    port: Annotated[int, Parameter(help="Port to listen on.")] = DEFAULT_PORT,
+    open_browser: Annotated[
+        bool,
+        Parameter(name="--open", help="Open the app in your default browser after the server starts."),
+    ] = True,
+) -> None:
+    """Serve GitHub-flavored markdown from a file or directory."""
+    config = build_config(path)
+    site = build_file_site(config)
+    serve_application(
+        None if python_reload_enabled() else create_app(site),
+        source=str(config.source),
+        root_dir=str(config.root_dir),
+        host=host,
+        port=port,
+        open_browser=open_browser,
+        app_factory_import="markserv.cli:create_app_from_env",
+        env_updates={TARGET_ENV_VAR: str(config.source)},
+    )
+
+
+def create_app_from_env() -> Any:
+    target = os.environ.get(TARGET_ENV_VAR)
+    if not target:
+        raise RuntimeError(f"{TARGET_ENV_VAR} must be set when Python reload is enabled")
+    config = build_config(Path(target))
+    return create_app(build_file_site(config))
+
+
+def main(argv: list[str] | None = None) -> None:
+    app(tokens=argv)

markserv/demo.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+from typing import Annotated
+
+from cyclopts import App, Parameter
+from cyclopts.help import PlainFormatter
+
+from .app import create_app
+from .cli import DEFAULT_HOST, DEFAULT_PORT, python_reload_enabled, serve_application
+from .site import SyntheticSite
+
+DEMO_DOCUMENTS = {
+    "README.md": """# markserv demo
+
+Welcome to the built-in demo site.
+
+This sample tree exists so you can quickly try the renderer, sidebar navigation, live reload, and theme control.
+
+## Try these pages
+
+- [Quickstart](guides/quickstart.md)
+- [GitHub-flavored markdown examples](guides/features/gfm.md)
+- [Nested navigation](guides/nested/deep-dive.md)
+- [Reference notes](reference/notes.md)
+
+## What to try
+
+- Toggle between **system**, **light**, and **dark** themes.
+- Follow links between nested folders.
+- Resize the window to see the responsive layout.
+
+> markserv is meant to feel nice for local docs, READMEs, and note collections.
+""",
+    "guides/quickstart.md": """# Quickstart
+
+This page gives you a quick way to verify the basics.
+
+## Checklist
+
+- [x] Markdown is rendered with GitHub-style formatting
+- [x] Sidebar navigation is generated from nested folders
+- [x] Theme choice is stored in browser storage
+- [x] Synthetic demo content renders without touching the filesystem
+
+## Code block
+
+```python
+from pathlib import Path
+
+root = Path("docs")
+print(root.resolve())
+```
+
+## Table
+
+| Feature | Status |
+| --- | --- |
+| Live preview | Ready |
+| Sidebar nav | Ready |
+| Theme picker | Ready |
+
+Continue to the [feature examples](features/gfm.md).
+""",
+    "guides/features/gfm.md": """# GitHub-flavored markdown examples
+
+This page exercises a few GFM features.
+
+## Formatting
+
+You can render **bold text**, *italic text*, ~~strikethrough~~, and `inline code`.
+
+## Blockquote
+
+> Markdown previews should be quick to open and pleasant to read.
+>
+> — local docs enjoyer
+
+## Task list
+
+- [x] Tables
+- [x] Fenced code blocks
+- [x] Blockquotes
+- [x] Nested navigation
+
+## Ordered list
+
+1. Open the demo.
+2. Change the selected page.
+3. Explore the nested tree.
+
+Back to the [demo home](../../README.md).
+""",
+    "guides/nested/deep-dive.md": """# Deep dive
+
+This file lives in a nested folder so you can inspect sidebar behavior.
+
+## Notes
+
+Nested folders are shown as expandable sections in the sidebar.
+
+### Another level
+
+The current page should stay highlighted while its parent folders remain open.
+
+See the [reference notes](../../reference/notes.md) for a simple cross-link.
+""",
+    "reference/notes.md": """# Reference notes
+
+A small page for cross-link testing.
+
+## Relative links
+
+- [Back home](../README.md)
+- [Quickstart](../guides/quickstart.md)
+- [Deep dive](../guides/nested/deep-dive.md)
+
+## Inline HTML
+
+GitHub-flavored markdown rendering should also tolerate small inline HTML snippets like <kbd>Ctrl</kbd> + <kbd>C</kbd>.
+""",
+}
+
+__all__ = ["DEFAULT_HOST", "DEFAULT_PORT", "build_demo_site", "create_demo_app", "main", "serve_demo"]
+
+app = App(
+    name="markserv.demo",
+    help="Serve the built-in synthetic markdown demo.",
+    help_formatter=PlainFormatter(),
+    result_action="return_value",
+)
+
+
+def build_demo_site() -> SyntheticSite:
+    return SyntheticSite(
+        name="markserv demo",
+        root_label="built-in demo",
+        documents=DEMO_DOCUMENTS,
+        default_doc="README.md",
+    )
+
+
+def create_demo_app() -> object:
+    return create_app(build_demo_site())
+
+
+def serve_demo(*, host: str, port: int, open_browser: bool) -> None:
+    site = build_demo_site()
+    serve_application(
+        None if python_reload_enabled() else create_app(site),
+        source="markserv demo",
+        root_dir=site.root_label,
+        host=host,
+        port=port,
+        open_browser=open_browser,
+        app_factory_import="markserv.demo:create_demo_app",
+    )
+
+
+@app.default
+def serve(
+    *,
+    host: Annotated[str, Parameter(help="Host interface to bind.")] = DEFAULT_HOST,
+    port: Annotated[int, Parameter(help="Port to listen on.")] = DEFAULT_PORT,
+    open_browser: Annotated[
+        bool,
+        Parameter(name="--open", help="Open the app in your default browser after the server starts."),
+    ] = True,
+) -> None:
+    """Serve the built-in synthetic markdown demo."""
+    serve_demo(host=host, port=port, open_browser=open_browser)
+
+
+def main(argv: list[str] | None = None) -> None:
+    app(tokens=argv)
+
+
+if __name__ == "__main__":
+    main()

markserv/icons.py

@@ -0,0 +1,182 @@
+"""Generate per-page favicon PNGs using a Clifford strange attractor.
+
+Zero external dependencies -- uses only stdlib (hashlib, math, struct, zlib).
+Each page's content hash maps to a unique attractor that produces an
+organic, visually distinct icon.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import struct
+import zlib
+
+# Curated Clifford attractor parameters known to produce rich forms.
+_GOOD_PARAMS: list[tuple[float, float, float, float]] = [
+    (1.5, -1.8, 1.6, 0.9),
+    (-1.7, 1.8, -0.9, -1.4),
+    (-1.7, 1.3, -0.1, -1.21),
+    (-1.4, 1.6, 1.0, 0.7),
+    (1.7, 1.7, 0.6, 1.2),
+    (-1.9, -1.9, -1.9, -1.0),
+    (1.8, -1.5, 1.4, -0.8),
+    (-1.2, 1.9, 0.3, -1.5),
+    (1.1, -1.3, 1.7, -1.8),
+    (-1.8, -1.0, -1.6, 0.6),
+    (1.6, -0.6, -1.2, 1.6),
+    (-1.5, 1.4, 1.1, -1.3),
+    (1.3, 1.7, -0.5, -1.6),
+    (-0.8, 1.9, -1.7, 1.1),
+    (1.9, -1.1, 0.8, -1.7),
+    (-1.6, -1.4, 1.8, 0.4),
+]
+
+_COLOR_STOPS_T = (0.00, 0.05, 0.15, 0.30, 0.50, 0.65, 0.80, 0.92, 1.00)
+_COLOR_STOPS_C = (
+    (13, 17, 23),
+    (20, 30, 60),
+    (40, 70, 140),
+    (70, 130, 230),
+    (100, 110, 255),
+    (150, 100, 255),
+    (200, 150, 255),
+    (240, 220, 255),
+    (255, 245, 250),
+)
+
+
+def _params_from_hash(digest: bytes, attempt: int = 0) -> tuple[float, float, float, float]:
+    idx = (digest[0] + attempt) % len(_GOOD_PARAMS)
+    base = _GOOD_PARAMS[idx]
+    return tuple(base[i] + (digest[i + 1] / 255.0 - 0.5) * 0.16 for i in range(4))  # type: ignore[return-value]
+
+
+def _hue_shift_from_hash(digest: bytes) -> float:
+    return (digest[8] / 255.0) * 0.4 - 0.2
+
+
+def _clifford_density(
+    a: float,
+    b: float,
+    c: float,
+    d: float,
+    res: int,
+    n_points: int,
+) -> list[list[int]]:
+    sin, cos = math.sin, math.cos
+    x, y = 0.1, 0.1
+
+    # Warmup + bounds
+    xs, ys = [], []
+    for _ in range(500):
+        x, y = sin(a * y) + c * cos(a * x), sin(b * x) + d * cos(b * y)
+        xs.append(x)
+        ys.append(y)
+
+    x_min, x_max = min(xs), max(xs)
+    y_min, y_max = min(ys), max(ys)
+    span = max(x_max - x_min, y_max - y_min)
+    if span < 0.01:
+        span = 4.0
+    pad = span * 0.12
+    span += 2 * pad
+    cx, cy = (x_min + x_max) / 2, (y_min + y_max) / 2
+    x_lo, y_lo = cx - span / 2, cy - span / 2
+    scale = (res - 1) / span
+
+    grid = [[0] * res for _ in range(res)]
+    for _ in range(n_points):
+        x, y = sin(a * y) + c * cos(a * x), sin(b * x) + d * cos(b * y)
+        bx = int((x - x_lo) * scale)
+        by = int((y - y_lo) * scale)
+        if 0 <= bx < res and 0 <= by < res:
+            grid[by][bx] += 1
+
+    return grid
+
+
+def _grid_is_interesting(grid: list[list[int]], res: int) -> bool:
+    filled = sum(1 for row in grid for v in row if v > 0)
+    return filled > res * res * 0.05  # at least 5% of pixels hit
+
+
+def _colorize_rgba(grid: list[list[int]], hue_shift: float) -> list[list[tuple[int, int, int, int]]]:
+    """Colorize with alpha derived from density. Background is fully transparent."""
+    max_raw = max(max(row) for row in grid)
+    if max_raw == 0:
+        return [[(0, 0, 0, 0)] * len(grid[0]) for _ in grid]
+
+    log_max = math.log1p(max_raw)
+    stops_t = _COLOR_STOPS_T
+    stops_c = _COLOR_STOPS_C
+
+    def lerp_color(t: float) -> tuple[int, int, int]:
+        # Skip the first two dark stops -- start from visible blue
+        t = max(0.0, min(1.0, t + hue_shift * t))
+        for i in range(len(stops_t) - 1):
+            if t <= stops_t[i + 1]:
+                t0, t1 = stops_t[i], stops_t[i + 1]
+                c0, c1 = stops_c[i], stops_c[i + 1]
+                f = (t - t0) / (t1 - t0) if t1 > t0 else 0.0
+                return (
+                    min(255, max(0, int(c0[0] + (c1[0] - c0[0]) * f))),
+                    min(255, max(0, int(c0[1] + (c1[1] - c0[1]) * f))),
+                    min(255, max(0, int(c0[2] + (c1[2] - c0[2]) * f))),
+                )
+        return stops_c[-1]
+
+    result: list[list[tuple[int, int, int, int]]] = []
+    for row in grid:
+        rgba_row: list[tuple[int, int, int, int]] = []
+        for v in row:
+            if v == 0:
+                rgba_row.append((0, 0, 0, 0))
+            else:
+                t = math.log1p(v) / log_max
+                r, g, b = lerp_color(t)
+                # Alpha proportional to density -- faint wisps are translucent, hot spots are opaque
+                a = min(255, int(t * 320))
+                rgba_row.append((r, g, b, a))
+        result.append(rgba_row)
+    return result
+
+
+def _encode_png_rgba(pixels: list[list[tuple[int, int, int, int]]], width: int, height: int) -> bytes:
+    """Encode RGBA PNG using only stdlib."""
+
+    def chunk(ctype: bytes, data: bytes) -> bytes:
+        c = ctype + data
+        return struct.pack(">I", len(data)) + c + struct.pack(">I", zlib.crc32(c) & 0xFFFFFFFF)
+
+    raw = bytearray()
+    for row in pixels:
+        raw.append(0)  # filter: none
+        for r, g, b, a in row:
+            raw.extend((r, g, b, a))
+
+    return (
+        b"\x89PNG\r\n\x1a\n"
+        + chunk(b"IHDR", struct.pack(">IIBBBBB", width, height, 8, 6, 0, 0, 0))
+        + chunk(b"IDAT", zlib.compress(bytes(raw), 9))
+        + chunk(b"IEND", b"")
+    )
+
+
+def generate_favicon(content: str, res: int = 48, n_points: int = 150_000) -> bytes:
+    """Generate a unique favicon PNG from content. Pure stdlib, ~30ms at 48px."""
+    digest = hashlib.sha256(content.encode()).digest()
+    hue_shift = _hue_shift_from_hash(digest)
+
+    grid: list[list[int]] | None = None
+    for attempt in range(len(_GOOD_PARAMS)):
+        a, b, c, d = _params_from_hash(digest, attempt)
+        grid = _clifford_density(a, b, c, d, res, n_points)
+        if _grid_is_interesting(grid, res):
+            break
+
+    if grid is None:
+        grid = [[0] * res for _ in range(res)]
+
+    pixels = _colorize_rgba(grid, hue_shift)
+    return _encode_png_rgba(pixels, res, res)