pythonlings 0.3.0__py3-none-any.whl

pythonlings/screens/docs.py

@@ -0,0 +1,93 @@
+# pythonlings/screens/docs.py
+from __future__ import annotations
+
+import webbrowser
+from urllib.parse import urldefrag
+
+from rich.markup import escape
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.containers import Vertical, VerticalScroll
+from textual.screen import ModalScreen
+from textual.widgets import Markdown, Static
+
+from pythonlings.core.docs import load_snippet
+from pythonlings.core.exercise import Exercise
+
+
+class DocsScreen(ModalScreen[None]):
+    """Small in-app reference window for the current exercise."""
+
+    BINDINGS = [
+        Binding("escape", "close", "Close", priority=True),
+        Binding("o", "open_browser", "Open"),
+    ]
+
+    def __init__(self, exercise: Exercise) -> None:
+        super().__init__()
+        self.exercise = exercise
+
+    def compose(self) -> ComposeResult:
+        yield Vertical(
+            Static(f"[bold]Docs: {escape(self.exercise.name)}[/bold]", id="docs-title"),
+            VerticalScroll(
+                Markdown(self._reference_markdown(), id="docs-content", open_links=False),
+                id="docs-scroll",
+            ),
+            Static("O Open official docs | Esc Close", id="docs-footer"),
+            id="docs-window",
+        )
+
+    def action_close(self) -> None:
+        self.dismiss()
+
+    def action_open_browser(self) -> None:
+        if self.exercise.docs:
+            webbrowser.open(self.exercise.docs)
+
+    def _reference_markdown(self) -> str:
+        docs = self.exercise.docs or "(no official docs link configured)"
+        hint = self.exercise.hint.strip() or "Use this reference while solving."
+        snippet = load_snippet(self.exercise.topic, self.exercise.docs)
+        if snippet is None:
+            local_reference = "No local reference is bundled for this topic."
+            snippet_source = ""
+        else:
+            local_reference = _display_reference(snippet.text)
+            snippet_source = snippet.source_url
+
+        source_section = ""
+        if snippet_source and _page_url(snippet_source) != _page_url(docs):
+            source_section = f"\n\n## Local snippet source\n\n{snippet_source}"
+
+        return (
+            f"## Local reference\n\n{local_reference}\n\n"
+            f"## Quick note\n\n{hint}\n\n"
+            f"## Official Python docs\n\n{docs}{source_section}\n"
+        )
+
+
+def _display_reference(text: str) -> str:
+    """Remove file metadata so the modal starts with useful reference text."""
+    lines = text.strip().splitlines()
+    if lines and lines[0].startswith("# "):
+        lines = lines[1:]
+    lines = _drop_leading_blanks(lines)
+
+    if lines and lines[0].startswith("Source: "):
+        lines = lines[1:]
+    lines = _drop_leading_blanks(lines)
+
+    if lines and lines[0].startswith("This local reference is generated"):
+        lines = lines[1:]
+    return "\n".join(_drop_leading_blanks(lines)).strip()
+
+
+def _drop_leading_blanks(lines: list[str]) -> list[str]:
+    while lines and not lines[0].strip():
+        lines = lines[1:]
+    return lines
+
+
+def _page_url(url: str) -> str:
+    return urldefrag(url).url

pythonlings/screens/topic_picker.py

@@ -0,0 +1,107 @@
+# pythonlings/screens/topic_picker.py
+from __future__ import annotations
+
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.containers import VerticalScroll
+from textual.screen import Screen
+from textual.widgets import Footer, Header, ListItem, ListView, Static
+
+from pythonlings.core.state import save as save_state
+
+
+class TopicPickerScreen(Screen[None]):
+    """Entry screen: choose a topic to work on."""
+
+    BINDINGS = [
+        Binding("escape", "quit", "Quit", priority=True),
+        Binding("ctrl+q", "quit", "Quit"),
+    ]
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield Static("", id="topic-banner")
+        yield VerticalScroll(ListView(id="topics"))
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.app.title = "pythonlings"
+        self.app.sub_title = "choose a topic"
+        self._populate()
+
+    def on_screen_resume(self) -> None:
+        self._populate()
+
+    def _populate(self) -> None:
+        listview = self.query_one("#topics", ListView)
+        listview.clear()
+        self.query_one("#topic-banner", Static).update(self._banner_text())
+        manifest = self.app.manifest
+        completed = self.app.state.completed
+        selected_index = 0
+        preferred = self._preferred_topic()
+        for topic_index, topic in enumerate(manifest.topics()):
+            exs = manifest.exercises_in(topic)
+            done = sum(1 for ex in exs if ex.name in completed)
+            if done == len(exs):
+                mark = "✓"
+                status = "Done"
+            elif done:
+                mark = "●"
+                status = "Continue"
+            else:
+                mark = " "
+                status = "Start"
+            label = f"{mark}  {topic:<18} {done}/{len(exs):<5} {status}"
+            listview.append(
+                ListItem(Static(label, classes="topic-row"), name=topic)
+            )
+            if topic == preferred:
+                selected_index = topic_index
+        if listview.children:
+            listview.index = selected_index
+            listview.focus()
+
+    def _topic_progress(self, topic: str) -> tuple[int, int]:
+        exs = self.app.manifest.exercises_in(topic)
+        done = sum(1 for ex in exs if ex.name in self.app.state.completed)
+        return done, len(exs)
+
+    def _first_incomplete_topic(self) -> str | None:
+        for topic in self.app.manifest.topics():
+            done, total = self._topic_progress(topic)
+            if done < total:
+                return topic
+        return None
+
+    def _preferred_topic(self) -> str | None:
+        topic = self.app.state.last_topic
+        if topic in self.app.manifest.topics():
+            done, total = self._topic_progress(topic)
+            if done < total:
+                return topic
+        return self._first_incomplete_topic() or (
+            self.app.manifest.topics()[0] if self.app.manifest.topics() else None
+        )
+
+    def _banner_text(self) -> str:
+        first = self._first_incomplete_topic()
+        if first is None:
+            return self.app.manifest.final_message
+        if not self.app.state.seen_intro:
+            return f"Start here: {first}"
+        if self.app.state.last_topic is None:
+            return "Choose a topic to practice."
+        return "Topics"
+
+    def on_list_view_selected(self, event: ListView.Selected) -> None:
+        topic = event.item.name
+        if topic:
+            from pythonlings.screens.track import TrackScreen
+
+            self.app.state.record_resume(topic, None)
+            save_state(self.app.root, self.app.state)
+            self.app.push_screen(TrackScreen(topic))
+
+    def action_quit(self) -> None:
+        self.app.exit(0)

pythonlings/screens/track.py

@@ -0,0 +1,234 @@
+# pythonlings/screens/track.py
+from __future__ import annotations
+
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.containers import Horizontal
+from textual.screen import Screen
+from textual.timer import Timer
+from textual.widgets import Footer, Header, TextArea
+
+from pythonlings.core.exercise import Exercise, RunResult
+from pythonlings.core.runner import run as run_exercise
+from pythonlings.core.state import next_pending, save as save_state
+from pythonlings.widgets.editor_pane import EditorPane
+from pythonlings.widgets.exercise_tree import ExerciseTree
+from pythonlings.widgets.output_panel import OutputPanel
+from pythonlings.widgets.progress import ProgressBar
+
+_DEBOUNCE_SECONDS = 0.6
+
+
+class TrackScreen(Screen[None]):
+    """One topic's linear track: editor + output + auto-save loop."""
+
+    BINDINGS = [
+        Binding("f1", "toggle_hint", "Hint"),
+        Binding("f2", "reset", "Reset"),
+        Binding("f3", "toggle_list", "List"),
+        Binding("f4", "topics", "Topics"),
+        Binding("f5", "docs", "Docs"),
+        Binding("escape", "quit", "Quit", priority=True),
+        Binding("ctrl+q", "quit", "Quit"),
+    ]
+
+    def __init__(self, topic: str, start_exercise: str | None = None) -> None:
+        super().__init__()
+        self.topic = topic
+        self._start_exercise = start_exercise
+        self._save_timer: Timer | None = None
+        self._loaded_text = ""
+        self._failure_counts: dict[str, int] = {}
+        self.current: str | None = None
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield ProgressBar(id="progress")
+        yield Horizontal(
+            ExerciseTree(),
+            EditorPane(id="editor"),
+            OutputPanel(id="output"),
+            id="main",
+        )
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.app.sub_title = f"topic: {self.topic}"
+        self.current = self._initial_exercise()
+        self._render_state()
+        if self.current is None:
+            self.query_one(OutputPanel).show_final(
+                f"Topic '{self.topic}' complete."
+            )
+            return
+        self._load_current()
+        self._run_current()
+        self.query_one(EditorPane).focus_editor()
+
+    # --- helpers ---------------------------------------------------------
+
+    def _exercises(self) -> list[Exercise]:
+        return self.app.manifest.exercises_in(self.topic)
+
+    def _initial_exercise(self) -> str | None:
+        names = {ex.name for ex in self._exercises()}
+        if (
+            self._start_exercise in names
+            and self._start_exercise not in self.app.state.completed
+        ):
+            return self._start_exercise
+        return next_pending(self._exercises(), self.app.state.completed)
+
+    def _render_state(self) -> None:
+        exs = self._exercises()
+        done = sum(1 for ex in exs if ex.name in self.app.state.completed)
+        self.query_one(ProgressBar).update_progress(done, len(exs))
+        self.query_one(ExerciseTree).render_topic(
+            self.topic, exs, self.app.state.completed, self.current
+        )
+
+    def _progress_counts(self) -> tuple[int, int]:
+        exs = self._exercises()
+        done = sum(1 for ex in exs if ex.name in self.app.state.completed)
+        return done, len(exs)
+
+    def _exercise(self, name: str) -> Exercise:
+        for ex in self._exercises():
+            if ex.name == name:
+                return ex
+        raise KeyError(name)
+
+    def _load_current(self) -> None:
+        if self.current is None:
+            return
+        if self._save_timer is not None:
+            self._save_timer.stop()
+            self._save_timer = None
+        self.query_one(OutputPanel).reset_hint()
+        pane = self.query_one(EditorPane)
+        pane.load_exercise(self._exercise(self.current))
+        self._loaded_text = pane.text
+        self._failure_counts[self.current] = 0
+        self._record_resume(self.current)
+
+    def _record_resume(self, exercise: str | None) -> None:
+        self.app.state.record_resume(self.topic, exercise)
+        save_state(self.app.root, self.app.state)
+
+    # --- auto-save / run loop -------------------------------------------
+
+    def on_text_area_changed(self, event: TextArea.Changed) -> None:
+        if event.text_area is not self.query_one("#code", TextArea):
+            return
+        if self.query_one(EditorPane).text == self._loaded_text:
+            return
+        if self._save_timer is not None:
+            self._save_timer.stop()
+        self._save_timer = self.set_timer(_DEBOUNCE_SECONDS, self._flush_and_run)
+
+    def _flush_and_run(self) -> None:
+        self._save_timer = None
+        if self.current is None:
+            return
+        ex = self._exercise(self.current)
+        ex.path.write_text(self.query_one(EditorPane).text, encoding="utf-8")
+        self._run_current()
+
+    def _run_current(self) -> None:
+        if self.current is None:
+            return
+        ex = self._exercise(self.current)
+        completed, total = self._progress_counts()
+        self.query_one(OutputPanel).render_running(ex, completed, total)
+        self.run_worker(
+            lambda: self._run_blocking(ex), exclusive=True, thread=True
+        )
+
+    def _run_blocking(self, exercise: Exercise) -> None:
+        result = run_exercise(exercise)
+        self.app.call_from_thread(self._apply_result, exercise, result)
+
+    def _apply_result(self, exercise: Exercise, result: RunResult) -> None:
+        if not self.is_attached:
+            return  # the track screen was popped while a run was in flight
+        if exercise.name != self.current:
+            return
+        if result.exit_code != 0 or result.timed_out:
+            self._failure_counts[exercise.name] = (
+                self._failure_counts.get(exercise.name, 0) + 1
+            )
+        else:
+            self._failure_counts[exercise.name] = 0
+        completed, total = self._progress_counts()
+        self.query_one(OutputPanel).render_result(
+            exercise,
+            result,
+            failures=self._failure_counts.get(exercise.name, 0),
+            completed=completed,
+            total=total,
+        )
+        if not result.passed:
+            return
+        self.app.state.mark_done(exercise.name)
+        save_state(self.app.root, self.app.state)
+        self.current = next_pending(self._exercises(), self.app.state.completed)
+        self._render_state()
+        if self.current is None:
+            self._record_resume(None)
+            self.query_one(OutputPanel).show_final(
+                f"Topic '{self.topic}' complete — press F4 for topics."
+            )
+            return
+        self._load_current()
+        self._run_current()
+
+    # --- actions ---------------------------------------------------------
+
+    def action_toggle_hint(self) -> None:
+        if self.current is None:
+            return
+        self.query_one(OutputPanel).toggle_hint(self._exercise(self.current).hint)
+
+    def action_reset(self) -> None:
+        from pythonlings.core.reset import restore
+
+        if self.current is None:
+            return
+        if self._save_timer is not None:
+            self._save_timer.stop()
+            self._save_timer = None
+        restore(self.app.root, self._exercise(self.current))
+        self._load_current()
+        self._run_current()
+
+    def action_toggle_list(self) -> None:
+        tree = self.query_one(ExerciseTree)
+        tree.display = not tree.display
+
+    def action_docs(self) -> None:
+        if self.current is None:
+            return
+        from pythonlings.screens.docs import DocsScreen
+
+        self.app.push_screen(DocsScreen(self._exercise(self.current)))
+
+    def action_topics(self) -> None:
+        self._flush_pending()
+        if self.current is not None:
+            self._record_resume(self.current)
+        self.app.pop_screen()
+
+    def action_quit(self) -> None:
+        self._flush_pending()
+        if self.current is not None:
+            self._record_resume(self.current)
+        self.app.exit(0)
+
+    def _flush_pending(self) -> None:
+        if self._save_timer is not None:
+            self._save_timer.stop()
+            self._save_timer = None
+            if self.current is not None:
+                self._exercise(self.current).path.write_text(
+                    self.query_one(EditorPane).text, encoding="utf-8"
+                )

pythonlings/widgets/editor_pane.py

@@ -0,0 +1,33 @@
+# pythonlings/widgets/editor_pane.py
+from __future__ import annotations
+
+from textual.app import ComposeResult
+from textual.containers import Vertical
+from textual.widgets import TextArea
+
+from pythonlings.core.exercise import Exercise
+
+
+class EditorPane(Vertical):
+    """The in-TUI code editor for the current exercise."""
+
+    def compose(self) -> ComposeResult:
+        try:
+            editor = TextArea.code_editor("", language="python", id="code")
+        except Exception:
+            # tree-sitter Python grammar unavailable — fall back to plain text.
+            editor = TextArea.code_editor("", id="code")
+        yield editor
+
+    def load_exercise(self, exercise: Exercise) -> None:
+        """Replace the editor contents with the exercise file from disk."""
+        area = self.query_one("#code", TextArea)
+        area.text = exercise.path.read_text(encoding="utf-8")
+        area.move_cursor((0, 0))
+
+    def focus_editor(self) -> None:
+        self.query_one("#code", TextArea).focus()
+
+    @property
+    def text(self) -> str:
+        return self.query_one("#code", TextArea).text

pythonlings/widgets/exercise_tree.py

@@ -0,0 +1,33 @@
+# pythonlings/widgets/exercise_tree.py
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from textual.widgets import Tree
+
+if TYPE_CHECKING:
+    from pythonlings.core.exercise import Exercise
+
+
+class ExerciseTree(Tree[str]):
+    def __init__(self) -> None:
+        super().__init__("exercises", id="tree")
+        self.show_root = False
+
+    def render_topic(
+        self,
+        topic: str,
+        exercises: list["Exercise"],
+        completed: set[str],
+        current: str | None,
+    ) -> None:
+        self.clear()
+        node = self.root.add(topic, expand=True)
+        for ex in exercises:
+            if ex.name in completed:
+                marker = "✓"
+            elif ex.name == current:
+                marker = "●"
+            else:
+                marker = "🔒"
+            node.add_leaf(f"{marker} {ex.name}", data=ex.name)

pythonlings/widgets/output_panel.py

@@ -0,0 +1,180 @@
+# pythonlings/widgets/output_panel.py
+from __future__ import annotations
+
+import os
+
+from textual.app import ComposeResult
+from textual.containers import Vertical
+from textual.widgets import Static
+
+from pythonlings.core.exercise import Exercise, RunResult
+
+_INSTRUCTION = "Edit the code on the left. Checks update automatically."
+
+
+class OutputPanel(Vertical):
+    def compose(self) -> ComposeResult:
+        yield Static("", id="output-header")
+        yield Static("", id="goal")
+        yield Static("", id="docs")
+        yield Static("Loading…", id="status")
+        yield Static("", id="next-step")
+        yield Static("", id="details")
+        yield Static("", id="hint")
+
+    def renderable_text(self) -> str:
+        parts: list[str] = []
+        for widget_id in (
+            "output-header",
+            "goal",
+            "docs",
+            "status",
+            "next-step",
+            "details",
+            "hint",
+        ):
+            parts.append(str(self.query_one(f"#{widget_id}", Static).content))
+        return "\n".join(parts)
+
+    def render_running(
+        self, exercise: Exercise, completed: int = 0, total: int = 0
+    ) -> None:
+        self.remove_class("passed", "failed", "pending")
+        self._render_header(exercise, completed, total)
+        self.query_one("#goal", Static).update(
+            f"[bold]Goal[/bold]\n{self._goal_from(exercise)}"
+        )
+        self._render_docs(exercise)
+        self.query_one("#status", Static).update(
+            "[bold blue]Running checks...[/bold blue]"
+        )
+        self.query_one("#next-step", Static).update(
+            "Keep editing; results update automatically."
+        )
+        self.query_one("#details", Static).update("")
+
+    def render_result(
+        self,
+        exercise: Exercise,
+        result: RunResult,
+        failures: int = 0,
+        completed: int = 0,
+        total: int = 0,
+    ) -> None:
+        self._render_header(exercise, completed, total)
+        self.query_one("#goal", Static).update(
+            f"[bold]Goal[/bold]\n{self._goal_from(exercise)}"
+        )
+        self._render_docs(exercise)
+        details = (result.stderr or result.stdout).rstrip()
+        self.query_one("#details", Static).update(
+            f"[bold]Details[/bold]\n{details}" if details else ""
+        )
+        self.remove_class("passed", "failed", "pending")
+        if result.timed_out:
+            self.add_class("failed")
+            self.query_one("#status", Static).update(
+                "[bold red]Not passing yet[/bold red]"
+            )
+            self.query_one("#next-step", Static).update(
+                f"Timed out after {result.duration_s:.1f}s. "
+                "Check for an infinite loop."
+            )
+            return
+        if result.exit_code != 0:
+            self.add_class("failed")
+            self.query_one("#status", Static).update(
+                "[bold red]Not passing yet[/bold red]"
+            )
+            nudge = (
+                self._hint_nudge(exercise)
+                if failures
+                else "Hint available: press F1."
+            )
+            self.query_one("#next-step", Static).update(
+                f"Read the details, fix the code, then pause typing.\n{nudge}"
+            )
+            return
+        if exercise.is_pending():
+            self.add_class("pending")
+            self.query_one("#status", Static).update(
+                "[bold yellow]Checks pass, remove marker[/bold yellow]"
+            )
+            self.query_one("#next-step", Static).update(
+                "Remove the # I AM NOT DONE line to advance."
+            )
+            return
+        self.add_class("passed")
+        self.query_one("#status", Static).update(
+            f"[bold green]✓ {exercise.name} complete[/bold green]"
+        )
+        self.query_one("#next-step", Static).update(
+            "Loading the next exercise."
+        )
+
+    def show_final(self, message: str) -> None:
+        """Render the curriculum-complete screen."""
+        self.remove_class("failed", "pending")
+        self.add_class("passed")
+        self.query_one("#hint", Static).remove_class("visible")
+        self.query_one("#output-header", Static).update(
+            "[bold green]All exercises complete[/bold green]"
+        )
+        self.query_one("#goal", Static).update("")
+        self.query_one("#docs", Static).update("")
+        self.query_one("#status", Static).update(message)
+        self.query_one("#next-step", Static).update("")
+        self.query_one("#details", Static).update("")
+
+    def _render_header(
+        self, exercise: Exercise, completed: int = 0, total: int = 0
+    ) -> None:
+        header = self.query_one("#output-header", Static)
+        progress = f"   [dim]{completed}/{total} complete[/dim]" if total else ""
+        header.update(
+            f"[bold]{exercise.name}[/bold]{progress}   "
+            f"[dim]{self._display_path(exercise)}[/dim]\n"
+            f"{_INSTRUCTION}"
+        )
+
+    def _goal_from(self, exercise: Exercise) -> str:
+        for line in exercise.path.read_text(encoding="utf-8").splitlines()[:12]:
+            stripped = line.strip()
+            if stripped.startswith("# Goal:"):
+                return stripped.removeprefix("# Goal:").strip()
+            if stripped.startswith("# Exercise:"):
+                return stripped.removeprefix("# Exercise:").strip()
+        return exercise.name
+
+    def _render_docs(self, exercise: Exercise) -> None:
+        docs = exercise.docs.strip()
+        self.query_one("#docs", Static).update(
+            f"[bold]Docs[/bold]\n{docs}" if docs else ""
+        )
+
+    @staticmethod
+    def _hint_nudge(exercise: Exercise) -> str:
+        first = exercise.hint.strip().split(".")[0].strip()
+        return f"{first}." if first else "Hint available: press F1."
+
+    @staticmethod
+    def _display_path(exercise: Exercise) -> str:
+        # Prefer a short path relative to the working directory; fall back to
+        # the absolute path when that isn't possible (e.g. different drives).
+        try:
+            return os.path.relpath(exercise.path)
+        except ValueError:
+            return str(exercise.path)
+
+    def toggle_hint(self, text: str) -> None:
+        hint = self.query_one("#hint", Static)
+        if "visible" in hint.classes:
+            hint.remove_class("visible")
+        else:
+            hint.add_class("visible")
+            hint.update(f"[italic]Hint:[/italic] {text or '(no hint provided)'}")
+
+    def reset_hint(self) -> None:
+        hint = self.query_one("#hint", Static)
+        hint.remove_class("visible")
+        hint.update("")