Add support for env variable TEXTUAL_ANIMATIONS

CHANGELOG.md

@@ -21,6 +21,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Added `Query.blur` and `Query.focus` https://github.com/Textualize/textual/pull/4012
 - Added `MessagePump.message_queue_size` https://github.com/Textualize/textual/pull/4012
 - Added `TabbedContent.active_pane` https://github.com/Textualize/textual/pull/4012
+- Added support for environment variable `TEXTUAL_ANIMATIONS` to control what animations Textual displays https://github.com/Textualize/textual/pull/4062
+- Add attribute `App.show_animations` to control whether animations on that app run or not https://github.com/Textualize/textual/pull/4062
 
 ### Fixed
 

docs/api/constants.md

@@ -0,0 +1 @@
+::: textuals.constants

mkdocs-nav.yml

@@ -178,6 +178,7 @@ nav:
       - "api/cache.md"
       - "api/color.md"
       - "api/command.md"
+      - "api/constants.md"
       - "api/containers.md"
       - "api/content_switcher.md"
       - "api/coordinate.md"

src/textual/_animator.py

@@ -10,8 +10,10 @@
 
 from . import _time
 from ._callback import invoke
+from ._context import active_app
 from ._easing import DEFAULT_EASING, EASING
 from ._types import CallbackType
+from .constants import AnimationsEnum
 from .timer import Timer
 
 if TYPE_CHECKING:
@@ -93,9 +95,19 @@ class SimpleAnimation(Animation):
     final_value: object
     easing: EasingFunction
     on_complete: CallbackType | None = None
+    animate_on_level: AnimationsEnum = AnimationsEnum.BASIC
+    """Minimum level required for the animation to take place (inclusive)."""
+
+    def __post_init__(self) -> None:
+        """Cache baseline that determines whether an animation runs."""
+        # We cache this value so we don't have to `.get` the context var repeatedly.
+        self.show_animations = active_app.get().show_animations
 
     def __call__(self, time: float) -> bool:
-        if self.duration == 0:
+        if (
+            self.duration == 0
+            or self.animate_on_level.value > self.show_animations.value
+        ):
             setattr(self.obj, self.attribute, self.final_value)
             return True
 
@@ -170,6 +182,7 @@ def __call__(
         delay: float = 0.0,
         easing: EasingFunction | str = DEFAULT_EASING,
         on_complete: CallbackType | None = None,
+        animate_on_level: AnimationsEnum = AnimationsEnum.FULL,
     ) -> None:
         """Animate an attribute.
 
@@ -182,6 +195,7 @@ def __call__(
             delay: A delay (in seconds) before the animation starts.
             easing: An easing method.
             on_complete: A callable to invoke when the animation is finished.
+            animate_on_level: Minimum level required for the animation to take place (inclusive).
         """
         start_value = getattr(self._obj, attribute)
         if isinstance(value, str) and hasattr(start_value, "parse"):
@@ -200,6 +214,7 @@ def __call__(
             delay=delay,
             easing=easing_function,
             on_complete=on_complete,
+            animate_on_level=animate_on_level,
         )
 
 
@@ -284,6 +299,7 @@ def animate(
         easing: EasingFunction | str = DEFAULT_EASING,
         delay: float = 0.0,
         on_complete: CallbackType | None = None,
+        animate_on_level: AnimationsEnum = AnimationsEnum.FULL,
     ) -> None:
         """Animate an attribute to a new value.
 
@@ -297,6 +313,7 @@ def animate(
             easing: An easing function.
             delay: Number of seconds to delay the start of the animation by.
             on_complete: Callback to run after the animation completes.
+            animate_on_level: Minimum level required for the animation to take place (inclusive).
         """
         animate_callback = partial(
             self._animate,
@@ -308,6 +325,7 @@ def animate(
             speed=speed,
             easing=easing,
             on_complete=on_complete,
+            animate_on_level=animate_on_level,
         )
         if delay:
             self._complete_event.clear()
@@ -328,7 +346,8 @@ def _animate(
         speed: float | None = None,
         easing: EasingFunction | str = DEFAULT_EASING,
         on_complete: CallbackType | None = None,
-    ):
+        animate_on_level: AnimationsEnum = AnimationsEnum.FULL,
+    ) -> None:
         """Animate an attribute to a new value.
 
         Args:
@@ -340,6 +359,7 @@ def _animate(
             speed: The speed of the animation.
             easing: An easing function.
             on_complete: Callback to run after the animation completes.
+            animate_on_level: Minimum level required for the animation to take place (inclusive).
         """
         if not hasattr(obj, attribute):
             raise AttributeError(
@@ -373,6 +393,7 @@ def _animate(
                 speed=speed,
                 easing=easing_function,
                 on_complete=on_complete,
+                animate_on_level=animate_on_level,
             )
 
         if animation is None:
@@ -410,6 +431,7 @@ def _animate(
                 final_value=final_value,
                 easing=easing_function,
                 on_complete=on_complete,
+                animate_on_level=animate_on_level,
             )
         assert animation is not None, "animation expected to be non-None"
 

src/textual/_context.py

@@ -14,12 +14,14 @@ class NoActiveAppError(RuntimeError):
     """Runtime error raised if we try to retrieve the active app when there is none."""
 
 
-active_app: ContextVar["App"] = ContextVar("active_app")
+active_app: ContextVar["App[object]"] = ContextVar("active_app")
 active_message_pump: ContextVar["MessagePump"] = ContextVar("active_message_pump")
 prevent_message_types_stack: ContextVar[list[set[type[Message]]]] = ContextVar(
     "prevent_message_types_stack"
 )
-visible_screen_stack: ContextVar[list[Screen]] = ContextVar("visible_screen_stack")
+visible_screen_stack: ContextVar[list[Screen[object]]] = ContextVar(
+    "visible_screen_stack"
+)
 """A stack of visible screens (with background alpha < 1), used in the screen render process."""
 message_hook: ContextVar[Callable[[Message], None]] = ContextVar("message_hook")
 """A callable that accepts a message. Used by App.run_test."""

src/textual/app.py

@@ -72,6 +72,7 @@
 from .await_remove import AwaitRemove
 from .binding import Binding, BindingType, _Bindings
 from .command import CommandPalette, Provider
+from .constants import AnimationsEnum
 from .css.query import NoMatches
 from .css.stylesheet import RulesMap, Stylesheet
 from .design import ColorSystem
@@ -575,6 +576,12 @@ def __init__(
         self.set_class(self.dark, "-dark-mode")
         self.set_class(not self.dark, "-light-mode")
 
+        self.show_animations: AnimationsEnum = constants._get_textual_animations()
+        """Determines what type of animations the app will display.
+
+        See [`textual.constants.SHOW_ANIMATIONS`][textual.constants.SHOW_ANIMATIONS].
+        """
+
     def validate_title(self, title: Any) -> str:
         """Make sure the title is set to a string."""
         return str(title)
@@ -670,6 +677,7 @@ def animate(
         delay: float = 0.0,
         easing: EasingFunction | str = DEFAULT_EASING,
         on_complete: CallbackType | None = None,
+        animate_on_level: AnimationsEnum = AnimationsEnum.FULL,
     ) -> None:
         """Animate an attribute.
 
@@ -684,6 +692,7 @@ def animate(
             delay: A delay (in seconds) before the animation starts.
             easing: An easing method.
             on_complete: A callable to invoke when the animation is finished.
+            animate_on_level: Minimum level required for the animation to take place (inclusive).
         """
         self._animate(
             attribute,
@@ -694,6 +703,7 @@ def animate(
             delay=delay,
             easing=easing,
             on_complete=on_complete,
+            animate_on_level=animate_on_level,
         )
 
     async def stop_animation(self, attribute: str, complete: bool = True) -> None:

src/textual/constants.py

@@ -4,14 +4,31 @@
 
 from __future__ import annotations
 
+import enum
 import os
 
 from typing_extensions import Final
 
 get_environ = os.environ.get
 
 
-def get_environ_bool(name: str) -> bool:
+class AnimationsEnum(enum.Enum):
+    """Valid values for the environment variable `TEXTUAL_ANIMATIONS`.
+
+    - `NONE` disables all animations.
+    - `BASIC` will only display animations that don't delay content appearing
+    (e.g., scrolling).
+    - `FULL` displays all animations.
+
+    See also: [`App.show_animations`][textual.app.App.show_animations].
+    """
+
+    NONE = 0
+    BASIC = 1
+    FULL = 2
+
+
+def _get_environ_bool(name: str) -> bool:
     """Check an environment variable switch.
 
     Args:
@@ -24,7 +41,7 @@ def get_environ_bool(name: str) -> bool:
     return has_environ
 
 
-def get_environ_int(name: str, default: int) -> int:
+def _get_environ_int(name: str, default: int) -> int:
     """Retrieves an integer environment variable.
 
     Args:
@@ -44,7 +61,21 @@ def get_environ_int(name: str, default: int) -> int:
         return default
 
 
-DEBUG: Final[bool] = get_environ_bool("TEXTUAL_DEBUG")
+def _get_textual_animations() -> AnimationsEnum:
+    """Get the value of the environment variable that controls textual animations.
+
+    The variable can be in any of the values defined by [`AnimationsEnum`][textual.constants.AnimationsEnum].
+
+    Returns:
+        The value that the variable was set to. If the environment variable is set to an
+            invalid value, we default to showing all animations.
+    """
+    value: str = get_environ("TEXTUAL_ANIMATIONS", "FULL")
+    enum_value = AnimationsEnum.__members__.get(value, AnimationsEnum.FULL)
+    return enum_value
+
+
+DEBUG: Final[bool] = _get_environ_bool("TEXTUAL_DEBUG")
 """Enable debug mode."""
 
 DRIVER: Final[str | None] = get_environ("TEXTUAL_DRIVER", None)
@@ -59,19 +90,19 @@ def get_environ_int(name: str, default: int) -> int:
 DEVTOOLS_HOST: Final[str] = get_environ("TEXTUAL_DEVTOOLS_HOST", "127.0.0.1")
 """The host where textual console is running."""
 
-DEVTOOLS_PORT: Final[int] = get_environ_int("TEXTUAL_DEVTOOLS_PORT", 8081)
+DEVTOOLS_PORT: Final[int] = _get_environ_int("TEXTUAL_DEVTOOLS_PORT", 8081)
 """Constant with the port that the devtools will connect to."""
 
-SCREENSHOT_DELAY: Final[int] = get_environ_int("TEXTUAL_SCREENSHOT", -1)
+SCREENSHOT_DELAY: Final[int] = _get_environ_int("TEXTUAL_SCREENSHOT", -1)
 """Seconds delay before taking screenshot."""
 
 PRESS: Final[str] = get_environ("TEXTUAL_PRESS", "")
 """Keys to automatically press."""
 
-SHOW_RETURN: Final[bool] = get_environ_bool("TEXTUAL_SHOW_RETURN")
+SHOW_RETURN: Final[bool] = _get_environ_bool("TEXTUAL_SHOW_RETURN")
 """Write the return value on exit."""
 
-MAX_FPS: Final[int] = get_environ_int("TEXTUAL_FPS", 60)
+MAX_FPS: Final[int] = _get_environ_int("TEXTUAL_FPS", 60)
 """Maximum frames per second for updates."""
 
 COLOR_SYSTEM: Final[str | None] = get_environ("TEXTUAL_COLOR_SYSTEM", "auto")

src/textual/css/scalar_animation.py

@@ -3,7 +3,9 @@
 from typing import TYPE_CHECKING
 
 from .._animator import Animation, EasingFunction
+from .._context import active_app
 from .._types import CallbackType
+from ..constants import AnimationsEnum
 from .scalar import Scalar, ScalarOffset
 
 if TYPE_CHECKING:
@@ -23,6 +25,7 @@ def __init__(
         speed: float | None,
         easing: EasingFunction,
         on_complete: CallbackType | None = None,
+        animate_on_level: AnimationsEnum = AnimationsEnum.FULL,
     ):
         assert (
             speed is not None or duration is not None
@@ -34,6 +37,7 @@ def __init__(
         self.final_value = value
         self.easing = easing
         self.on_complete = on_complete
+        self.animate_on_level = animate_on_level
 
         size = widget.outer_size
         viewport = widget.app.size
@@ -48,11 +52,21 @@ def __init__(
             assert duration is not None, "Duration expected to be non-None"
             self.duration = duration
 
+        self.show_animations = active_app.get().show_animations
+        """Cached version of [`App.show_animations`][textual.app.App.show_animations].
+
+        Caching this avoids repeatedly getting the context variable when the animation
+        is supposed to play.
+        """
+
     def __call__(self, time: float) -> bool:
         factor = min(1.0, (time - self.start_time) / self.duration)
         eased_factor = self.easing(factor)
 
-        if eased_factor >= 1:
+        if (
+            eased_factor >= 1
+            or self.animate_on_level.value > self.show_animations.value
+        ):
             setattr(self.styles, self.attribute, self.final_value)
             return True
 

src/textual/css/styles.py

@@ -13,6 +13,7 @@
 from .._animator import DEFAULT_EASING, Animatable, BoundAnimator, EasingFunction
 from .._types import CallbackType
 from ..color import Color
+from ..constants import AnimationsEnum
 from ..geometry import Offset, Spacing
 from ._style_properties import (
     AlignProperty,
@@ -369,6 +370,7 @@ def __textual_animation__(
         speed: float | None,
         easing: EasingFunction,
         on_complete: CallbackType | None = None,
+        animate_on_level: AnimationsEnum = AnimationsEnum.FULL,
     ) -> ScalarAnimation | None:
         if self.node is None:
             return None
@@ -396,6 +398,7 @@ def __textual_animation__(
                 speed=speed,
                 easing=easing,
                 on_complete=on_complete,
+                animate_on_level=animate_on_level,
             )
         return None
 
@@ -1138,6 +1141,7 @@ def animate(
         delay: float = 0.0,
         easing: EasingFunction | str = DEFAULT_EASING,
         on_complete: CallbackType | None = None,
+        animate_on_level: AnimationsEnum = AnimationsEnum.FULL,
     ) -> None:
         """Animate an attribute.
 
@@ -1150,6 +1154,7 @@ def animate(
             delay: A delay (in seconds) before the animation starts.
             easing: An easing method.
             on_complete: A callable to invoke when the animation is finished.
+            animate_on_level: Minimum level required for the animation to take place (inclusive).
         """
         if self._animate is None:
             assert self.node is not None
@@ -1164,6 +1169,7 @@ def animate(
             delay=delay,
             easing=easing,
             on_complete=on_complete,
+            animate_on_level=animate_on_level,
         )
 
     def __rich_repr__(self) -> rich.repr.Result: