docstrings and comments

Author: willmcgugan

src/textual/command.py

@@ -1000,8 +1000,10 @@ async def _gather_commands(self, search_value: str) -> None:
             # list of commands that have been gathered so far.
 
             def build_prompt() -> Iterable[Content]:
+                """Generator for prompt content."""
                 assert hit is not None
                 yield Content.from_rich_text(hit.prompt)
+                # Optional help text
                 if hit.help:
                     help_style = VisualStyle.from_styles(
                         self.get_component_styles("command-palette--help-text")

src/textual/drivers/linux_driver.py

@@ -269,6 +269,7 @@ def on_terminal_resize(signum, stack) -> None:
         self.write("\x1b[>1u")  # https://sw.kovidgoyal.net/kitty/keyboard-protocol/
         # Disambiguate escape codes https://sw.kovidgoyal.net/kitty/keyboard-protocol/#progressive-enhancement
         self.write("\x1b[=1;u")
+
         self.flush()
         self._key_thread = Thread(target=self._run_input_thread)
         send_size_event()
@@ -366,6 +367,7 @@ def stop_application_mode(self) -> None:
         # Disable the Kitty keyboard protocol. This must be done before leaving
         # the alt screen. https://sw.kovidgoyal.net/kitty/keyboard-protocol/
         self.write("\x1b[<u")
+
         # Alt screen false, show cursor
         self.write("\x1b[?1049l")
         self.write("\x1b[?25h")

src/textual/visual.py

@@ -36,6 +36,7 @@ def is_visual(obj: object) -> bool:
     return isinstance(obj, Visual) or hasattr(obj, "textualize")
 
 
+# Note: not runtime checkable currently, as I've found that to be slow
 class SupportsTextualize(Protocol):
     """An object that supports the textualize protocol."""
 
@@ -52,6 +53,9 @@ class VisualError(Exception):
 def visualize(widget: Widget, obj: object) -> Visual:
     """Get a visual instance from an object.
 
+    If the object does not support the Visual protocol and is a Rich renderable, it
+    will be wrapped in a [RichVisual][textual.visual.RichVisual].
+
     Args:
         obj: An object.
 
@@ -87,7 +91,7 @@ def visualize(widget: Widget, obj: object) -> Visual:
 @rich.repr.auto
 @dataclass(frozen=True)
 class Style:
-    """Represent a content style (color and other attributes)."""
+    """Represents a style in the Visual interface (color and other attributes)."""
 
     background: Color = TRANSPARENT
     foreground: Color = TRANSPARENT
@@ -128,6 +132,14 @@ def __add__(self, other: object) -> Style:
 
     @classmethod
     def from_rich_style(cls, rich_style: RichStyle) -> Style:
+        """Build a Style from a (Rich) Style.
+
+        Args:
+            rich_style: A Rich Style object.
+
+        Returns:
+            New Style.
+        """
         return Style(
             Color.from_rich_color(rich_style.bgcolor),
             Color.from_rich_color(rich_style.color),
@@ -140,6 +152,12 @@ def from_rich_style(cls, rich_style: RichStyle) -> Style:
 
     @classmethod
     def from_styles(cls, styles: StylesBase) -> Style:
+        """Create a Visual Style from a Textual styles object.
+
+        Args:
+            styles: A Styles object, such as `my_widget.styles`.
+
+        """
         text_style = styles.text_style
         return Style(
             styles.background,
@@ -158,6 +176,11 @@ def from_styles(cls, styles: StylesBase) -> Style:
 
     @cached_property
     def rich_style(self) -> RichStyle:
+        """Convert this Styles in to a Rich style.
+
+        Returns:
+            A Rich style object.
+        """
         return RichStyle(
             color=(self.background + self.foreground).rich_color,
             bgcolor=self.background.rich_color,
@@ -209,18 +232,19 @@ def render_strips(
         Args:
             base_style: The base style.
             width: Width of desired render.
-            height: Height of desired render.
+            height: Height of desired render or `None` for any height.
+            style: A Visual Style.
 
         Returns:
-            An iterable of Strips.
+            An list of Strips.
         """
 
     @abstractmethod
     def get_optimal_width(self, container_width: int) -> int:
         """Get ideal width of the renderable to display its content.
 
         Args:
-            tab_size: Size of tabs.
+            container_size: The size of the container.
 
         Returns:
             A width in cells.
@@ -253,13 +277,13 @@ def to_strips(
             widget: Widget that produced the visual.
             visual: A Visual instance.
             width: Desired width (in cells).
-            height: Desired height (in lines).
+            height: Desired height (in lines) or `None` for no limit.
             style: A (Visual) Style instance.
-            pad: Pad to desired height?
+            pad: Pad to desired width?
             align: Tuple of horizontal and vertical alignment.
 
         Returns:
-            _type_: _description_
+            A list of Strips containing the render.
         """
         strips = visual.render_strips(widget, width, height, style)
         if height is None:
@@ -285,7 +309,15 @@ def to_strips(
 
 @rich.repr.auto
 class RichVisual(Visual):
+    """A Visual to wrap a Rich renderable."""
+
     def __init__(self, widget: Widget, renderable: RenderableType) -> None:
+        """
+
+        Args:
+            widget: The associated Widget.
+            renderable: A Rich renderable.
+        """
         self._widget = widget
         self._renderable = renderable
         self._measurement: Measurement | None = None
@@ -295,13 +327,12 @@ def __rich_repr__(self) -> rich.repr.Result:
         yield self._renderable
 
     def _measure(self, console: Console, options: ConsoleOptions) -> Measurement:
-        return Measurement.get(
-            console,
-            options,
-            self._widget.post_render(self._renderable, RichStyle.null()),
-        )
         if self._measurement is None:
-            self._measurement = Measurement.get(console, options, self._renderable)
+            self._measurement = Measurement.get(
+                console,
+                options,
+                self._widget.post_render(self._renderable, RichStyle.null()),
+            )
         return self._measurement
 
     def get_optimal_width(self, container_width: int) -> int:
@@ -363,7 +394,15 @@ def render_strips(
 
 @rich.repr.auto
 class Padding(Visual):
+    """A Visual to pad another visual."""
+
     def __init__(self, visual: Visual, spacing: Spacing):
+        """
+
+        Args:
+            Visual: A Visual.
+            spacing: A Spacing object containing desired padding dimensions.
+        """
         self._visual = visual
         self._spacing = spacing