Add more docstrings/comments

Author: johnslavik

Lib/_pyrepl/content.py

@@ -21,6 +21,8 @@ class PromptContent:
 
 @dataclass(frozen=True, slots=True)
 class SourceLine:
+    """One logical line from the editor buffer, before styling."""
+
     lineno: int
     text: str
     start_offset: int
@@ -59,6 +61,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,7 @@
 
 @dataclass(frozen=True, slots=True)
 class LayoutRow:
+    """Metadata for one physical screen row."""
     prompt_width: int
     char_widths: tuple[int, ...]
     suffix_width: int = 0
@@ -28,6 +31,10 @@ 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.
+    """
     rows: tuple[LayoutRow, ...]
 
     @classmethod
@@ -95,6 +102,7 @@ def xy_to_pos(self, x: int, y: int) -> int:
 
 @dataclass(frozen=True, slots=True)
 class WrappedRow:
+    """One physical screen row after wrapping, with all metadata needed for rendering."""
     prompt_text: str = ""
     prompt_width: int = 0
     fragments: tuple[ContentFragment, ...] = ()
@@ -116,6 +124,10 @@ def layout_content_lines(
     width: int,
     start_offset: int,
 ) -> LayoutResult:
+    """Wrap content lines to fit *width* columns.
+    
+    Line boundaries are marked with ``\\``.
+    """
     if width <= 0:
         return LayoutResult((), LayoutMap(()), ())
 
@@ -140,6 +152,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 +174,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:
+    """Parts of the screen state that have changed and need to be refreshed."""
+
     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,6 +18,7 @@
 
 
 class _ThemeSyntax(Protocol):
+    """Protocol for theme objects that map tag names to SGR escape strings."""
     def __getitem__(self, key: str, /) -> str: ...
 
 
@@ -173,9 +174,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)))
@@ -250,10 +253,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 +279,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 +319,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

@@ -152,12 +152,19 @@ def poll(self, timeout: float | None = None) -> list[int]:
 @dataclass(frozen=True, slots=True)
 class UnixRefreshPlan:
     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