trailhead-edu 0.2.0__tar.gz

trailhead_edu-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Kris Jordan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

trailhead_edu-0.2.0/MANIFEST.in

@@ -0,0 +1 @@
+prune tests

trailhead_edu-0.2.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: trailhead-edu
+Version: 0.2.0
+Summary: A local web environment for learning and exploring Python programs
+Author-email: Kris Jordan <kris@cs.unc.edu>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/KrisJordan/trailhead
+Project-URL: Issues, https://github.com/KrisJordan/trailhead/issues
+Project-URL: Repository, https://github.com/KrisJordan/trailhead.git
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cachetools<7,>=5.3
+Requires-Dist: fastapi<1,>=0.108
+Requires-Dist: pydantic<3,>=2.5
+Requires-Dist: uvicorn<1,>=0.25
+Requires-Dist: watchdog<7,>=3
+Requires-Dist: websockets<17,>=12
+Provides-Extra: student
+Requires-Dist: ipykernel>=6.28; extra == "student"
+Requires-Dist: matplotlib>=3.8; extra == "student"
+Requires-Dist: numpy>=1.26; extra == "student"
+Requires-Dist: pandas>=2.1; extra == "student"
+Requires-Dist: pillow>=10.1; extra == "student"
+Requires-Dist: seaborn>=0.13; extra == "student"
+Requires-Dist: six>=1.16; extra == "student"
+Requires-Dist: svgwrite>=1.4; extra == "student"
+Dynamic: license-file
+
+# Trailhead server
+
+Trailhead is a local FastAPI server for exploring and running Python modules in
+a browser. It supports Python 3.11 or newer on macOS, Windows, and Linux. The
+PyPI distribution is named `trailhead-edu`; the import package and command remain
+`trailhead`.
+
+Install the command from PyPI in an isolated tool environment with:
+
+```console
+uv tool install trailhead-edu
+```
+
+For repository development, synchronize the locked environment from the
+repository root:
+
+```console
+uv sync --project server --locked --extra student
+```
+
+The `student` extra supplies the optional data-science and teaching libraries;
+the base installation contains only Trailhead's server runtime. Run a project
+with:
+
+```console
+trailhead --root demo
+```
+
+Use `trailhead --help` for host, port, reload, and log-level options. The web
+client must be built before creating a release wheel so that `static/index.html`
+and `static/assets/` are included as package data.

trailhead_edu-0.2.0/README.md

@@ -0,0 +1,31 @@
+# Trailhead server
+
+Trailhead is a local FastAPI server for exploring and running Python modules in
+a browser. It supports Python 3.11 or newer on macOS, Windows, and Linux. The
+PyPI distribution is named `trailhead-edu`; the import package and command remain
+`trailhead`.
+
+Install the command from PyPI in an isolated tool environment with:
+
+```console
+uv tool install trailhead-edu
+```
+
+For repository development, synchronize the locked environment from the
+repository root:
+
+```console
+uv sync --project server --locked --extra student
+```
+
+The `student` extra supplies the optional data-science and teaching libraries;
+the base installation contains only Trailhead's server runtime. Run a project
+with:
+
+```console
+trailhead --root demo
+```
+
+Use `trailhead --help` for host, port, reload, and log-level options. The web
+client must be built before creating a release wheel so that `static/index.html`
+and `static/assets/` are included as package data.

trailhead_edu-0.2.0/pyproject.toml

@@ -0,0 +1,100 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "trailhead-edu"
+version = "0.2.0"
+description = "A local web environment for learning and exploring Python programs"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Kris Jordan", email = "kris@cs.unc.edu" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Web Environment",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "cachetools>=5.3,<7",
+    "fastapi>=0.108,<1",
+    "pydantic>=2.5,<3",
+    "uvicorn>=0.25,<1",
+    "watchdog>=3,<7",
+    "websockets>=12,<17",
+]
+
+[project.optional-dependencies]
+student = [
+    "ipykernel>=6.28",
+    "matplotlib>=3.8",
+    "numpy>=1.26",
+    "pandas>=2.1",
+    "pillow>=10.1",
+    "seaborn>=0.13",
+    "six>=1.16",
+    "svgwrite>=1.4",
+]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.7",
+    "pytest>=7.4",
+    "pytest-asyncio>=0.23",
+    "pytest-json-report>=1.5",
+    "ruff>=0.9",
+    "types-cachetools>=5.3",
+]
+
+[project.scripts]
+trailhead = "trailhead.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/KrisJordan/trailhead"
+Issues = "https://github.com/KrisJordan/trailhead/issues"
+Repository = "https://github.com/KrisJordan/trailhead.git"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["trailhead*"]
+
+[tool.setuptools.package-data]
+trailhead = [
+    "static/*",
+    "static/**/*",
+]
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.mypy]
+python_version = "3.11"
+files = ["src/trailhead", "tests"]
+check_untyped_defs = true
+no_implicit_optional = true
+show_error_codes = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+
+[tool.ruff]
+target-version = "py311"
+line-length = 88
+
+[tool.ruff.format]
+indent-style = "space"
+quote-style = "double"

trailhead_edu-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

trailhead_edu-0.2.0/src/trailhead/__init__.py

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

trailhead_edu-0.2.0/src/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_edu-0.2.0/src/trailhead/analysis/__init__.py

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

trailhead_edu-0.2.0/src/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()