pythonlings 0.3.0__py3-none-any.whl

pythonlings/__main__.py

@@ -0,0 +1,4 @@
+from pythonlings.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pythonlings/app.py

@@ -0,0 +1,84 @@
+# pythonlings/app.py
+from __future__ import annotations
+
+from pathlib import Path
+
+from textual.app import App
+
+from pythonlings.core.manifest import Manifest, load as load_manifest
+from pythonlings.core.state import State, load as load_state, next_pending
+from pythonlings.screens.topic_picker import TopicPickerScreen
+from pythonlings.screens.track import TrackScreen
+
+
+class PythonlingsApp(App[int]):
+    CSS_PATH = "pythonlings.tcss"
+
+    def __init__(
+        self,
+        root: Path,
+        start_topic: str | None = None,
+        force_picker: bool = False,
+    ) -> None:
+        super().__init__()
+        self.root = root
+        self.manifest: Manifest = load_manifest(root)
+        self.state: State = load_state(root)
+        self._start_topic = start_topic
+        self._force_picker = force_picker
+
+    def on_mount(self) -> None:
+        self.push_screen(TopicPickerScreen())
+        target = self._startup_target()
+        if target is not None:
+            topic, exercise = target
+            self.push_screen(TrackScreen(topic, start_exercise=exercise))
+
+    def _startup_target(self) -> tuple[str, str | None] | None:
+        if self._start_topic is not None:
+            if self._start_topic in self.manifest.topics():
+                return self._start_topic, None
+            return None
+        if self._force_picker:
+            return None
+        return self._resume_target() or self._first_pending_target()
+
+    def _resume_target(self) -> tuple[str, str | None] | None:
+        topic = self.state.last_topic
+        if topic not in self.manifest.topics():
+            return None
+
+        exercises = self.manifest.exercises_in(topic)
+        names = {ex.name for ex in exercises}
+        last = self.state.last_exercise
+        if last in names and last not in self.state.completed:
+            return topic, last
+
+        next_name = next_pending(exercises, self.state.completed)
+        if next_name is not None:
+            return topic, next_name
+        return None
+
+    def _first_pending_target(self) -> tuple[str, str | None] | None:
+        for topic in self.manifest.topics():
+            next_name = next_pending(
+                self.manifest.exercises_in(topic), self.state.completed
+            )
+            if next_name is not None:
+                return topic, next_name
+        return None
+
+
+def run_tui(
+    root: Path,
+    start_topic: str | None = None,
+    force_picker: bool = False,
+) -> int:
+    return (
+        PythonlingsApp(
+            root,
+            start_topic,
+            force_picker=force_picker,
+        ).run()
+        or 0
+    )

pythonlings/cli.py

@@ -0,0 +1,318 @@
+# pythonlings/cli.py
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+__version__ = "0.3.0"
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="pythonlings")
+    parser.add_argument("--version", action="version", version=f"pythonlings {__version__}")
+    parser.add_argument(
+        "--debug", action="store_true", help="Write debug output to .pythonlings_debug.log."
+    )
+    parser.add_argument(
+        "--root",
+        type=Path,
+        default=Path.cwd(),
+        help="Project root containing info.toml (default: cwd).",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    p_init = sub.add_parser("init", help="Create a pythonlings workspace.")
+    p_init.add_argument("--path", type=Path, default=Path.cwd())
+    p_init.add_argument(
+        "--force", action="store_true", help="Overwrite managed workspace files."
+    )
+
+    p_update = sub.add_parser("update", help="Update an existing pythonlings workspace.")
+    p_update.add_argument("--path", type=Path, default=Path.cwd())
+
+    sub.add_parser("watch", help="Launch the TUI in watch mode (default).")
+    sub.add_parser("topics", help="Launch the TUI on the topic picker.")
+
+    p_run = sub.add_parser("run", help="Run a single exercise.")
+    p_run.add_argument("name")
+
+    p_dry_run = sub.add_parser("dry-run", help="Run one exercise non-interactively.")
+    p_dry_run.add_argument("name")
+
+    p_solution = sub.add_parser(
+        "solution", aliases=["sol"], help="Run a reference solution."
+    )
+    p_solution.add_argument("name")
+
+    p_hint = sub.add_parser("hint", help="Print the hint for an exercise.")
+    p_hint.add_argument("name")
+
+    p_list = sub.add_parser("list", help="List topics, or one topic's exercises.")
+    p_list.add_argument("topic", nargs="?", help="Show exercises of this topic.")
+
+    p_start = sub.add_parser("start", help="Launch the TUI on a topic's track.")
+    p_start.add_argument("topic")
+
+    p_reset = sub.add_parser("reset", help="Restore an exercise from its snapshot.")
+    p_reset.add_argument("name")
+    p_reset.add_argument("--yes", action="store_true", help="Skip the confirmation prompt.")
+
+    p_verify = sub.add_parser(
+        "verify", help="Run every exercise, or just one topic's."
+    )
+    p_verify.add_argument("topic", nargs="?", help="Verify only this topic.")
+
+    return parser
+
+
+def _resolve_topic(manifest, topic: str):
+    """Return the topic name if valid, else write an error and return None."""
+    if topic in manifest.topics():
+        return topic
+    sys.stderr.write(
+        f"pythonlings: no topic named {topic!r}. "
+        f"Topics: {', '.join(manifest.topics())}\n"
+    )
+    return None
+
+
+def _cmd_init(path: Path, force: bool) -> int:
+    from pythonlings.core.curriculum import WorkspaceError, init_workspace
+
+    try:
+        root = init_workspace(path, force=force)
+    except WorkspaceError as e:
+        sys.stderr.write(f"pythonlings: {e}\n")
+        return 1
+    print(f"initialized: {root}")
+    return 0
+
+
+def _cmd_update(path: Path) -> int:
+    from pythonlings.core.curriculum import WorkspaceError, update_workspace
+
+    try:
+        root = update_workspace(path)
+    except WorkspaceError as e:
+        sys.stderr.write(f"pythonlings: {e}\n")
+        return 1
+    print(f"updated: {root}")
+    return 0
+
+
+def _cmd_verify(root: Path, topic: str | None) -> int:
+    from pythonlings.core.manifest import load as load_manifest
+    from pythonlings.core.runner import run_verify
+
+    manifest = load_manifest(root)
+    if topic is not None:
+        if _resolve_topic(manifest, topic) is None:
+            return 2
+        exercises = manifest.exercises_in(topic)
+    else:
+        exercises = manifest.exercises
+    for ex in exercises:
+        result = run_verify(ex)
+        status = "✓" if result.passed else "✗"
+        print(f"{status} {ex.name}")
+        if not result.passed:
+            sys.stderr.write(result.stderr or result.stdout)
+            return 1
+    return 0
+
+
+def _cmd_list(root: Path, topic: str | None) -> int:
+    from pythonlings.core.manifest import load as load_manifest
+    from pythonlings.core.state import load as load_state, next_pending
+
+    manifest = load_manifest(root)
+    state = load_state(root)
+
+    if topic is None:
+        for name in manifest.topics():
+            exs = manifest.exercises_in(name)
+            done = sum(1 for ex in exs if ex.name in state.completed)
+            mark = "✓" if done == len(exs) else ("●" if done else " ")
+            print(f"  {mark}  {name}  {done}/{len(exs)}")
+        return 0
+
+    if _resolve_topic(manifest, topic) is None:
+        return 2
+    exs = manifest.exercises_in(topic)
+    current = next_pending(exs, state.completed)
+    for ex in exs:
+        if ex.name in state.completed:
+            marker = "✓"
+        elif ex.name == current:
+            marker = "●"
+        else:
+            marker = "🔒"
+        print(f"  {marker}  {ex.name}")
+    return 0
+
+
+def _cmd_hint(root: Path, name: str) -> int:
+    from pythonlings.core.manifest import load as load_manifest
+
+    manifest = load_manifest(root)
+    try:
+        ex = manifest.by_name(name)
+    except KeyError:
+        sys.stderr.write(f"pythonlings: no exercise named {name!r}\n")
+        return 1
+    print(ex.hint.strip() or "(no hint provided)")
+    if ex.docs:
+        print(f"Docs: {ex.docs}")
+    return 0
+
+
+def _cmd_run(root: Path, name: str) -> int:
+    from pythonlings.core.manifest import load as load_manifest
+    from pythonlings.core.runner import run as run_exercise
+
+    manifest = load_manifest(root)
+    try:
+        ex = manifest.by_name(name)
+    except KeyError:
+        sys.stderr.write(f"pythonlings: no exercise named {name!r}\n")
+        return 1
+
+    result = run_exercise(ex)
+    if result.stdout:
+        sys.stdout.write(result.stdout)
+    if result.stderr:
+        sys.stderr.write(result.stderr)
+    if result.timed_out:
+        sys.stderr.write(f"pythonlings: {name} timed out after {result.duration_s:.1f}s\n")
+        return 1
+    if result.exit_code != 0:
+        return 1
+    if ex.is_pending():
+        sys.stderr.write(
+            f"pythonlings: tests pass but the '# I AM NOT DONE' marker is still in {name}.\n"
+        )
+        return 1
+    return 0
+
+
+def _cmd_solution(root: Path, name: str) -> int:
+    from pythonlings.core.manifest import load as load_manifest
+    from pythonlings.core.runner import run_verify
+    from pythonlings.core.solutions import SolutionError, solution_exercise
+
+    manifest = load_manifest(root)
+    try:
+        ex = solution_exercise(root, manifest.by_name(name))
+    except KeyError:
+        sys.stderr.write(f"pythonlings: no exercise named {name!r}\n")
+        return 1
+    except SolutionError as e:
+        sys.stderr.write(f"pythonlings: {e}\n")
+        return 1
+
+    result = run_verify(ex)
+    if result.stdout:
+        sys.stdout.write(result.stdout)
+    if result.stderr:
+        sys.stderr.write(result.stderr)
+    return 0 if result.passed else 1
+
+
+def _cmd_reset(root: Path, name: str, yes: bool) -> int:
+    from pythonlings.core.manifest import load as load_manifest
+    from pythonlings.core.reset import ResetError, restore
+    from pythonlings.core.state import load as load_state, save as save_state
+
+    manifest = load_manifest(root)
+    try:
+        ex = manifest.by_name(name)
+    except KeyError:
+        sys.stderr.write(f"pythonlings: no exercise named {name!r}\n")
+        return 1
+
+    if not yes:
+        sys.stdout.write(f"Reset {name}? (y/N) ")
+        sys.stdout.flush()
+        if sys.stdin.readline().strip().lower() != "y":
+            return 0
+
+    try:
+        restore(root, ex)
+    except ResetError as e:
+        sys.stderr.write(f"pythonlings: {e}\n")
+        return 1
+
+    state = load_state(root)
+    state.completed.discard(name)
+    save_state(root, state)
+    print(f"reset: {name}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv if argv is not None else sys.argv[1:])
+
+    # Migrate any legacy .pylings/ state dir. init/update target --path; the
+    # in-workspace commands target --root. Both are no-ops without a legacy dir.
+    from pythonlings.core.curriculum import migrate_legacy_state_dir
+
+    for attr in ("path", "root"):
+        workspace = getattr(args, attr, None)
+        if workspace is not None:
+            migrate_legacy_state_dir(Path(workspace))
+
+    try:
+        if getattr(args, "debug", False):
+            try:
+                (args.root / ".pythonlings_debug.log").write_text(
+                    f"argv={argv if argv is not None else sys.argv[1:]!r}\n",
+                    encoding="utf-8",
+                )
+            except OSError:
+                pass
+
+        if args.command == "init":
+            return _cmd_init(args.path, args.force)
+        if args.command == "update":
+            return _cmd_update(args.path)
+
+        if args.command == "verify":
+            return _cmd_verify(args.root, args.topic)
+        if args.command == "list":
+            return _cmd_list(args.root, args.topic)
+        if args.command == "hint":
+            return _cmd_hint(args.root, args.name)
+        if args.command == "run":
+            return _cmd_run(args.root, args.name)
+        if args.command == "dry-run":
+            return _cmd_run(args.root, args.name)
+        if args.command in {"solution", "sol"}:
+            return _cmd_solution(args.root, args.name)
+        if args.command == "reset":
+            return _cmd_reset(args.root, args.name, args.yes)
+
+        if args.command in (None, "watch", "start", "topics"):
+            start_topic = getattr(args, "topic", None)
+            if start_topic is not None:
+                from pythonlings.core.manifest import load as load_manifest
+                if _resolve_topic(load_manifest(args.root), start_topic) is None:
+                    return 2
+            from pythonlings.app import run_tui  # lazy: Textual is heavy
+            return run_tui(
+                args.root,
+                start_topic,
+                force_picker=args.command == "topics",
+            )
+
+        # Other subcommands wired in later tasks.
+        sys.stderr.write(f"pythonlings: '{args.command}' not implemented yet\n")
+        return 1
+    except Exception as e:
+        # Manifest errors and other startup failures use exit code 2.
+        from pythonlings.core.manifest import ManifestError
+        if isinstance(e, ManifestError):
+            sys.stderr.write(f"pythonlings: {e}\n")
+            return 2
+        raise

pythonlings/core/curriculum.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import shutil
+from importlib import resources
+from pathlib import Path
+
+
+class WorkspaceError(RuntimeError):
+    """Workspace init or update failed."""
+
+
+CURRICULUM_DIRS = ("exercises", "checks", "solutions")
+GITIGNORE_LINES = [
+    ".pythonlings/state.json",
+    ".pythonlings_debug.log",
+    "__pycache__/",
+    "*.pyc",
+]
+
+
+def migrate_legacy_state_dir(root: Path) -> None:
+    """Rename a pre-rename `.pylings/` state dir to `.pythonlings/`.
+
+    Workspaces created before the project was renamed from pylings to
+    pythonlings keep their progress and reset snapshots this way.
+    """
+    legacy = root / ".pylings"
+    current = root / ".pythonlings"
+    if legacy.is_dir() and not current.exists():
+        legacy.rename(current)
+
+
+def source_root() -> Path:
+    """Return the curriculum source root for editable and wheel installs."""
+    packaged = resources.files("pythonlings").joinpath("curriculum")
+    if packaged.joinpath("info.toml").is_file():
+        return Path(str(packaged))
+
+    repo_root = Path(__file__).resolve().parents[2]
+    if (repo_root / "info.toml").exists():
+        return repo_root
+
+    raise WorkspaceError("packaged curriculum not found")
+
+
+def _copy_path(src: Path, dst: Path, *, overwrite: bool) -> None:
+    if src.is_dir():
+        if dst.exists() and overwrite:
+            shutil.rmtree(dst)
+        dst.mkdir(parents=True, exist_ok=True)
+        for child in src.iterdir():
+            _copy_path(child, dst / child.name, overwrite=overwrite)
+        return
+
+    if dst.exists() and not overwrite:
+        return
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(src, dst)
+
+
+def _write_workspace_gitignore(root: Path) -> None:
+    (root / ".gitignore").write_text(
+        "\n".join(GITIGNORE_LINES) + "\n",
+        encoding="utf-8",
+    )
+
+
+def _sync_originals(root: Path, src_root: Path) -> None:
+    originals = root / ".pythonlings" / "originals"
+    if originals.exists():
+        shutil.rmtree(originals)
+    for exercise in (src_root / "exercises").rglob("*.py"):
+        rel = exercise.relative_to(src_root / "exercises")
+        target = originals / rel
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(exercise, target)
+
+
+def init_workspace(path: Path, *, force: bool = False) -> Path:
+    path = path.expanduser().resolve()
+    if path.exists() and any(path.iterdir()) and not force:
+        raise WorkspaceError(f"{path} already exists and is not empty")
+    path.mkdir(parents=True, exist_ok=True)
+
+    src_root = source_root()
+    _copy_path(src_root / "info.toml", path / "info.toml", overwrite=True)
+    for dirname in CURRICULUM_DIRS:
+        _copy_path(src_root / dirname, path / dirname, overwrite=True)
+    _sync_originals(path, src_root)
+    _write_workspace_gitignore(path)
+    return path
+
+
+def update_workspace(path: Path) -> Path:
+    path = path.expanduser().resolve()
+    if not (path / "info.toml").exists():
+        raise WorkspaceError(f"{path} is not a pythonlings workspace")
+
+    src_root = source_root()
+    _copy_path(src_root / "info.toml", path / "info.toml", overwrite=True)
+    _copy_path(src_root / "checks", path / "checks", overwrite=True)
+    _copy_path(src_root / "solutions", path / "solutions", overwrite=True)
+    _copy_path(src_root / "exercises", path / "exercises", overwrite=False)
+    _sync_originals(path, src_root)
+    _write_workspace_gitignore(path)
+    return path

pythonlings/core/docs.py

@@ -0,0 +1,68 @@
+# pythonlings/core/docs.py
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from importlib import resources
+from typing import Any
+from urllib.parse import urldefrag
+
+
+@dataclass(frozen=True)
+class DocSnippet:
+    topic: str
+    title: str
+    source_url: str
+    text: str
+
+
+def load_snippet(topic: str, source_url: str = "") -> DocSnippet | None:
+    """Load a bundled snippet by topic, falling back to an official docs URL."""
+    index = _load_index()
+    if index is None:
+        return None
+
+    entry = index["topics"].get(topic)
+    if entry is not None:
+        return _load_entry(topic, entry)
+
+    normalized_source = _normalize_url(source_url)
+    if not normalized_source:
+        return None
+
+    for candidate_topic, candidate_entry in index["topics"].items():
+        candidate_source = candidate_entry["source_url"]
+        if (
+            candidate_source == source_url
+            or _normalize_url(candidate_source) == normalized_source
+        ):
+            return _load_entry(candidate_topic, candidate_entry)
+
+    return None
+
+
+def _load_index() -> dict[str, Any] | None:
+    try:
+        docs_root = resources.files("pythonlings.docs")
+        return json.loads((docs_root / "index.json").read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError, ModuleNotFoundError):
+        return None
+
+
+def _load_entry(topic: str, entry: dict[str, Any]) -> DocSnippet | None:
+    try:
+        docs_root = resources.files("pythonlings.docs")
+        text = (docs_root / entry["file"]).read_text(encoding="utf-8").strip()
+    except (FileNotFoundError, KeyError, ModuleNotFoundError):
+        return None
+
+    return DocSnippet(
+        topic=topic,
+        title=entry["title"],
+        source_url=entry["source_url"],
+        text=text,
+    )
+
+
+def _normalize_url(url: str) -> str:
+    return urldefrag(url.strip()).url

pythonlings/core/exercise.py

@@ -0,0 +1,33 @@
+# pythonlings/core/exercise.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Exercise:
+    name: str
+    path: Path
+    check_path: Path
+    topic: str
+    hint: str
+    docs: str = ""
+    root: Path | None = None
+    rel_path: Path | None = None
+    check_rel_path: Path | None = None
+
+    DONE_MARKER = "# I AM NOT DONE"
+
+    def is_pending(self) -> bool:
+        return self.DONE_MARKER in self.path.read_text(encoding="utf-8")
+
+
+@dataclass
+class RunResult:
+    passed: bool
+    exit_code: int
+    stdout: str
+    stderr: str
+    duration_s: float
+    timed_out: bool