Merge branch 'main' into remove-freeze-fix

Author: willmcgugan

CHANGELOG.md

@@ -1,5 +1,6 @@
 # Change Log
 
+
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
@@ -27,12 +28,15 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Added `Widget.move_child` https://github.com/Textualize/textual/issues/1121
 - Added a `Label` widget https://github.com/Textualize/textual/issues/1190
 - Support lazy-instantiated Screens (callables in App.SCREENS) https://github.com/Textualize/textual/pull/1185
+- Display of keys in footer has more sensible defaults https://github.com/Textualize/textual/pull/1213
+- Add App.get_key_display, allowing custom key_display App-wide https://github.com/Textualize/textual/pull/1213
 
 ### Changed
 
 - Watchers are now called immediately when setting the attribute if they are synchronous. https://github.com/Textualize/textual/pull/1145
 - Widget.call_later has been renamed to Widget.call_after_refresh.
 - Button variant values are now checked at runtime. https://github.com/Textualize/textual/issues/1189
+- Added caching of some properties in Styles object
 
 ### Fixed
 

examples/five_by_five.py

@@ -311,7 +311,7 @@ class FiveByFive(App[None]):
     CSS_PATH = "five_by_five.css"
     """The name of the stylesheet for the app."""
 
-    SCREENS = {"help": Help()}
+    SCREENS = {"help": Help}
     """The pre-loaded screens for the application."""
 
     BINDINGS = [("ctrl+d", "toggle_dark", "Toggle Dark Mode")]

src/textual/app.py

@@ -57,13 +57,14 @@
 from .features import FeatureFlag, parse_features
 from .file_monitor import FileMonitor
 from .geometry import Offset, Region, Size
-from .keys import REPLACED_KEYS
+from .keys import REPLACED_KEYS, _get_key_display
 from .messages import CallbackType
 from .reactive import Reactive
 from .renderables.blank import Blank
 from .screen import Screen
 from .widget import AwaitMount, MountError, Widget
 
+
 if TYPE_CHECKING:
     from .devtools.client import DevtoolsClient
     from .pilot import Pilot
@@ -103,7 +104,6 @@
 ComposeResult = Iterable[Widget]
 RenderResult = RenderableType
 
-
 AutopilotCallbackType: TypeAlias = "Callable[[Pilot], Coroutine[Any, Any, None]]"
 
 
@@ -670,6 +670,22 @@ def bind(
             keys, action, description, show=show, key_display=key_display
         )
 
+    def get_key_display(self, key: str) -> str:
+        """For a given key, return how it should be displayed in an app
+        (e.g. in the Footer widget).
+        By key, we refer to the string used in the "key" argument for
+        a Binding instance. By overriding this method, you can ensure that
+        keys are displayed consistently throughout your app, without
+        needing to add a key_display to every binding.
+
+        Args:
+            key (str): The binding key string.
+
+        Returns:
+            str: The display string for the input key.
+        """
+        return _get_key_display(key)
+
     async def _press_keys(self, keys: Iterable[str]) -> None:
         """A task to send key events."""
         app = self
@@ -707,7 +723,7 @@ async def _press_keys(self, keys: Iterable[str]) -> None:
                 #  This conditional sleep can be removed after that issue is closed.
                 if key == "tab":
                     await asyncio.sleep(0.05)
-                await asyncio.sleep(0.02)
+                await asyncio.sleep(0.025)
         await app._animator.wait_for_idle()
 
     @asynccontextmanager

src/textual/css/styles.py

@@ -557,6 +557,7 @@ def _align_size(self, child: tuple[int, int], parent: tuple[int, int]) -> Offset
 class Styles(StylesBase):
     node: DOMNode | None = None
     _rules: RulesMap = field(default_factory=dict)
+    _updates: int = 0
 
     important: set[str] = field(default_factory=set)
 
@@ -577,6 +578,7 @@ def clear_rule(self, rule: str) -> bool:
         Returns:
             bool: ``True`` if a rule was cleared, or ``False`` if it was already not set.
         """
+        self._updates += 1
         return self._rules.pop(rule, None) is not None
 
     def get_rules(self) -> RulesMap:
@@ -592,6 +594,7 @@ def set_rule(self, rule: str, value: object | None) -> bool:
         Returns:
             bool: ``True`` if the rule changed, otherwise ``False``.
         """
+        self._updates += 1
         if value is None:
             return self._rules.pop(rule, None) is not None
         current = self._rules.get(rule)
@@ -610,6 +613,7 @@ def refresh(self, *, layout: bool = False, children: bool = False) -> None:
 
     def reset(self) -> None:
         """Reset the rules to initial state."""
+        self._updates += 1
         self._rules.clear()
 
     def merge(self, other: Styles) -> None:
@@ -618,10 +622,11 @@ def merge(self, other: Styles) -> None:
         Args:
             other (Styles): A Styles object.
         """
-
+        self._updates += 1
         self._rules.update(other._rules)
 
     def merge_rules(self, rules: RulesMap) -> None:
+        self._updates += 1
         self._rules.update(rules)
 
     def extract_rules(
@@ -929,6 +934,18 @@ def __init__(self, node: DOMNode, base: Styles, inline_styles: Styles) -> None:
         self._base_styles = base
         self._inline_styles = inline_styles
         self._animate: BoundAnimator | None = None
+        self._updates: int = 0
+        self._rich_style: tuple[int, Style] | None = None
+        self._gutter: tuple[int, Spacing] | None = None
+
+    @property
+    def _cache_key(self) -> int:
+        """A key key, that changes when any style is changed.
+
+        Returns:
+            int: An opaque integer.
+        """
+        return self._updates + self._base_styles._updates + self._inline_styles._updates
 
     @property
     def base(self) -> Styles:
@@ -946,6 +963,21 @@ def rich_style(self) -> Style:
         assert self.node is not None
         return self.node.rich_style
 
+    @property
+    def gutter(self) -> Spacing:
+        """Get space around widget.
+
+        Returns:
+            Spacing: Space around widget content.
+        """
+        if self._gutter is not None:
+            cache_key, gutter = self._gutter
+            if cache_key == self._updates:
+                return gutter
+        gutter = self.padding + self.border.spacing
+        self._gutter = (self._cache_key, gutter)
+        return gutter
+
     def animate(
         self,
         attribute: str,
@@ -972,6 +1004,7 @@ def animate(
 
         """
         if self._animate is None:
+            assert self.node is not None
             self._animate = self.node.app.animator.bind(self)
         assert self._animate is not None
         self._animate(
@@ -1003,16 +1036,19 @@ def merge(self, other: Styles) -> None:
 
     def merge_rules(self, rules: RulesMap) -> None:
         self._inline_styles.merge_rules(rules)
+        self._updates += 1
 
     def reset(self) -> None:
         """Reset the rules to initial state."""
         self._inline_styles.reset()
+        self._updates += 1
 
     def has_rule(self, rule: str) -> bool:
         """Check if a rule has been set."""
         return self._inline_styles.has_rule(rule) or self._base_styles.has_rule(rule)
 
     def set_rule(self, rule: str, value: object | None) -> bool:
+        self._updates += 1
         return self._inline_styles.set_rule(rule, value)
 
     def get_rule(self, rule: str, default: object = None) -> object:
@@ -1022,6 +1058,7 @@ def get_rule(self, rule: str, default: object = None) -> object:
 
     def clear_rule(self, rule_name: str) -> bool:
         """Clear a rule (from inline)."""
+        self._updates += 1
         return self._inline_styles.clear_rule(rule_name)
 
     def get_rules(self) -> RulesMap:

src/textual/keys.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import unicodedata
 from enum import Enum
 
 
@@ -219,7 +220,34 @@ class Keys(str, Enum):
     "ctrl+j": ["newline"],
 }
 
+KEY_DISPLAY_ALIASES = {
+    "up": "↑",
+    "down": "↓",
+    "left": "←",
+    "right": "→",
+    "backspace": "⌫",
+    "escape": "ESC",
+    "enter": "⏎",
+}
+
 
 def _get_key_aliases(key: str) -> list[str]:
     """Return all aliases for the given key, including the key itself"""
     return [key] + KEY_ALIASES.get(key, [])
+
+
+def _get_key_display(key: str) -> str:
+    """Given a key (i.e. the `key` string argument to Binding __init__),
+    return the value that should be displayed in the app when referring
+    to this key (e.g. in the Footer widget)."""
+    display_alias = KEY_DISPLAY_ALIASES.get(key)
+    if display_alias:
+        return display_alias
+
+    original_key = REPLACED_KEYS.get(key, key)
+    try:
+        unicode_character = unicodedata.lookup(original_key.upper().replace("_", " "))
+    except KeyError:
+        return original_key.upper()
+
+    return unicode_character

src/textual/reactive.py

@@ -43,7 +43,7 @@ class Reactive(Generic[ReactiveType]):
         layout (bool, optional): Perform a layout on change. Defaults to False.
         repaint (bool, optional): Perform a repaint on change. Defaults to True.
         init (bool, optional): Call watchers on initialize (post mount). Defaults to False.
-        always_update(bool, optional): Call watchers even when the new value equals the old value. Defaults to False.
+        always_update (bool, optional): Call watchers even when the new value equals the old value. Defaults to False.
     """
 
     def __init__(
@@ -76,7 +76,7 @@ def init(
             default (ReactiveType | Callable[[], ReactiveType]): A default value or callable that returns a default.
             layout (bool, optional): Perform a layout on change. Defaults to False.
             repaint (bool, optional): Perform a repaint on change. Defaults to True.
-            always_update(bool, optional): Call watchers even when the new value equals the old value. Defaults to False.
+            always_update (bool, optional): Call watchers even when the new value equals the old value. Defaults to False.
 
         Returns:
             Reactive: A Reactive instance which calls watchers or initialize.
@@ -292,7 +292,7 @@ class reactive(Reactive[ReactiveType]):
         layout (bool, optional): Perform a layout on change. Defaults to False.
         repaint (bool, optional): Perform a repaint on change. Defaults to True.
         init (bool, optional): Call watchers on initialize (post mount). Defaults to True.
-        always_update(bool, optional): Call watchers even when the new value equals the old value. Defaults to False.
+        always_update (bool, optional): Call watchers even when the new value equals the old value. Defaults to False.
     """
 
     def __init__(

src/textual/widgets/_footer.py

@@ -7,6 +7,7 @@
 from rich.text import Text
 
 from .. import events
+from ..keys import _get_key_display
 from ..reactive import Reactive, watch
 from ..widget import Widget
 
@@ -99,11 +100,12 @@ def make_key_text(self) -> Text:
 
         for action, bindings in action_to_bindings.items():
             binding = bindings[0]
-            key_display = (
-                binding.key.upper()
-                if binding.key_display is None
-                else binding.key_display
-            )
+            if binding.key_display is None:
+                key_display = self.app.get_key_display(binding.key)
+                if key_display is None:
+                    key_display = binding.key.upper()
+            else:
+                key_display = binding.key_display
             hovered = self.highlight_key == binding.key
             key_text = Text.assemble(
                 (f" {key_display} ", highlight_key_style if hovered else key_style),