Merge pull request #123 from johnslavik/pablo-pyrepl-docstrings

PyREPL refactor: add more docstrings/comments

Author: pablogsal

Lib/_pyrepl/content.py

@@ -7,20 +7,63 @@
 
 @dataclass(frozen=True, slots=True)
 class ContentFragment:
+    """A single display character with its visual width and style.
+
+    The body of ``>>> def greet`` becomes one fragment per character::
+
+        d  e  f     g  r  e  e  t
+        ╰──┴──╯     ╰──┴──┴──┴──╯
+        keyword       (unstyled)
+
+    e.g. ``ContentFragment("d", 1, StyleRef(tag="keyword"))``.
+    """
+
     text: str
     width: int
     style: StyleRef = StyleRef()
 
 
 @dataclass(frozen=True, slots=True)
 class PromptContent:
+    """The prompt split into leading full-width lines and an inline portion.
+
+    For the common ``">>> "`` prompt (no newlines)::
+
+        >>> def greet(name):
+        ╰─╯
+        text=">>> ", width=4, leading_lines=()
+
+    If ``sys.ps1`` contains newlines, e.g. ``"Python 3.13\\n>>> "``::
+
+        Python 3.13              ← leading_lines[0]
+        >>> def greet(name):
+        ╰─╯
+        text=">>> ", width=4
+    """
+
     leading_lines: tuple[ContentFragment, ...]
     text: str
     width: int
 
 
 @dataclass(frozen=True, slots=True)
 class SourceLine:
+    """One logical line from the editor buffer, before styling.
+
+    Given this two-line input in the REPL::
+
+        >>> def greet(name):
+        ...     return name
+                       ▲ cursor
+
+    The buffer ``"def greet(name):\\n    return name"`` yields::
+
+        SourceLine(lineno=0, text="def greet(name):",
+                   start_offset=0, has_newline=True)
+        SourceLine(lineno=1, text="    return name",
+                   start_offset=17, cursor_index=14)
+    """
+
     lineno: int
     text: str
     start_offset: int
@@ -34,6 +77,15 @@ def cursor_on_line(self) -> bool:
 
 @dataclass(frozen=True, slots=True)
 class ContentLine:
+    """A logical line paired with its prompt and styled body.
+
+    For ``>>> def greet(name):``::
+
+        >>> def greet(name):
+        ╰─╯ ╰──────────────╯
+        prompt       body: one ContentFragment per character
+    """
+
     source: SourceLine
     prompt: PromptContent
     body: tuple[ContentFragment, ...]
@@ -59,6 +111,7 @@ def build_body_fragments(
     colors: list[ColorSpan] | None,
     start_index: int,
 ) -> tuple[ContentFragment, ...]:
+    """Convert a line's text into styled content fragments."""
     # Two separate loops to avoid the THEME() call in the common uncolored path.
     if colors is None:
         return tuple(

Lib/_pyrepl/layout.py

@@ -1,3 +1,5 @@
+"""Wrap content lines to the terminal width before rendering."""
+
 from __future__ import annotations
 
 from dataclasses import dataclass
@@ -9,6 +11,16 @@
 
 @dataclass(frozen=True, slots=True)
 class LayoutRow:
+    """Metadata for one physical screen row.
+
+    For the row ``>>> def greet(name):``::
+
+        >>> def greet(name):
+        ╰─╯ ╰──────────────╯
+         4    char_widths=(1,1,1,…)  ← 16 entries
+              buffer_advance=17      ← includes the newline
+    """
+
     prompt_width: int
     char_widths: tuple[int, ...]
     suffix_width: int = 0
@@ -28,6 +40,16 @@ def screeninfo(self) -> ScreenInfoRow:
 
 @dataclass(frozen=True, slots=True)
 class LayoutMap:
+    """Mapping between buffer positions and screen coordinates.
+
+    Single source of truth for cursor placement.  Given::
+
+        >>> def greet(name):     ← row 0, buffer_advance=17
+        ...     return name      ← row 1, buffer_advance=15
+                       ▲cursor
+
+    ``pos_to_xy(31)`` → ``(18, 1)``:  prompt width 4 + 14 body chars.
+    """
     rows: tuple[LayoutRow, ...]
 
     @classmethod
@@ -95,6 +117,14 @@ def xy_to_pos(self, x: int, y: int) -> int:
 
 @dataclass(frozen=True, slots=True)
 class WrappedRow:
+    """One physical screen row after wrapping, ready for rendering.
+
+    When a line overflows the terminal width, it splits into
+    multiple rows with a ``\\`` continuation marker::
+
+        >>> x = "a very long li\\   ← suffix="\\", suffix_width=1
+        ne that wraps"              ← prompt_text="" (continuation)
+    """
     prompt_text: str = ""
     prompt_width: int = 0
     fragments: tuple[ContentFragment, ...] = ()
@@ -116,6 +146,15 @@ def layout_content_lines(
     width: int,
     start_offset: int,
 ) -> LayoutResult:
+    """Wrap content lines to fit *width* columns.
+
+    A short line passes through as one ``WrappedRow``; a long line is
+    split at the column boundary with ``\\`` markers::
+
+        >>> short = 1           ← one WrappedRow
+        >>> x = "a long stri\\  ← two WrappedRows, first has suffix="\\"
+        ng"
+    """
     if width <= 0:
         return LayoutResult((), LayoutMap(()), ())
 
@@ -140,6 +179,7 @@ def layout_content_lines(
         body = tuple(line.body)
         body_widths = tuple(fragment.width for fragment in body)
 
+        # Fast path: line fits on one row.
         if not body_widths or (sum(body_widths) + prompt_width) < width:
             offset += len(body) + newline_advance
             line_end_offsets.append(offset)
@@ -161,11 +201,13 @@ def layout_content_lines(
             )
             continue
 
+        # Slow path: line needs wrapping.
         current_prompt = prompt_text
         current_prompt_width = prompt_width
         start = 0
         total = len(body)
         while True:
+            # Find how many characters fit on this row.
             index_to_wrap_before = 0
             column = 0
             for char_width in body_widths[start:]:

Lib/_pyrepl/reader.py

@@ -157,6 +157,8 @@ def make_default_commands() -> dict[CommandName, CommandClass]:
 
 @dataclass(frozen=True, slots=True)
 class RefreshInvalidation:
+    """Which parts of the screen need to be recomputed on the next refresh."""
+
     cursor_only: bool = False
     buffer_from_pos: int | None = None
     prompt: bool = False
@@ -308,6 +310,8 @@ class Reader:
     ## cached metadata to speed up screen refreshes
     @dataclass
     class RefreshCache:
+        """Previously computed render/layout data for incremental refresh."""
+
         render_lines: list[RenderLine] = field(default_factory=list)
         layout_rows: list[LayoutRow] = field(default_factory=list)
         line_end_offsets: list[int] = field(default_factory=list)
@@ -412,6 +416,7 @@ def calc_screen(self) -> RenderedScreen:
                 )
                 and (self.invalidation.message or self.invalidation.overlay)
             ):
+                # Fast path: only overlays or messages changed.
                 offset, num_common_lines = self.last_refresh_cache.get_cached_location(
                     self,
                     reuse_full=True,

Lib/_pyrepl/render.py

@@ -18,11 +18,20 @@
 
 
 class _ThemeSyntax(Protocol):
+    """Protocol for theme objects that map tag names to SGR escape strings."""
     def __getitem__(self, key: str, /) -> str: ...
 
 
 @dataclass(frozen=True, slots=True)
 class RenderCell:
+    """One terminal cell: a character, its column width, and SGR style.
+
+    A screen row like ``>>> def`` is a sequence of cells::
+
+        >  >  >     d  e  f
+       ╰─╯╰─╯╰─╯╰─╯╰─╯╰─╯╰─╯
+    """
+
     text: str
     width: int
     style: StyleRef = field(default_factory=StyleRef)
@@ -94,6 +103,12 @@ def append_plain_text(segment: str) -> None:
 
 @dataclass(frozen=True, slots=True)
 class RenderLine:
+    """One physical screen row as a tuple of :class:`RenderCell` objects.
+
+    ``text`` is the pre-rendered terminal string (characters + SGR escapes);
+    ``width`` is the total visible column count.
+    """
+
     cells: tuple[RenderCell, ...]
     text: str
     width: int
@@ -139,10 +154,16 @@ def from_rendered_text(cls, text: str) -> Self:
 class ScreenOverlay:
     """An overlay that replaces or inserts lines at a screen position.
 
-    If insert is True, lines are spliced in (shifting content down);
-    if False (default), lines replace existing content at y.
+    If *insert* is True, lines are spliced in (shifting content down);
+    if False (default), lines replace existing content at *y*.
 
     Overlays are used to display tab completion menus and status messages.
+    For example, a tab-completion menu inserted below the input::
+
+        >>> os.path.j           ← line 0 (base content)
+                    join        ← ScreenOverlay(y=1, insert=True)
+                    junction    ←   (pushes remaining lines down)
+        ...                     ← line 1 (shifted down by 2)
     """
     y: int
     lines: tuple[RenderLine, ...]
@@ -151,6 +172,19 @@ class ScreenOverlay:
 
 @dataclass(frozen=True, slots=True)
 class RenderedScreen:
+    """The complete screen state: content lines, cursor, and overlays.
+
+    ``lines`` holds the base content; ``composed_lines`` is the final
+    result after overlays (completion menus, messages) are applied::
+
+        lines:                     composed_lines:
+        ┌──────────────────┐       ┌──────────────────┐
+        │>>> os.path.j     │       │>>> os.path.j     │
+        │...               │  ──►  │            join  │ ← overlay
+        └──────────────────┘       │...               │
+                                   └──────────────────┘
+    """
+
     lines: tuple[RenderLine, ...]
     cursor: CursorXY
     overlays: tuple[ScreenOverlay, ...] = ()
@@ -173,9 +207,11 @@ def _compose(self) -> tuple[RenderLine, ...]:
                 "overlays must be sorted by ascending y"
             )
             if overlay.insert:
+                # Splice overlay lines in, pushing existing content down.
                 lines[adjusted_y:adjusted_y] = overlay.lines
                 y_offset += len(overlay.lines)
             else:
+                # Replace existing lines at the overlay position.
                 target_len = adjusted_y + len(overlay.lines)
                 if len(lines) < target_len:
                     lines.extend([EMPTY_RENDER_LINE] * (target_len - len(lines)))
@@ -217,6 +253,17 @@ def screen_lines(self) -> tuple[str, ...]:
 
 @dataclass(frozen=True, slots=True)
 class LineDiff:
+    """The changed region between an old and new version of one screen row.
+
+    When the user types ``e`` so the row changes from
+    ``>>> nam`` to ``>>> name``::
+
+        >>> n a m       old
+        >>> n a m e     new
+                  ╰─╯
+                  start_cell=7, new_cells=("m","e"), old_cells=("m",)
+    """
+
     start_cell: int
     start_x: int
     old_cells: tuple[RenderCell, ...]
@@ -250,10 +297,13 @@ class LineUpdate:
     y: int
     start_cell: int
     start_x: int
+    """Screen x-coordinate where the update begins. Used for cursor positioning."""
     cells: tuple[RenderCell, ...]
     char_width: int = 0
     clear_eol: bool = False
     reset_to_margin: bool = False
+    """If True, the console must resync the cursor position after writing
+    (needed when cells contain non-SGR escape sequences that may move the cursor)."""
     text: str = field(init=False, default="")
 
     def __post_init__(self) -> None:
@@ -273,6 +323,14 @@ def render_cells(
     cells: Sequence[RenderCell],
     visual_style: str | None = None,
 ) -> str:
+    """Render a sequence of cells into a terminal string with SGR escapes.
+
+    Tracks the active SGR state to emit resets only when the style
+    actually changes, minimizing output bytes.
+
+    If *visual_style* is given (used by redraw visualization), it is appended
+    to every cell's style.
+    """
     rendered: list[str] = []
     active_escape = ""
     for cell in cells:
@@ -305,6 +363,8 @@ def diff_render_lines(old: RenderLine, new: RenderLine) -> LineDiff | None:
     start_x = 0
     max_prefix = min(len(old.cells), len(new.cells))
     while prefix < max_prefix and old.cells[prefix] == new.cells[prefix]:
+        # Stop at any cell with non-SGR controls, since those might affect
+        # cursor position and must be re-emitted.
         if old.cells[prefix].controls:
             break
         start_x += old.cells[prefix].width

Lib/_pyrepl/unix_console.py

@@ -151,13 +151,35 @@ def poll(self, timeout: float | None = None) -> list[int]:
 
 @dataclass(frozen=True, slots=True)
 class UnixRefreshPlan:
+    """Instructions for updating the terminal after a screen change.
+
+    After the user types ``e`` to complete ``name``::
+
+        Before: >>> def greet(nam|):   
+                                 ▲
+                        LineUpdate here: insert_char "e"
+
+         After: >>> def greet(name|):
+                                  ▲
+
+    Only the changed cells are sent to the terminal; unchanged rows
+    are skipped entirely.
+    """
+
     grow_lines: int
+    """Number of blank lines to append at the bottom to accommodate new content."""
     use_tall_mode: bool
+    """Use absolute cursor addressing via ``cup`` instead of relative moves.
+    Activated when content exceeds one screen height."""
     offset: int
+    """Vertical scroll offset: the buffer row displayed at the top of the terminal window."""
     reverse_scroll: int
+    """Number of lines to scroll backwards (content moves down)."""
     forward_scroll: int
+    """Number of lines to scroll forwards (content moves up)."""
     line_updates: tuple[LineUpdate, ...]
     cleared_lines: tuple[int, ...]
+    """Row indices to erase (old content with no replacement)."""
     rendered_screen: RenderedScreen
     cursor: tuple[int, int]
 

Lib/_pyrepl/utils.py

@@ -437,7 +437,7 @@ def prev_next_window[T](
 
 @dataclass(frozen=True, slots=True)
 class StyleRef:
-    tag: str | None = None
+    tag: str | None = None  # From THEME().syntax, e.g. "keyword", "builtin"
     sgr: str = ""
 
     @classmethod