panel-live-server 0.1.0a2__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,89 @@
+"""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
+import os
+
+from panel_live_server.endpoints import HealthEndpoint
+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."""
+    proxy_url = os.getenv("JUPYTER_SERVER_PROXY_URL", None)
+    if proxy_url:
+        proxy_url = proxy_url.rstrip("/")
+        return f"{proxy_url}/{port}/{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 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/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,
+    )
+
+
+if __name__ == "__main__":
+    # Read config from env vars when run as subprocess
+    from panel_live_server.config import get_config
+    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,269 @@
+"""CLI for Panel Live Server."""
+
+import logging
+from typing import Annotated
+
+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,109 @@
+"""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 = "jupyter") -> 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 ("jupyter" or "panel")
+
+        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,
+                },
+                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 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,50 @@
+"""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()
+
+
+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",
+    )
+    jupyter_server_proxy_url: str = Field(default="", description="Jupyter server proxy URL")
+
+
+_config: Config | None = None
+
+
+def get_config() -> Config:
+    """Get or create the config instance."""
+    global _config
+    if _config is None:
+        _config = Config(
+            port=int(os.getenv("PANEL_LIVE_SERVER_PORT", "5077")),
+            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"))),
+            jupyter_server_proxy_url=os.getenv("JUPYTER_SERVER_PROXY_URL", ""),
+        )
+    return _config
+
+
+def reset_config() -> None:
+    """Reset config (for testing)."""
+    global _config
+    _config = None