panel-live-server 0.1.0__py3-none-any.whl

panel_live_server/__init__.py

@@ -0,0 +1,14 @@
+"""Panel Live Server - Execute and visualize Python code snippets."""
+
+import importlib.metadata
+import warnings
+
+try:
+    __version__ = importlib.metadata.version("panel-live-server")
+except importlib.metadata.PackageNotFoundError as e:  # pragma: no cover
+    warnings.warn(f"Could not determine version of panel-live-server\n{e!s}", stacklevel=2)
+    __version__ = "unknown"
+
+__all__: list[str] = [
+    "__version__",
+]

panel_live_server/app.py

@@ -0,0 +1,125 @@
+"""Panel server for code visualization.
+
+This module implements a Panel web server that executes Python code
+and displays the results through various endpoints.
+"""
+
+import logging
+from urllib.parse import urlparse
+
+from panel_live_server.config import get_config
+from panel_live_server.endpoints import EmbedEndpoint
+from panel_live_server.endpoints import HealthEndpoint
+from panel_live_server.endpoints import ScreenshotEndpoint
+from panel_live_server.endpoints import SnippetEndpoint
+
+logger = logging.getLogger(__name__)
+
+
+def _display_url(address: str, port: int, endpoint: str) -> str:
+    """Generate the display server URL, externalizing when config.external_url is set."""
+    external_url = get_config().external_url
+    if external_url:
+        return f"{external_url.rstrip('/')}/{endpoint}"
+    return f"http://{address}:{port}/{endpoint}"
+
+
+def _api_url(address: str, port: int, endpoint: str) -> str:
+    """Generate the API URL for a given endpoint."""
+    return f"http://{address}:{port}{endpoint}"
+
+
+def _build_websocket_origins(address: str, port: int) -> list[str]:
+    """Build a targeted websocket origin allowlist for Bokeh/Panel.
+
+    Bokeh expects origins as host[:port] values. We include local defaults,
+    the configured bind address, and (when configured) the externally reachable
+    host from ``external_url``.
+    """
+    origins: set[str] = {
+        f"localhost:{port}",
+        f"127.0.0.1:{port}",
+    }
+
+    # Add the configured bind address when it is a concrete host.
+    if address and address not in {"0.0.0.0", "::"}:
+        origins.add(f"{address}:{port}")
+
+    external_url = get_config().external_url
+    if external_url:
+        parsed = urlparse(external_url)
+        if parsed.hostname:
+            if parsed.port:
+                origins.add(f"{parsed.hostname}:{parsed.port}")
+            else:
+                origins.add(parsed.hostname)
+                if parsed.scheme == "https":
+                    origins.add(f"{parsed.hostname}:443")
+                elif parsed.scheme == "http":
+                    origins.add(f"{parsed.hostname}:80")
+
+    return sorted(origins)
+
+
+def main(address: str = "localhost", port: int = 5077, show: bool = True) -> None:
+    """Start the Panel server."""
+    import panel as pn
+
+    from panel_live_server.database import get_db
+    from panel_live_server.pages import add_page
+    from panel_live_server.pages import admin_page
+    from panel_live_server.pages import feed_page
+    from panel_live_server.pages import view_page
+
+    # Initialize the database
+    _ = get_db()
+
+    # Configure Panel defaults
+    pn.template.FastListTemplate.param.main_layout.default = None
+    pn.pane.Markdown.param.disable_anchors.default = True
+
+    # Initialize views cache for feed page
+    pn.state.cache["views"] = {}
+
+    # Configure pages
+    pages = {
+        "/view": view_page,
+        "/feed": feed_page,
+        "/admin": admin_page,
+        "/add": add_page,
+    }
+
+    # Configure extra patterns for Tornado handlers (REST API endpoints)
+    extra_patterns = [
+        (r"/api/snippet", SnippetEndpoint),
+        (r"/api/embed", EmbedEndpoint),
+        (r"/api/screenshot", ScreenshotEndpoint),
+        (r"/api/health", HealthEndpoint),
+    ]
+
+    # Log startup information
+    logger.info(f"Starting Panel Live Server at http://{address}:{port}")
+    logger.info(f"  Feed:   {_display_url(address, port, 'feed')}")
+    logger.info(f"  Add:    {_display_url(address, port, 'add')}")
+    logger.info(f"  Admin:  {_display_url(address, port, 'admin')}")
+    logger.info(f"  Health: {_api_url(address, port, '/api/health')}")
+
+    # Start server
+    pn.serve(
+        pages,
+        port=port,
+        address=address,
+        show=show,
+        title="Panel Live Server",
+        extra_patterns=extra_patterns,
+        websocket_origin=_build_websocket_origins(address=address, port=port),
+    )
+
+
+if __name__ == "__main__":
+    # Read config from env vars when run as subprocess
+    from panel_live_server.config import reset_config
+
+    reset_config()
+    config = get_config()
+    main(address=config.host, port=config.port, show=False)

panel_live_server/cli.py

@@ -0,0 +1,280 @@
+"""CLI for Panel Live Server."""
+
+import logging
+import os
+import sys
+from typing import Annotated
+
+# On Windows, conda/pixi environments require Library/bin and DLLs on PATH so
+# that native extensions (numpy, panel, etc.) can find their DLLs at import
+# time. MCP clients that launch pls directly (not via `pixi run`) don't
+# activate the environment, so we fix it up here before any heavy imports.
+if sys.platform == "win32":
+    from panel_live_server.utils import prepend_env_dll_paths
+
+    prepend_env_dll_paths(os.environ)
+
+import typer
+
+from panel_live_server import __version__
+
+logger = logging.getLogger(__name__)
+
+
+def version_callback(value: bool) -> None:
+    """Print version and exit."""
+    if value:
+        typer.echo(f"panel-live-server {__version__}")
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    name="pls",
+    help="Panel Live Server - Execute and visualize Python code snippets.",
+    add_completion=False,
+)
+
+list_app = typer.Typer(help="List resources (packages, etc.).")
+app.add_typer(list_app, name="list")
+
+
+@app.callback(invoke_without_command=True)
+def main_callback(
+    ctx: typer.Context,
+    version: Annotated[
+        bool,
+        typer.Option("--version", "-V", callback=version_callback, is_eager=True, help="Show version and exit."),
+    ] = False,
+) -> None:
+    """Panel Live Server - Execute and visualize Python code snippets."""
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+
+
+@app.command()
+def serve(
+    port: int = typer.Option(
+        5077,
+        "--port",
+        "-p",
+        help="Port number to run the Panel server on.",
+        envvar="PANEL_LIVE_SERVER_PORT",
+        show_default=True,
+    ),
+    host: str = typer.Option(
+        "localhost",
+        "--host",
+        "-H",
+        help="Host address to bind to.",
+        envvar="PANEL_LIVE_SERVER_HOST",
+        show_default=True,
+    ),
+    db_path: str | None = typer.Option(
+        None,
+        "--db-path",
+        help="Path to the SQLite database file.",
+        envvar="PANEL_LIVE_SERVER_DB_PATH",
+    ),
+    show: bool = typer.Option(
+        False,
+        "--show",
+        help="Open the server in a browser after starting.",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Enable verbose logging.",
+    ),
+) -> None:
+    """Start the Panel Live Server directly.
+
+    The server provides a web interface for executing Python code snippets
+    and visualizing the results. Visit http://<host>:<port>/feed to see
+    visualizations as they are created.
+
+    Note: if you are also running `pls mcp`, both commands use the same Panel
+    server port (PANEL_LIVE_SERVER_PORT). Run only one at a time unless you
+    configure different ports.
+    """
+    import os
+
+    if verbose:
+        logging.basicConfig(level=logging.DEBUG)
+    else:
+        logging.basicConfig(level=logging.INFO)
+
+    # Set env vars before config is loaded so get_config() picks them up
+    os.environ["PANEL_LIVE_SERVER_PORT"] = str(port)
+    os.environ["PANEL_LIVE_SERVER_HOST"] = host
+    if db_path:
+        os.environ["PANEL_LIVE_SERVER_DB_PATH"] = db_path
+
+    # Reset the cached config singleton so it re-reads the env vars we just set
+    from panel_live_server.config import reset_config
+
+    reset_config()
+
+    from panel_live_server.app import main as app_main
+
+    try:
+        app_main(address=host, port=port, show=show)
+    except OSError as exc:
+        import errno
+
+        import requests
+
+        if exc.errno != errno.EADDRINUSE:
+            raise
+        url = f"http://{host}:{port}/api/health"
+        try:
+            resp = requests.get(url, timeout=2)
+            if resp.status_code == 200:
+                typer.echo(f"Panel Live Server is already running at http://{host}:{port}")
+                typer.echo("  Run `pls status` for details.")
+                raise typer.Exit(0)
+        except requests.ConnectionError:
+            pass
+        typer.echo(f"Error: port {port} is already in use by another process.", err=True)
+        typer.echo(f"  Try: pls serve --port {port + 1}", err=True)
+        raise typer.Exit(1) from None
+
+
+@app.command()
+def mcp(
+    transport: str = typer.Option(
+        "stdio",
+        "--transport",
+        "-t",
+        help="MCP transport: stdio, http, or sse.",
+        envvar="PANEL_LIVE_SERVER_TRANSPORT",
+    ),
+    host: str = typer.Option(
+        "127.0.0.1",
+        "--host",
+        help="Host for HTTP/SSE transport.",
+        envvar="PANEL_LIVE_SERVER_MCP_HOST",
+    ),
+    port: int = typer.Option(
+        8001,
+        "--port",
+        "-p",
+        help="Port for HTTP/SSE transport.",
+        envvar="PANEL_LIVE_SERVER_MCP_PORT",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Enable verbose logging.",
+    ),
+) -> None:
+    """Start as an MCP server for AI assistants.
+
+    The MCP server exposes the `show` tool for executing and displaying
+    Python visualizations. A Panel visualization server starts automatically
+    on port 5077 (PANEL_LIVE_SERVER_PORT) — visit that address in a browser
+    to watch visualizations appear in real time.
+
+    Note: the --port flag here controls the MCP HTTP/SSE listener, NOT the
+    Panel visualization server port. For stdio transport, --port is unused.
+    """
+    if verbose:
+        logging.basicConfig(level=logging.DEBUG)
+    else:
+        logging.basicConfig(level=logging.INFO)
+
+    from panel_live_server.server import mcp as mcp_server
+
+    if transport == "stdio":
+        mcp_server.run(transport="stdio")
+    elif transport == "http":
+        mcp_server.run(transport="streamable-http", host=host, port=port)
+    elif transport == "sse":
+        mcp_server.run(transport="sse", host=host, port=port)
+    else:
+        typer.echo(f"Unknown transport: {transport!r}. Choose from: stdio, http, sse.")
+        raise typer.Exit(1)
+
+
+@app.command()
+def status(
+    port: int = typer.Option(
+        5077,
+        "--port",
+        "-p",
+        help="Port to check.",
+        envvar="PANEL_LIVE_SERVER_PORT",
+        show_default=True,
+    ),
+    host: str = typer.Option(
+        "localhost",
+        "--host",
+        "-H",
+        help="Host to check.",
+        envvar="PANEL_LIVE_SERVER_HOST",
+        show_default=True,
+    ),
+) -> None:
+    """Check whether the Panel server is running.
+
+    Queries the health endpoint and reports the server status.
+    """
+    import requests
+
+    url = f"http://{host}:{port}/api/health"
+    try:
+        resp = requests.get(url, timeout=3)
+        if resp.status_code == 200:
+            data = resp.json()
+            typer.echo(f"Running  http://{host}:{port}/feed  (healthy at {data.get('timestamp', '?')})")
+        else:
+            typer.echo(f"Unhealthy  http://{host}:{port}  (status {resp.status_code})")
+            raise typer.Exit(1)
+    except requests.ConnectionError:
+        typer.echo(f"Not running  (nothing on {host}:{port})")
+        raise typer.Exit(1) from None
+    except requests.Timeout:
+        typer.echo(f"Timeout  (no response from {host}:{port} within 3 s)")
+        raise typer.Exit(1) from None
+
+
+@list_app.command(name="packages")
+def list_packages(
+    filter: str = typer.Argument(
+        "",
+        help="Optional substring to filter package names (case-insensitive).",
+        show_default=False,
+    ),
+) -> None:
+    """List all Python packages installed in the current environment.
+
+    Optionally filter by a substring, e.g. ``pls list packages panel`` to show
+    only packages whose name contains "panel".
+    """
+    from importlib.metadata import distributions
+
+    pkgs = sorted(
+        ((dist.metadata["Name"], dist.metadata["Version"]) for dist in distributions()),
+        key=lambda t: t[0].lower().replace("-", "_"),
+    )
+
+    if filter:
+        pkgs = [(name, ver) for name, ver in pkgs if filter.lower() in name.lower()]
+
+    if not pkgs:
+        typer.echo("No packages found.")
+        return
+
+    name_width = max(len(name) for name, _ in pkgs)
+    for name, version in pkgs:
+        typer.echo(f"{name:<{name_width}}  {version}")
+
+
+def main() -> None:
+    """Entry point for the pls command."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

panel_live_server/client.py

@@ -0,0 +1,177 @@
+"""HTTP client for Display Server REST API.
+
+This module provides a client for interacting with the Panel Display Server
+via its REST API. The client can be used with either a locally-managed subprocess
+or a remote server instance.
+"""
+
+import logging
+
+import requests  # type: ignore[import-untyped]
+
+logger = logging.getLogger(__name__)
+
+
+class DisplayClient:
+    """HTTP client for Display Server REST API.
+
+    This client handles all HTTP communication with the Panel Display Server,
+    including health checks and snippet creation. It uses a persistent session
+    for connection pooling.
+    """
+
+    def __init__(self, base_url: str, timeout: int = 30):
+        """Initialize the Display Client.
+
+        Parameters
+        ----------
+        base_url : str
+            Base URL of the Display Server (e.g., "http://localhost:5077")
+        timeout : int
+            Request timeout in seconds
+        """
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.session = requests.Session()
+
+    def is_healthy(self) -> bool:
+        """Check if Display Server is healthy.
+
+        Returns
+        -------
+        bool
+            True if server responds to health check, False otherwise
+        """
+        try:
+            response = self.session.get(f"{self.base_url}/api/health", timeout=2)
+            return response.status_code == 200
+        except requests.RequestException:
+            return False
+
+    def create_snippet(self, code: str, name: str = "", description: str = "", method: str = "inline", validated: bool = False) -> dict:
+        """Create a visualization snippet on the Display Server.
+
+        Sends Python code to the server for execution and rendering.
+
+        Parameters
+        ----------
+        code : str
+            Python code to execute
+        name : str, optional
+            Name for the visualization
+        description : str, optional
+            Description of the visualization
+        method : str, optional
+            Execution method ("inline" or "server")
+        validated : bool, optional
+            When True, signals that the code was already validated and executed
+            by the MCP ``show`` tool, so the server can skip its redundant
+            storage-time validation and execution.
+
+        Returns
+        -------
+        dict
+            Server response containing either:
+            - Success: {"url": str, "id": str, ...}
+            - Error: {"error": str, "message": str, "traceback": str}
+
+        Raises
+        ------
+        RuntimeError
+            If HTTP request fails
+        """
+        try:
+            response = self.session.post(
+                f"{self.base_url}/api/snippet",
+                json={
+                    "code": code,
+                    "name": name,
+                    "description": description,
+                    "method": method,
+                    "validated": validated,
+                },
+                timeout=self.timeout,
+            )
+
+            response.raise_for_status()
+            return response.json()
+
+        except requests.RequestException as e:
+            logger.exception(f"Error creating visualization: {e}")
+            raise RuntimeError(f"Failed to create visualization: {e}") from e
+
+    def get_embed_html(self, snippet_id: str) -> str | None:
+        """Fetch self-contained static HTML for an inline-method snippet.
+
+        Returns ``None`` on failure so the caller can degrade gracefully.
+        """
+        try:
+            response = self.session.get(
+                f"{self.base_url}/api/embed",
+                params={"id": snippet_id},
+                timeout=self.timeout,
+            )
+            if response.status_code != 200:
+                logger.warning("Embed render failed (HTTP %s) for snippet %s", response.status_code, snippet_id)
+                return None
+            if "text/html" not in response.headers.get("Content-Type", ""):
+                logger.warning("Embed render returned non-HTML content-type for snippet %s", snippet_id)
+                return None
+            return response.text
+        except requests.RequestException as e:
+            logger.warning("Embed render request error for snippet %s: %s", snippet_id, e)
+            return None
+
+    def get_screenshot(
+        self,
+        snippet_id: str,
+        width: int | None = None,
+        height: int | None = None,
+        full_page: bool = False,
+    ) -> tuple[bytes | None, str | None]:
+        """Fetch a PNG screenshot of a snippet's rendered ``/view`` page.
+
+        Returns
+        -------
+        tuple[bytes | None, str | None]
+            ``(png_bytes, None)`` on success, or ``(None, error_message)`` on failure.
+        """
+        params: dict[str, str | int] = {"id": snippet_id, "full_page": str(full_page).lower()}
+        if width:
+            params["width"] = width
+        if height:
+            params["height"] = height
+
+        try:
+            response = self.session.get(
+                f"{self.base_url}/api/screenshot",
+                params=params,
+                timeout=max(self.timeout, 60),
+            )
+        except requests.RequestException as e:
+            logger.warning("Screenshot request error for snippet %s: %s", snippet_id, e)
+            return None, f"Screenshot request failed: {e}"
+
+        if response.status_code == 200 and "image/png" in response.headers.get("Content-Type", ""):
+            return response.content, None
+
+        try:
+            body = response.json()
+            message = body.get("message") or body.get("error") or response.text
+        except ValueError:
+            message = response.text or f"HTTP {response.status_code}"
+        logger.warning("Screenshot failed (HTTP %s) for snippet %s: %s", response.status_code, snippet_id, message)
+        return None, message
+
+    def close(self) -> None:
+        """Close the HTTP session and cleanup resources."""
+        if self.session:
+            self.session.close()
+
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self.close()

panel_live_server/config.py

@@ -0,0 +1,94 @@
+"""Configuration for Panel Live Server."""
+
+import logging
+import os
+from pathlib import Path
+
+from pydantic import BaseModel
+from pydantic import Field
+
+logger = logging.getLogger("panel_live_server")
+
+
+def _default_user_dir() -> Path:
+    return Path(os.getenv("PANEL_LIVE_SERVER_USER_DIR", "~/.panel-live-server")).expanduser()
+
+
+def _resolve_external_url(port: int) -> str:
+    """Resolve the external URL for the Panel server.
+
+    Checks in priority order:
+    1. ``PANEL_LIVE_SERVER_EXTERNAL_URL``                          — explicit override (port-inclusive).
+    2. ``JUPYTERHUB_HOST`` + ``JUPYTERHUB_SERVICE_PREFIX``         — JupyterHub with jupyter-server-proxy.
+       Note: ``JUPYTERHUB_SERVICE_PREFIX`` is set automatically by JupyterHub, but ``JUPYTERHUB_HOST`` is
+       only set automatically in subdomain routing mode and must be supplied manually in path-based routing.
+    3. ``CODESPACE_NAME``                                          — GitHub Codespaces port-forwarding URL.
+    4. ``""``                                                      — local; callers fall back to ``http://localhost:{port}``.
+    """
+    if explicit := os.getenv("PANEL_LIVE_SERVER_EXTERNAL_URL", ""):
+        return explicit.rstrip("/")
+
+    hub_host = os.getenv("JUPYTERHUB_HOST", "")
+    hub_prefix = os.getenv("JUPYTERHUB_SERVICE_PREFIX", "")
+    if hub_host and hub_prefix:
+        if not hub_host.startswith(("http://", "https://")):
+            hub_host = f"https://{hub_host}"
+        return f"{hub_host.rstrip('/')}{hub_prefix}proxy/{port}"
+
+    if codespace := os.getenv("CODESPACE_NAME", ""):
+        domain = os.getenv("GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN") or "app.github.dev"
+        return f"https://{codespace}-{port}.{domain}"
+
+    return ""
+
+
+class Config(BaseModel):
+    """Panel Live Server configuration."""
+
+    port: int = Field(default=5077, description="Port for the Panel server")
+    host: str = Field(default="localhost", description="Host address for the Panel server")
+    max_restarts: int = Field(default=3, description="Maximum number of restart attempts")
+    db_path: Path = Field(
+        default_factory=lambda: _default_user_dir() / "snippets" / "snippets.db",
+        description="Path to SQLite database for snippets",
+    )
+    external_url: str = Field(
+        default="",
+        description=(
+            "Externally reachable base URL for the Panel server (port-inclusive). "
+            "Auto-detected from JUPYTERHUB_HOST + JUPYTERHUB_SERVICE_PREFIX (JupyterHub) "
+            "or CODESPACE_NAME (GitHub Codespaces) if not set explicitly via PANEL_LIVE_SERVER_EXTERNAL_URL."
+        ),
+    )
+    screenshot_width: int = Field(default=1200, description="Viewport width (px) for screenshot capture")
+    screenshot_height: int = Field(default=800, description="Viewport height (px) for screenshot capture")
+    screenshot_settle_ms: int = Field(default=1200, description="Delay (ms) after content mounts before capturing, to let Bokeh finish drawing")
+    screenshot_timeout_ms: int = Field(default=30000, description="Max time (ms) to wait for the page to load before capturing")
+
+
+_config: Config | None = None
+
+
+def get_config() -> Config:
+    """Get or create the config instance."""
+    global _config
+    if _config is None:
+        port = int(os.getenv("PANEL_LIVE_SERVER_PORT", "5077"))
+        _config = Config(
+            port=port,
+            host=os.getenv("PANEL_LIVE_SERVER_HOST", "localhost"),
+            max_restarts=int(os.getenv("PANEL_LIVE_SERVER_MAX_RESTARTS", "3")),
+            db_path=Path(os.getenv("PANEL_LIVE_SERVER_DB_PATH", str(_default_user_dir() / "snippets" / "snippets.db"))),
+            external_url=_resolve_external_url(port),
+            screenshot_width=int(os.getenv("PANEL_LIVE_SERVER_SCREENSHOT_WIDTH", "1200")),
+            screenshot_height=int(os.getenv("PANEL_LIVE_SERVER_SCREENSHOT_HEIGHT", "800")),
+            screenshot_settle_ms=int(os.getenv("PANEL_LIVE_SERVER_SCREENSHOT_SETTLE_MS", "1200")),
+            screenshot_timeout_ms=int(os.getenv("PANEL_LIVE_SERVER_SCREENSHOT_TIMEOUT_MS", "30000")),
+        )
+    return _config
+
+
+def reset_config() -> None:
+    """Reset config (for testing)."""
+    global _config
+    _config = None