diff --git a/CHANGELOG.md b/CHANGELOG.md index f45fb94d63..fb688a7c3b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,16 @@ and this project adheres to [Semantic Versioning](http://semver.org/). - Breaking change: changed default behaviour of `Vertical` (see `VerticalScroll`) https://github.com/Textualize/textual/issues/1957 - The default `overflow` style for `Horizontal` was changed to `hidden hidden` https://github.com/Textualize/textual/issues/1957 - `DirectoryTree` also accepts `pathlib.Path` objects as the path to list https://github.com/Textualize/textual/issues/1438 +- Some widget methods now return `self` instead of `None` https://github.com/Textualize/textual/pull/2102: + - `Widget`: `refresh`, `focus`, `reset_focus` + - `Button.press` + - `DataTable`: `clear`, `refresh_coordinate`, `refresh_row`, `refresh_column`, `sort` + - `Placehoder.cycle_variant` + - `Switch.toggle` + - `Tabs.clear` + - `TextLog`: `write`, `clear` + - `TreeNode`: `expand`, `expand_all`, `collapse`, `collapse_all`, `toggle`, `toggle_all` + - `Tree`: `clear`, `reset` ### Removed diff --git a/src/textual/dom.py b/src/textual/dom.py index 23e878ba46..cb9881f653 100644 --- a/src/textual/dom.py +++ b/src/textual/dom.py @@ -42,7 +42,7 @@ from .css.query import DOMQuery, QueryType from .screen import Screen from .widget import Widget - from typing_extensions import TypeAlias + from typing_extensions import Self, TypeAlias from typing_extensions import Literal @@ -950,5 +950,5 @@ def has_pseudo_class(self, *class_names: str) -> bool: has_pseudo_classes = self.pseudo_classes.issuperset(class_names) return has_pseudo_classes - def refresh(self, *, repaint: bool = True, layout: bool = False) -> None: - pass + def refresh(self, *, repaint: bool = True, layout: bool = False) -> Self: + return self diff --git a/src/textual/widget.py b/src/textual/widget.py index 6ac329d6d1..971bde61bb 100644 --- a/src/textual/widget.py +++ b/src/textual/widget.py @@ -2542,7 +2542,7 @@ def refresh( *regions: Region, repaint: bool = True, layout: bool = False, - ) -> None: + ) -> Self: """Initiate a refresh of the widget. This method sets an internal flag to perform a refresh, which will be done on the @@ -2558,8 +2558,11 @@ def refresh( Args: *regions: Additional screen regions to mark as dirty. - repaint: Repaint the widget (will call render() again). Defaults to True. - layout: Also layout widgets in the view. Defaults to False. + repaint: Repaint the widget (will call render() again). + layout: Also layout widgets in the view. + + Returns: + The `Widget` instance. """ if layout and not self._layout_required: self._layout_required = True @@ -2577,6 +2580,7 @@ def refresh( self._repaint_required = True self.check_idle() + return self def remove(self) -> AwaitRemove: """Remove the Widget from the DOM (effectively deleting it). @@ -2658,12 +2662,14 @@ def _check_refresh(self) -> None: self._layout_required = False screen.post_message(messages.Layout()) - def focus(self, scroll_visible: bool = True) -> None: + def focus(self, scroll_visible: bool = True) -> Self: """Give focus to this widget. Args: - scroll_visible: Scroll parent to make this widget - visible. Defaults to True. + scroll_visible: Scroll parent to make this widget visible. + + Returns: + The `Widget` instance. """ def set_focus(widget: Widget): @@ -2674,13 +2680,19 @@ def set_focus(widget: Widget): pass self.app.call_later(set_focus, self) + return self + + def reset_focus(self) -> Self: + """Reset the focus (move it to the next available widget). - def reset_focus(self) -> None: - """Reset the focus (move it to the next available widget).""" + Returns: + The `Widget` instance. + """ try: self.screen._reset_focus(self) except NoScreen: pass + return self def capture_mouse(self, capture: bool = True) -> None: """Capture (or release) the mouse. diff --git a/src/textual/widgets/_button.py b/src/textual/widgets/_button.py index 34a82a195c..dfa1867398 100644 --- a/src/textual/widgets/_button.py +++ b/src/textual/widgets/_button.py @@ -1,11 +1,10 @@ from __future__ import annotations from functools import partial -from typing import cast import rich.repr from rich.text import Text, TextType -from typing_extensions import Literal +from typing_extensions import Literal, Self from .. import events from ..css._error_tools import friendly_list @@ -233,14 +232,18 @@ async def _on_click(self, event: events.Click) -> None: event.stop() self.press() - def press(self) -> None: - """Respond to a button press.""" + def press(self) -> Self: + """Respond to a button press. + + Returns: + The button instance.""" if self.disabled or not self.display: - return + return self # Manage the "active" effect: self._start_active_affect() # ...and let other components know that we've just been clicked: self.post_message(Button.Pressed(self)) + return self def _start_active_affect(self) -> None: """Start a small animation to show the button was clicked.""" diff --git a/src/textual/widgets/_data_table.py b/src/textual/widgets/_data_table.py index 649e495e4b..4469f85a3a 100644 --- a/src/textual/widgets/_data_table.py +++ b/src/textual/widgets/_data_table.py @@ -13,7 +13,7 @@ from rich.segment import Segment from rich.style import Style from rich.text import Text, TextType -from typing_extensions import Literal, TypeAlias +from typing_extensions import Literal, Self, TypeAlias from .. import events from .._cache import LRUCache @@ -1156,11 +1156,14 @@ def _get_column_region(self, column_index: int) -> Region: full_column_region = Region(x, 0, width, height) return full_column_region - def clear(self, columns: bool = False) -> None: + def clear(self, columns: bool = False) -> Self: """Clear the table. Args: - columns: Also clear the columns. Defaults to False. + columns: Also clear the columns. + + Returns: + The `DataTable` instance. """ self._clear_caches() self._y_offsets.clear() @@ -1176,6 +1179,7 @@ def clear(self, columns: bool = False) -> None: self._label_column = Column(self._label_column_key, Text(), auto_width=True) self._labelled_row_exists = False self.refresh() + return self def add_column( self, label: TextType, *, width: int | None = None, key: str | None = None @@ -1333,49 +1337,66 @@ def on_idle(self) -> None: self._updated_cells.clear() self._update_column_widths(updated_columns) - def refresh_coordinate(self, coordinate: Coordinate) -> None: + def refresh_coordinate(self, coordinate: Coordinate) -> Self: """Refresh the cell at a coordinate. Args: coordinate: The coordinate to refresh. + + Returns: + The `DataTable` instance. """ if not self.is_valid_coordinate(coordinate): - return + return self region = self._get_cell_region(coordinate) self._refresh_region(region) + return self - def refresh_row(self, row_index: int) -> None: + def refresh_row(self, row_index: int) -> Self: """Refresh the row at the given index. Args: row_index: The index of the row to refresh. + + Returns: + The `DataTable` instance. """ if not self.is_valid_row_index(row_index): - return + return self region = self._get_row_region(row_index) self._refresh_region(region) + return self - def refresh_column(self, column_index: int) -> None: + def refresh_column(self, column_index: int) -> Self: """Refresh the column at the given index. Args: column_index: The index of the column to refresh. + + Returns: + The `DataTable` instance. """ if not self.is_valid_column_index(column_index): - return + return self region = self._get_column_region(column_index) self._refresh_region(region) + return self + + def _refresh_region(self, region: Region) -> Self: + """Refresh a region of the DataTable, if it's visible within the window. + + This method will translate the region to account for scrolling. - def _refresh_region(self, region: Region) -> None: - """Refresh a region of the DataTable, if it's visible within - the window. This method will translate the region to account - for scrolling.""" + Returns: + The `DataTable` instance. + """ if not self.window_region.overlaps(region): - return + return self region = region.translate(-self.scroll_offset) self.refresh(region) + return self def is_valid_row_index(self, row_index: int) -> bool: """Return a boolean indicating whether the row_index is within table bounds. @@ -1839,12 +1860,15 @@ def sort( self, *columns: ColumnKey | str, reverse: bool = False, - ) -> None: - """Sort the rows in the DataTable by one or more column keys. + ) -> Self: + """Sort the rows in the `DataTable` by one or more column keys. Args: columns: One or more columns to sort by the values in. reverse: If True, the sort order will be reversed. + + Returns: + The `DataTable` instance. """ def sort_by_column_keys( @@ -1862,6 +1886,7 @@ def sort_by_column_keys( ) self._update_count += 1 self.refresh() + return self def _scroll_cursor_into_view(self, animate: bool = False) -> None: """When the cursor is at a boundary of the DataTable and moves out diff --git a/src/textual/widgets/_placeholder.py b/src/textual/widgets/_placeholder.py index 81c877c99a..17b0614af4 100644 --- a/src/textual/widgets/_placeholder.py +++ b/src/textual/widgets/_placeholder.py @@ -5,7 +5,7 @@ from itertools import cycle from rich.console import RenderableType -from typing_extensions import Literal +from typing_extensions import Literal, Self from .. import events from ..css._error_tools import friendly_list @@ -132,9 +132,14 @@ def render(self) -> RenderableType: """ return self._renderables[self.variant] - def cycle_variant(self) -> None: - """Get the next variant in the cycle.""" + def cycle_variant(self) -> Self: + """Get the next variant in the cycle. + + Returns: + The `Placeholder` instance. + """ self.variant = next(self._variants_cycle) + return self def watch_variant( self, old_variant: PlaceholderVariant, variant: PlaceholderVariant diff --git a/src/textual/widgets/_switch.py b/src/textual/widgets/_switch.py index 3f9044df49..cf636b92ab 100644 --- a/src/textual/widgets/_switch.py +++ b/src/textual/widgets/_switch.py @@ -1,6 +1,6 @@ from __future__ import annotations -from typing import ClassVar +from typing import TYPE_CHECKING, ClassVar from rich.console import RenderableType @@ -11,6 +11,9 @@ from ..scrollbar import ScrollBarRender from ..widget import Widget +if TYPE_CHECKING: + from typing_extensions import Self + class Switch(Widget, can_focus=True): """A switch widget that represents a boolean value. @@ -158,10 +161,14 @@ def action_toggle(self) -> None: """Toggle the state of the switch.""" self.toggle() - def toggle(self) -> None: + def toggle(self) -> Self: """Toggle the switch value. As a result of the value changing, a `Switch.Changed` message will be posted. + + Returns: + The `Switch` instance. """ self.value = not self.value + return self diff --git a/src/textual/widgets/_tabs.py b/src/textual/widgets/_tabs.py index 1474975edc..3191b1e47c 100644 --- a/src/textual/widgets/_tabs.py +++ b/src/textual/widgets/_tabs.py @@ -1,6 +1,6 @@ from __future__ import annotations -from typing import ClassVar +from typing import TYPE_CHECKING, ClassVar import rich.repr from rich.style import Style @@ -18,6 +18,9 @@ from ..widget import Widget from ..widgets import Static +if TYPE_CHECKING: + from typing_extensions import Self + class Underline(Widget): """The animated underline beneath tabs.""" @@ -316,13 +319,18 @@ async def refresh_active() -> None: self.call_after_refresh(refresh_active) - def clear(self) -> None: - """Clear all the tabs.""" + def clear(self) -> Self: + """Clear all the tabs. + + Returns: + The `Tabs` instance. + """ underline = self.query_one(Underline) underline.highlight_start = 0 underline.highlight_end = 0 self.query("#tabs-list > Tab").remove() self.post_message(self.Cleared(self)) + return self def remove_tab(self, tab_or_id: Tab | str | None) -> None: """Remove a tab. diff --git a/src/textual/widgets/_text_log.py b/src/textual/widgets/_text_log.py index fa12226ea0..bcf0923546 100644 --- a/src/textual/widgets/_text_log.py +++ b/src/textual/widgets/_text_log.py @@ -2,7 +2,7 @@ from __future__ import annotations -from typing import Optional, cast +from typing import TYPE_CHECKING, Optional, cast from rich.console import RenderableType from rich.highlighter import ReprHighlighter @@ -18,6 +18,9 @@ from ..scroll_view import ScrollView from ..strip import Strip +if TYPE_CHECKING: + from typing_extensions import Self + class TextLog(ScrollView, can_focus=True): """A widget for logging text.""" @@ -89,7 +92,7 @@ def write( width: int | None = None, expand: bool = False, shrink: bool = True, - ) -> None: + ) -> Self: """Write text or a rich renderable. Args: @@ -97,6 +100,9 @@ def write( width: Width to render or ``None`` to use optimal width. expand: Enable expand to widget width, or ``False`` to use `width`. shrink: Enable shrinking of content to fit width. + + Returns: + The `TextLog` instance. """ renderable: RenderableType @@ -136,7 +142,7 @@ def write( ) lines = list(Segment.split_lines(segments)) if not lines: - return + return self self.max_width = max( self.max_width, @@ -154,14 +160,21 @@ def write( self.virtual_size = Size(self.max_width, len(self.lines)) self.scroll_end(animate=False) - def clear(self) -> None: - """Clear the text log.""" + return self + + def clear(self) -> Self: + """Clear the text log. + + Returns: + The `TextLog` instance. + """ self.lines.clear() self._line_cache.clear() self._start_line = 0 self.max_width = 0 self.virtual_size = Size(self.max_width, len(self.lines)) self.refresh() + return self def render_line(self, y: int) -> Strip: scroll_x, scroll_y = self.scroll_offset diff --git a/src/textual/widgets/_toggle_button.py b/src/textual/widgets/_toggle_button.py index 51efa137bc..a25b283e7a 100644 --- a/src/textual/widgets/_toggle_button.py +++ b/src/textual/widgets/_toggle_button.py @@ -5,7 +5,7 @@ from __future__ import annotations -from typing import ClassVar +from typing import TYPE_CHECKING, ClassVar from rich.style import Style from rich.text import Text, TextType @@ -17,6 +17,9 @@ from ..reactive import reactive from ._static import Static +if TYPE_CHECKING: + from typing_extensions import Self + class ToggleButton(Static, can_focus=True): """Base toggle button widget. @@ -201,9 +204,14 @@ def get_content_width(self, container: Size, viewport: Size) -> int: def get_content_height(self, container: Size, viewport: Size, width: int) -> int: return 1 - def toggle(self) -> None: - """Toggle the value of the widget.""" + def toggle(self) -> Self: + """Toggle the value of the widget. + + Returns: + The `ToggleButton` instance. + """ self.value = not self.value + return self def action_toggle(self) -> None: """Toggle the value of the widget when called as an action. diff --git a/src/textual/widgets/_tree.py b/src/textual/widgets/_tree.py index fb582dd796..db0d77cf7a 100644 --- a/src/textual/widgets/_tree.py +++ b/src/textual/widgets/_tree.py @@ -22,7 +22,7 @@ from ..strip import Strip if TYPE_CHECKING: - from typing_extensions import TypeAlias + from typing_extensions import Self, TypeAlias NodeID = NewType("NodeID", int) """The type of an ID applied to a [TreeNode][textual.widgets._tree.TreeNode].""" @@ -201,15 +201,25 @@ def _expand(self, expand_all: bool) -> None: for child in self.children: child._expand(expand_all) - def expand(self) -> None: - """Expand the node (show its children).""" + def expand(self) -> Self: + """Expand the node (show its children). + + Returns: + The `TreeNode` instance. + """ self._expand(False) self._tree._invalidate() + return self - def expand_all(self) -> None: - """Expand the node (show its children) and all those below it.""" + def expand_all(self) -> Self: + """Expand the node (show its children) and all those below it. + + Returns: + The `TreeNode` instance. + """ self._expand(True) self._tree._invalidate() + return self def _collapse(self, collapse_all: bool) -> None: """Mark the node as collapsed (its children are hidden). @@ -223,29 +233,49 @@ def _collapse(self, collapse_all: bool) -> None: for child in self.children: child._collapse(collapse_all) - def collapse(self) -> None: - """Collapse the node (hide its children).""" + def collapse(self) -> Self: + """Collapse the node (hide its children). + + Returns: + The `TreeNode` instance. + """ self._collapse(False) self._tree._invalidate() + return self - def collapse_all(self) -> None: - """Collapse the node (hide its children) and all those below it.""" + def collapse_all(self) -> Self: + """Collapse the node (hide its children) and all those below it. + + Returns: + The `TreeNode` instance. + """ self._collapse(True) self._tree._invalidate() + return self - def toggle(self) -> None: - """Toggle the node's expanded state.""" + def toggle(self) -> Self: + """Toggle the node's expanded state. + + Returns: + The `TreeNode` instance. + """ if self._expanded: self.collapse() else: self.expand() + return self - def toggle_all(self) -> None: - """Toggle the node's expanded state and make all those below it match.""" + def toggle_all(self) -> Self: + """Toggle the node's expanded state and make all those below it match. + + Returns: + The `TreeNode` instance. + """ if self._expanded: self.collapse_all() else: self.expand_all() + return self @property def label(self) -> TextType: @@ -597,8 +627,12 @@ def get_label_width(self, node: TreeNode[TreeDataType]) -> int: label = self.render_label(node, NULL_STYLE, NULL_STYLE) return label.cell_len - def clear(self) -> None: - """Clear all nodes under root.""" + def clear(self) -> Self: + """Clear all nodes under root. + + Returns: + The `Tree` instance. + """ self._line_cache.clear() self._tree_lines_cached = None self._current_id = 0 @@ -614,17 +648,22 @@ def clear(self) -> None: ) self._updates += 1 self.refresh() + return self - def reset(self, label: TextType, data: TreeDataType | None = None) -> None: + def reset(self, label: TextType, data: TreeDataType | None = None) -> Self: """Clear the tree and reset the root node. Args: label: The label for the root node. data: Optional data for the root node. + + Returns: + The `Tree` instance. """ self.clear() self.root.label = label self.root.data = data + return self def select_node(self, node: TreeNode[TreeDataType] | None) -> None: """Move the cursor to the given node, or reset cursor.