Remove value parameter from style's apply() method (#3159)

Simplifies the prototype of the `apply()` method on a style so that the value doesn't need to be passed in explicitly.

changes/3159.removal.rst

@@ -0,0 +1 @@
+The signature of the ``apply`` method of ``BaseStyle`` (and thus ``Pack``) has changed. Rather than taking a property name and value, it now takes only the name, and the style object checks its own current value for that property to know what to apply. This method is normally used internally, but any user code calling it manually will get a ``DeprecationWarning`` if it supplies two arguments.

core/src/toga/app.py

@@ -919,7 +919,7 @@ def add_background_task(self, handler: BackgroundTask) -> None:
         self.loop.call_soon_threadsafe(wrapped_handler(self, handler))
 
     ######################################################################
-    # 2024-12: Backwards compatibility for <= 0.4.8
+    # 2024-12: Backwards compatibility for < 0.5.0
     ######################################################################
 
     def exit_full_screen(self) -> None:

core/src/toga/style/applicator.py

@@ -14,7 +14,7 @@ class TogaApplicator:
     """Apply styles to a Toga widget."""
 
     ######################################################################
-    # 2024-12: Backwards compatibility for <= 0.4.8
+    # 2024-12: Backwards compatibility for < 0.5.0
     ######################################################################
 
     def __init__(self, widget: None = None):

core/src/toga/style/pack.py

@@ -51,6 +51,8 @@
 # Make sure deprecation warnings are shown by default
 warnings.filterwarnings("default", category=DeprecationWarning)
 
+NOT_PROVIDED = object()
+
 PACK = "pack"
 
 # Used in backwards compatibility section below
@@ -115,7 +117,7 @@ def _hidden(self) -> bool:
         return self.visibility == HIDDEN
 
     ######################################################################
-    # 2024-12: Backwards compatibility for Toga <= 0.4.8
+    # 2024-12: Backwards compatibility for Toga < 0.5.0
     ######################################################################
 
     def update(self, **properties):
@@ -259,23 +261,44 @@ def __delitem__(self, name):
     # End backwards compatibility
     ######################################################################
 
-    def apply(self, prop: str, value: object) -> None:
+    def apply(self, name: str, value: object = NOT_PROVIDED) -> None:
+        ######################################################################
+        # 2025-02: Backwards compatibility for Toga < 0.5.0
+        ######################################################################
+
+        if value is not NOT_PROVIDED:
+            warnings.warn(
+                (
+                    "The value parameter to Pack.apply() is deprecated. The instance "
+                    "will use its own current value for the property named."
+                ),
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+        ######################################################################
+        # End backwards compatibility
+        ######################################################################
+
         if self._applicator:
-            if prop == "text_align":
-                if value is None:
+            if name == "text_align":
+                if (value := self.text_align) is None:
                     if self.text_direction == RTL:
                         value = RIGHT
                     else:
                         value = LEFT
                 self._applicator.set_text_align(value)
-            elif prop == "text_direction":
+            elif name == "text_direction":
                 if self.text_align is None:
-                    self._applicator.set_text_align(RIGHT if value == RTL else LEFT)
-            elif prop == "color":
-                self._applicator.set_color(value)
-            elif prop == "background_color":
-                self._applicator.set_background_color(value)
-            elif prop == "visibility":
+                    self._applicator.set_text_align(
+                        RIGHT if self.text_direction == RTL else LEFT
+                    )
+            elif name == "color":
+                self._applicator.set_color(self.color)
+            elif name == "background_color":
+                self._applicator.set_background_color(self.background_color)
+            elif name == "visibility":
+                value = self.visibility
                 if value == VISIBLE:
                     # If visibility is being set to VISIBLE, look up the chain to see if
                     # an ancestor is hidden.
@@ -286,7 +309,7 @@ def apply(self, prop: str, value: object) -> None:
                             break
 
                 self._applicator.set_hidden(value == HIDDEN)
-            elif prop in (
+            elif name in (
                 "font_family",
                 "font_size",
                 "font_style",

core/src/toga/widgets/base.py

@@ -52,9 +52,9 @@ def __init__(
         # Get factory and assign implementation
         self.factory = get_platform_factory()
 
-        ####################################################
-        # 2024-12: Backwards compatibility for Toga <= 0.4.8
-        ####################################################
+        ##################################################################
+        # 2024-12: Backwards compatibility for Toga < 0.5.0
+        ##################################################################
 
         # Just in case we're working with a third-party widget created before
         # the _create() mechanism was added, which has already defined its

core/src/toga/window.py

@@ -858,7 +858,7 @@ def select_folder_dialog(
     ######################################################################
 
     ######################################################################
-    # 2024-10: Backwards compatibility for <= 0.4.8
+    # 2024-10: Backwards compatibility for < 0.5.0
     ######################################################################
     @property
     def full_screen(self) -> bool:

core/tests/style/pack/test_apply.py

@@ -1,12 +1,15 @@
 from unittest.mock import call
 
+import pytest
+
 from toga.colors import rgb
 from toga.fonts import Font
 from toga.style.pack import (
     CENTER,
     HIDDEN,
     LEFT,
     RIGHT,
+    ROW,
     RTL,
     VISIBLE,
     Pack,
@@ -118,3 +121,10 @@ def assert_hidden_called(grandparent_value, parent_value, child_value):
     # Show grandparent again; the other two should reappear.
     grandparent.style.visibility = VISIBLE
     assert_hidden_called(False, False, False)
+
+
+def test_apply_deprecated_signature():
+    """Calling apply() with a second argument raises a DeprecationWarning."""
+    style = Pack()
+    with pytest.warns(DeprecationWarning):
+        style.apply("direction", ROW)

travertino/src/travertino/declaration.py

@@ -160,19 +160,19 @@ def __set__(self, obj, value):
             # to the initial value.
             setattr(obj, f"_{self.name}", value)
             if value != self.initial:
-                obj.apply(self.name, value)
+                obj.apply(self.name)
 
         elif value != current:
             setattr(obj, f"_{self.name}", value)
-            obj.apply(self.name, value)
+            obj.apply(self.name)
 
     def __delete__(self, obj):
         try:
             delattr(obj, f"_{self.name}")
         except AttributeError:
             pass
         else:
-            obj.apply(self.name, self.initial)
+            obj.apply(self.name)
 
     @property
     def _name_if_set(self):
@@ -332,7 +332,7 @@ def _applicator(self, value):
 
     def reapply(self):
         for name in self._PROPERTIES:
-            self.apply(name, self[name])
+            self.apply(name)
 
     def copy(self, applicator=None):
         """Create a duplicate of this style declaration."""
@@ -362,7 +362,7 @@ def copy(self, applicator=None):
     # Interface that style declarations must define
     ######################################################################
 
-    def apply(self, property, value):
+    def apply(self, name):
         raise NotImplementedError(
             "Style must define an apply method"
         )  # pragma: no cover

travertino/tests/test_choices.py

@@ -66,7 +66,7 @@ class DeprecatedStyle(BaseStyle):
 def assert_property(obj, name, value):
     assert getattr(obj, name) == value
 
-    obj.apply.assert_called_once_with(name, value)
+    obj.apply.assert_called_once_with(name)
     obj.apply.reset_mock()