trailhead-edu 0.2.0__py3-none-any.whl

trailhead/__init__.py

@@ -0,0 +1,3 @@
+"""Trailhead's Python teaching server."""
+
+__version__ = "0.2.0"

trailhead/__main__.py

@@ -0,0 +1,117 @@
+"""Command-line entry point for the Trailhead server."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import sys
+from typing import Sequence
+
+import uvicorn
+
+from . import __version__
+from .project import set_project_root
+from .websocket_origin import (
+    ALLOWED_ORIGINS_ENV,
+    add_allowed_websocket_origins,
+)
+
+PACKAGE_DIR = Path(__file__).resolve().parent
+
+
+def _port(value: str) -> int:
+    port = int(value)
+    if not 1 <= port <= 65535:
+        raise argparse.ArgumentTypeError("port must be between 1 and 65535")
+    return port
+
+
+def _url_host(host: str) -> str:
+    """Format a bind host for display in an HTTP URL."""
+
+    if ":" in host and not host.startswith("["):
+        return f"[{host}]"
+    return host
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build Trailhead's command-line argument parser."""
+
+    parser = argparse.ArgumentParser(description="Run the Trailhead server")
+    parser.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="interface to bind (default: 127.0.0.1)",
+    )
+    parser.add_argument(
+        "--port",
+        "-p",
+        type=_port,
+        default=1110,
+        help="TCP port to bind (default: 1110)",
+    )
+    parser.add_argument(
+        "--root",
+        type=Path,
+        default=Path.cwd(),
+        help="project containing the Python modules to serve (default: current directory)",
+    )
+    parser.add_argument(
+        "--reload",
+        action="store_true",
+        help="restart when Trailhead server source files change",
+    )
+    parser.add_argument(
+        "--log-level",
+        choices=("critical", "error", "warning", "info", "debug", "trace"),
+        default="info",
+        help="Uvicorn log level (default: info)",
+    )
+    parser.add_argument(
+        "--allow-origin",
+        action="append",
+        default=[],
+        metavar="ORIGIN",
+        help=(
+            "allow an exact browser WebSocket origin (repeatable; additional "
+            f"origins may be set with {ALLOWED_ORIGINS_ENV})"
+        ),
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run Trailhead using an installable, host-independent configuration."""
+
+    args = build_parser().parse_args(argv)
+    try:
+        project_root = set_project_root(args.root)
+        add_allowed_websocket_origins(args.allow_origin)
+    except (OSError, ValueError) as error:
+        print(f"trailhead: {error}", file=sys.stderr)
+        return 2
+
+    print(f"Serving project {project_root}")
+    print(f"Starting Trailhead server at http://{_url_host(args.host)}:{args.port}")
+    print("Press Ctrl+C to stop the Trailhead server")
+
+    options: dict[str, object] = {
+        "host": args.host,
+        "port": args.port,
+        "log_level": args.log_level,
+    }
+    if args.reload:
+        options.update(
+            reload=True,
+            reload_dirs=[str(PACKAGE_DIR)],
+        )
+
+    # An import string works both normally and in Uvicorn's spawned reload
+    # worker. Any startup/import failure remains visible to the caller.
+    uvicorn.run("trailhead.app:app", **options)  # type: ignore[arg-type]
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

trailhead/analysis/__init__.py

@@ -0,0 +1 @@
+"""Static analysis helpers for Python source modules."""

trailhead/analysis/inspect.py

@@ -0,0 +1,206 @@
+"""Tools for analyzing Python code."""
+
+from _ast import AsyncFor
+import argparse
+import ast
+import tokenize
+from typing import Any, Dict
+from pydantic import BaseModel
+
+
+class Parameter(BaseModel):
+    name: str
+    type: str
+
+
+class Function(BaseModel):
+    name: str
+    doc: str
+    parameters: list[Parameter]
+    return_type: str
+    source: str
+
+
+class Module(BaseModel):
+    name: str
+    doc: str
+    top_level_functions: list[Function]
+    top_level_calls: list[str]
+    global_vars: Dict[str, Any]
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Analyze Python Code")
+    parser.add_argument("filepath", help="The Python file to analyze")
+    args = parser.parse_args()
+    file = args.filepath
+    with tokenize.open(file) as source:
+        tree = ast.parse(source.read())
+    module = get_module(file, tree)
+    print(module)
+
+
+def analyze_module(file: str) -> Module:
+    with tokenize.open(file) as source:
+        try:
+            tree = ast.parse(source.read())
+            return get_module(file, tree)
+        except Exception as e:
+            return Module(
+                name=file,
+                doc=f"{type(e).__name__} encountered when parsing",
+                top_level_functions=[],
+                top_level_calls=[],
+                global_vars={},
+            )
+
+
+def get_module(path: str, tree: ast.Module) -> Module:
+    return Module(
+        name=path,
+        doc=ast.get_docstring(tree) or "",
+        top_level_functions=get_module_function_definitions(tree),
+        top_level_calls=get_top_level_function_calls(tree),
+        global_vars=extract_global_vars(tree),
+    )
+
+
+def extract_global_vars(tree: ast.Module) -> Dict[str, Any]:
+    assignment_nodes: list[ast.Assign | ast.AnnAssign] = []
+    for n in tree.body:
+        if isinstance(n, ast.Assign) and isinstance(n.targets[0], ast.Name):
+            assignment_nodes.append(n)
+        elif isinstance(n, ast.AnnAssign) and isinstance(n.target, ast.Name):
+            assignment_nodes.append(n)
+
+    variable_dict = {}
+    for node in assignment_nodes:
+        if isinstance(node, ast.AnnAssign):
+            if not isinstance(node.target, ast.Name):
+                continue
+            ref = node.target.id
+            value = node.value
+        else:
+            target = node.targets[0]
+            if not isinstance(target, ast.Name):
+                continue
+            ref = target.id
+            value = node.value
+
+        if isinstance(value, (ast.Constant, ast.List, ast.Tuple)):
+            assignment_value = ast.literal_eval(value)
+        elif isinstance(value, ast.Dict):
+            assignment_value = {}
+            for key, val in zip(value.keys, value.values):
+                if key is None:
+                    continue
+                if isinstance(val, (ast.Constant, ast.List, ast.Tuple, ast.Dict)):
+                    assignment_value[ast.literal_eval(key)] = ast.literal_eval(val)
+                else:
+                    assignment_value[ast.literal_eval(key)] = str(val)
+        else:
+            assignment_value = None
+
+        variable_dict[ref] = assignment_value
+
+    return variable_dict
+
+
+def get_module_function_definitions(tree: ast.AST) -> list[Function]:
+    class FunctionCollector(ast.NodeVisitor):
+        def __init__(self):
+            self.functions: list[Function] = []
+
+        def visit_ClassDef(self, node: ast.ClassDef):
+            # Not looking for method definitions
+            ...
+
+        def visit_FunctionDef(self, node: ast.FunctionDef):
+            ast_params = node.args.args
+            parameters = [
+                Parameter(name=param.arg, type=self._get_param_type(param.annotation))
+                for param in ast_params
+            ]
+            self.functions.append(
+                Function(
+                    name=node.name,
+                    doc=ast.get_docstring(node) or "",
+                    parameters=parameters,
+                    return_type=self._get_return_type(node.returns),
+                    source=ast.unparse(node),
+                )
+            )
+
+        def visit_AsyncFunctionDef(self, node: ast.AsyncFunctionDef):
+            return self.visit_FunctionDef(node)  # type: ignore
+
+        def _get_param_type(self, node: ast.expr | None) -> str:
+            if node is None:
+                return "Any"
+            elif isinstance(node, ast.Name):
+                return node.id
+            elif isinstance(node, ast.Constant):
+                return str(node.value)
+            else:
+                return "UnsupportedParamType"
+
+        def _get_return_type(self, node: ast.expr | None) -> str:
+            if isinstance(node, ast.Name):
+                return node.id
+            elif isinstance(node, ast.Constant):
+                return str(node.value)
+            else:
+                return "UnsupportedReturnType"
+
+    function_collector = FunctionCollector()
+    function_collector.visit(tree)
+    return function_collector.functions
+
+
+def get_top_level_function_calls(tree: ast.AST) -> list[str]:
+    class FunctionCallCollector(ast.NodeVisitor):
+        def __init__(self):
+            self.function_calls: list[str] = []
+
+        def visit_Call(self, node: ast.Call):
+            self.function_calls.append(ast.unparse(node.func))
+
+        def visit_ClassDef(self, node: ast.ClassDef) -> Any:
+            # Only looking for top-level function calls
+            ...
+
+        def visit_FunctionDef(self, node: ast.FunctionDef):
+            # Only looking for top-level function calls
+            ...
+
+        def visit_For(self, node: ast.For):
+            # Only looking for top-level function calls
+            ...
+
+        def visit_AsyncFor(self, node: AsyncFor) -> Any:
+            # Only looking for top-level function calls
+            ...
+
+        def visit_If(self, node: ast.If):
+            # Only looking for top-level function calls
+            ...
+
+        def visit_While(self, node: ast.While):
+            # Only looking for top-level function calls
+            ...
+
+        def visit_AsyncWith(self, node: ast.AsyncWith):
+            # Only looking for top-level function calls
+            ...
+
+        def visit_Match(self, node: ast.Match):
+            # Only looking for top-level function calls
+            ...
+
+    function_call_collector = FunctionCallCollector()
+    function_call_collector.visit(tree)
+    return function_call_collector.function_calls
+
+
+if __name__ == "__main__":
+    main()

trailhead/app.py

@@ -0,0 +1,163 @@
+"""Main module for the introductory programming web server."""
+
+__author__ = "Kris Jordan <kris@cs.unc.edu>"
+__copyright__ = "Copyright 2024"
+__license__ = "MIT"
+
+import asyncio
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI, WebSocket, HTTPException
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse
+from starlette.websockets import WebSocketDisconnect, WebSocketState
+
+from .web_socket_manager import WebSocketManager
+from .file_observer import FileObserver
+from .controller import web_socket_controller
+from .web_socket_event import WebSocketEvent
+from .async_python_subprocess import AsyncPythonSubprocess
+from .analysis.inspect import analyze_module, Module
+from .project import get_project_root, module_file
+from .websocket_origin import (
+    WebSocketOriginMiddleware,
+    configured_websocket_origins,
+)
+
+web_socket_manager = WebSocketManager(web_socket_controller)
+"""Web Socket Manager handles connections and dispatches to the controller."""
+
+PACKAGE_DIR = Path(__file__).resolve().parent
+STATIC_DIR = PACKAGE_DIR / "static"
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """
+    This function is called before the FastAPI web server begins, yields while
+    the web server is running, then shuts down depencies when halting. It is
+    responsible for starting and stopping the file observer and the web socket
+    manager.
+    """
+    # Validate configuration at startup rather than waiting for the first
+    # browser connection.  Invalid values fail closed in the middleware too.
+    configured_websocket_origins()
+    file_observer = FileObserver(get_project_root(), web_socket_manager.notify)
+    try:
+        yield
+    finally:
+        file_observer.stop()
+        await asyncio.to_thread(file_observer.join, 5)
+        await web_socket_manager.stop()
+
+
+app = FastAPI(lifespan=lifespan)
+"""The FastAPI web server instance."""
+app.add_middleware(WebSocketOriginMiddleware)
+
+
+@app.get("/api/module/{module}")
+async def get_module(module: str) -> Module:
+    try:
+        path = module_file(module)
+    except ValueError:
+        raise HTTPException(status_code=404, detail="Module not found") from None
+    if not path.is_file():
+        raise HTTPException(status_code=404, detail="Module not found")
+    return analyze_module(str(path))
+
+
+@app.get("/api/heartbeat")
+async def get_heartbeat():
+    return "heartbeat"
+
+
+async def _run_module_process(
+    module: str, client: WebSocket, wrapper: str = "trailhead.wrappers.module"
+) -> None:
+    """Run a module wrapper and relay its standard streams over a WebSocket."""
+
+    subprocess: AsyncPythonSubprocess | None = None
+    await client.accept()
+    try:
+        path = module_file(module)
+    except ValueError:
+        path = None
+    if path is None or not path.is_file():
+        await client.close(code=1008, reason="Module not found")
+        return
+
+    try:
+        subprocess = AsyncPythonSubprocess(module, client, wrapper)
+        pid = await subprocess.start()
+        response = WebSocketEvent(type="RUNNING", data={"pid": pid})
+        await client.send_text(response.model_dump_json())
+        while not subprocess.subprocess_exited():
+            try:
+                data = await asyncio.wait_for(client.receive_text(), timeout=0.1)
+                event = WebSocketEvent.model_validate_json(data)
+                match event.type:
+                    case "KILL":
+                        subprocess.kill()
+                    case "STDIN":
+                        await subprocess.write(event.data["data"])
+
+            except asyncio.TimeoutError:
+                # Expected while waiting for client input
+                pass
+        await subprocess.await_end()
+    except WebSocketDisconnect:
+        pass
+    finally:
+        if subprocess is not None and not subprocess.subprocess_exited():
+            subprocess.kill()
+
+        if client.client_state == WebSocketState.CONNECTED:
+            await client.close()
+
+
+@app.websocket("/ws/{module}/run")
+async def run_module(module: str, client: WebSocket):
+    """Run a Python module and relay its input and output."""
+
+    await _run_module_process(module, client)
+
+
+@app.websocket("/ws/{module}/repl")
+async def repl_module(module: str, client: WebSocket):
+    """Start an interactive REPL for a Python module."""
+
+    await _run_module_process(module, client, "trailhead.wrappers.repl")
+
+
+@app.websocket("/ws/{module}/repl_gui")
+async def repl_gui(module: str, client: WebSocket):
+    """Start the graphical REPL protocol for a Python module."""
+
+    await _run_module_process(module, client, "trailhead.wrappers.repl_gui")
+
+
+@app.websocket("/ws")
+async def websocket_endpoint(client: WebSocket):
+    """The FastAPI web socket endpoint dispatches out to Web Socket Manager."""
+    await web_socket_manager.accept(client)
+
+
+if (STATIC_DIR / "assets").is_dir():
+    app.mount(
+        "/assets",
+        StaticFiles(directory=STATIC_DIR / "assets", html=True),
+        name="assets",
+    )
+
+
+@app.get("/{full_path:path}")
+async def read_index(full_path: str):
+    index = STATIC_DIR / "index.html"
+    if not index.is_file():
+        raise HTTPException(
+            status_code=404,
+            detail="Trailhead's web client has not been built or installed.",
+        )
+    return FileResponse(index)