From 07bc450a50eba221ebdf6bfc40ba7881dafb8973 Mon Sep 17 00:00:00 2001 From: Dave Pearson Date: Tue, 14 Feb 2023 14:12:25 +0000 Subject: [PATCH 1/3] Assorted docstring tidying in dom.py Noticed that there were a few properties that still had types in the docstrings; which we've since decided to not do; so this removes them. Also some other assorted docstring tweaks in the same file. --- src/textual/dom.py | 71 ++++++++++++++++++---------------------------- 1 file changed, 27 insertions(+), 44 deletions(-) diff --git a/src/textual/dom.py b/src/textual/dom.py index 74f87d073..24a1b7b1d 100644 --- a/src/textual/dom.py +++ b/src/textual/dom.py @@ -225,7 +225,7 @@ class DOMNode(MessagePump): @property def _node_bases(self) -> Iterator[Type[DOMNode]]: - """Iterator[Type[DOMNode]]: The DOMNode bases classes (including self.__class__)""" + """The DOMNode bases classes (including self.__class__)""" # Node bases are in reversed order so that the base class is lower priority return self._css_bases(self.__class__) @@ -337,12 +337,12 @@ class DOMNode(MessagePump): @property def parent(self) -> DOMNode | None: - """DOMNode | None: The parent node.""" + """The parent node.""" return cast("DOMNode | None", self._parent) @property def screen(self) -> "Screen": - """Screen: The screen that this node is contained within. + """The screen that this node is contained within. Note: This may not be the currently active screen within the app. @@ -360,7 +360,7 @@ class DOMNode(MessagePump): @property def id(self) -> str | None: - """str | None: The ID of this node, or None if the node has no ID.""" + """The ID of this node, or None if the node has no ID.""" return self._id @id.setter @@ -385,12 +385,12 @@ class DOMNode(MessagePump): @property def name(self) -> str | None: - """str | None: The name of the node.""" + """The name of the node.""" return self._name @property def css_identifier(self) -> str: - """str: A CSS selector that identifies this DOM node.""" + """A CSS selector that identifies this DOM node.""" tokens = [self.__class__.__name__] if self.id is not None: tokens.append(f"#{self.id}") @@ -398,7 +398,7 @@ class DOMNode(MessagePump): @property def css_identifier_styled(self) -> Text: - """Text: A stylized CSS identifier.""" + """A stylized CSS identifier.""" tokens = Text.styled(self.__class__.__name__) if self.id is not None: tokens.append(f"#{self.id}", style="bold") @@ -411,18 +411,18 @@ class DOMNode(MessagePump): @property def classes(self) -> frozenset[str]: - """frozenset[str]: A frozenset of the current classes set on the widget.""" + """A frozenset of the current classes set on the widget.""" return frozenset(self._classes) @property def pseudo_classes(self) -> frozenset[str]: - """frozenset[str]: A set of all pseudo classes""" + """A set of all pseudo classes""" pseudo_classes = frozenset({*self.get_pseudo_classes()}) return pseudo_classes @property def css_path_nodes(self) -> list[DOMNode]: - """list[DOMNode] A list of nodes from the root to this node, forming a "path".""" + """A list of nodes from the root to this node, forming a "path".""" result: list[DOMNode] = [self] append = result.append @@ -451,12 +451,7 @@ class DOMNode(MessagePump): @property def display(self) -> bool: - """ - Check if this widget should display or not. - - Returns: - ``True`` if this DOMNode is displayed (``display != "none"``) otherwise ``False`` . - """ + """Should the DOM node be displayed?""" return self.styles.display != "none" and not (self._closing or self._closed) @display.setter @@ -482,11 +477,7 @@ class DOMNode(MessagePump): @property def visible(self) -> bool: - """Check if the node is visible or None. - - Returns: - True if the node is visible. - """ + """Is the DOM node visible?""" return self.styles.visibility != "hidden" @visible.setter @@ -607,12 +598,7 @@ class DOMNode(MessagePump): @property def background_colors(self) -> tuple[Color, Color]: - """Get the background color and the color of the parent's background. - - Returns: - Tuple of (base background, background) - - """ + """The background color and the color of the parent's background.""" base_background = background = BLACK for node in reversed(self.ancestors_with_self): styles = node.styles @@ -623,11 +609,7 @@ class DOMNode(MessagePump): @property def colors(self) -> tuple[Color, Color, Color, Color]: - """Gets the Widgets foreground and background colors, and its parent's (base) colors. - - Returns: - Tuple of (base background, base color, background, color) - """ + """The widget's foreground and background colors, and its parent's (base) colors.""" base_background = background = WHITE base_color = color = BLACK for node in reversed(self.ancestors_with_self): @@ -646,9 +628,10 @@ class DOMNode(MessagePump): @property def ancestors_with_self(self) -> list[DOMNode]: - """list[DOMNode]: A list of Nodes by tracing a path all the way back to App. + """A list of Nodes by tracing a path all the way back to App. - Note: This is inclusive of ``self``. + Note: + This is inclusive of ``self``. """ nodes: list[MessagePump | None] = [] add_node = nodes.append @@ -660,17 +643,12 @@ class DOMNode(MessagePump): @property def ancestors(self) -> list[DOMNode]: - """list[DOMNode]: A list of ancestor nodes Nodes by tracing ancestors all the way back to App.""" + """A list of ancestor nodes Nodes by tracing ancestors all the way back to App.""" return self.ancestors_with_self[1:] @property def displayed_children(self) -> list[Widget]: - """The children which don't have display: none set. - - Returns: - Children of this widget which will be displayed. - - """ + """The children which don't have display: none set.""" return [child for child in self._nodes if child.display] def watch( @@ -919,7 +897,6 @@ class DOMNode(MessagePump): Args: *class_names: CSS class names to remove. - """ check_identifiers("class name", *class_names) old_classes = self._classes.copy() @@ -936,7 +913,6 @@ class DOMNode(MessagePump): Args: *class_names: CSS class names to toggle. - """ check_identifiers("class name", *class_names) old_classes = self._classes.copy() @@ -949,7 +925,14 @@ class DOMNode(MessagePump): pass def has_pseudo_class(self, *class_names: str) -> bool: - """Check for pseudo class (such as hover, focus etc)""" + """Check for pseudo classes (such as hover, focus etc) + + Args: + *class_names: The pseudo classes to check for. + + Returns: + `True` if the DOM node has those pseudo classes, `False` if not. + """ has_pseudo_classes = self.pseudo_classes.issuperset(class_names) return has_pseudo_classes From f92f7786b2bb893765cc6fad52a9b9feaad613fd Mon Sep 17 00:00:00 2001 From: Dave Pearson Date: Tue, 14 Feb 2023 15:11:56 +0000 Subject: [PATCH 2/3] Tidy up various docstrings in ListView Adding some actions docstrings (#1729) and also tweaking a couple of others to better conform with our docstring standard. --- src/textual/widgets/_list_view.py | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/src/textual/widgets/_list_view.py b/src/textual/widgets/_list_view.py index 76c0fdf05..2a319b6f9 100644 --- a/src/textual/widgets/_list_view.py +++ b/src/textual/widgets/_list_view.py @@ -13,8 +13,10 @@ from textual.widgets._list_item import ListItem class ListView(Vertical, can_focus=True, can_focus_children=False): - """Displays a vertical list of `ListItem`s which can be highlighted - and selected using the mouse or keyboard. + """A vertical list view widget. + + Displays a vertical list of `ListItem`s which can be highlighted and + selected using the mouse or keyboard. Attributes: index: The index in the list that's currently highlighted. @@ -89,16 +91,21 @@ class ListView(Vertical, can_focus=True, can_focus_children=False): @property def highlighted_child(self) -> ListItem | None: - """ListItem | None: The currently highlighted ListItem, - or None if nothing is highlighted. - """ + """The currently highlighted ListItem, or None if nothing is highlighted.""" if self.index is None: return None elif 0 <= self.index < len(self._nodes): return self._nodes[self.index] def validate_index(self, index: int | None) -> int | None: - """Clamp the index to the valid range, or set to None if there's nothing to highlight.""" + """Clamp the index to the valid range, or set to None if there's nothing to highlight. + + Args: + index: The index to clamp. + + Returns: + The clamped index. + """ if not self._nodes or index is None: return None return self._clamp_index(index) @@ -155,13 +162,16 @@ class ListView(Vertical, can_focus=True, can_focus_children=False): return await_remove def action_select_cursor(self) -> None: + """Select the current item in the list.""" selected_child = self.highlighted_child self.post_message_no_wait(self.Selected(self, selected_child)) def action_cursor_down(self) -> None: + """Select the next item in the list.""" self.index += 1 def action_cursor_up(self) -> None: + """Select the previous item in the list.""" self.index -= 1 def on_list_item__child_clicked(self, event: ListItem._ChildClicked) -> None: From 3cd879d2a6ff3fac4564a92e9028106b20f680c7 Mon Sep 17 00:00:00 2001 From: Dave Pearson Date: Tue, 14 Feb 2023 15:25:15 +0000 Subject: [PATCH 3/3] Correct the wording of what the up/down actions do There's a difference here between select and highlight and I got sloppy with the wording. This corrects that. --- src/textual/widgets/_list_view.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/textual/widgets/_list_view.py b/src/textual/widgets/_list_view.py index 2a319b6f9..efb552f0c 100644 --- a/src/textual/widgets/_list_view.py +++ b/src/textual/widgets/_list_view.py @@ -167,11 +167,11 @@ class ListView(Vertical, can_focus=True, can_focus_children=False): self.post_message_no_wait(self.Selected(self, selected_child)) def action_cursor_down(self) -> None: - """Select the next item in the list.""" + """Highlight the next item in the list.""" self.index += 1 def action_cursor_up(self) -> None: - """Select the previous item in the list.""" + """Highlight the previous item in the list.""" self.index -= 1 def on_list_item__child_clicked(self, event: ListItem._ChildClicked) -> None: