v1: Replace Colors.BLACK{shade} with BLACK_{shade}, WHITE{shade} with WHITE_{shade} (#5752)

* Fix attribute setting in Observable class

Corrects logic in Observable to set attribute directly if it does not exist, preventing unnecessary value comparison and notification for new attributes.

* Refactor attribute setting in Observable class

Simplifies logic for setting attributes by removing redundant checks and directly handling cases where the attribute may not exist. This improves code clarity and maintains correct notification behavior.

* Fix attribute update order in Observable class

Moves attribute assignment before value comparison in Observable.__setattr__ to ensure correct notification behavior when attribute values change.

* Add deprecated color aliases to Colors enum

Introduced DeprecatedEnumMeta to support deprecated enum members and added deprecated color aliases to the Colors enum for backward compatibility. Deprecated aliases now emit a DeprecationWarning and redirect to the new member names. Also updated __all__ and imports to expose DeprecatedEnumMeta.

* Update color constants to new naming convention

Replaces deprecated color constants like BLACK54, WHITE24, etc. with their new underscore-named versions (e.g., BLACK_54, WHITE_24) across all example, tutorial, and documentation files for consistency with the latest Flet API.

* Add TODO for deprecated color aliases removal

Added a TODO comment indicating that deprecated color aliases should be removed in Flet 1.0. This helps track planned cleanup for future releases.

Author: FeodorFitsner

sdk/python/packages/flet-video/src/flet_video/types.py

@@ -189,7 +189,7 @@ class VideoSubtitleConfiguration:
             word_spacing=0.0,
             color=ft.Colors.WHITE,
             weight=ft.FontWeight.NORMAL,
-            bgcolor=ft.Colors.BLACK54,
+            bgcolor=ft.Colors.BLACK_54,
         )
     )
     """The text style to be used for the subtitles."""

sdk/python/packages/flet/docs/controls/submenubutton.md

@@ -1,7 +1,7 @@
 ---
 class_name: flet.SubmenuButton
 examples: ../../examples/controls/submenu_button
-example_images: ../test-images/examples/core/golden/macos/submenu_button
+example_images: ../test-images/examples/material/golden/macos/submenu_button
 ---
 
 {{ class_summary(class_name, example_images + "/image_for_docs.png", image_caption="Activated submenu button") }}

sdk/python/packages/flet/docs/cookbook/colors.md

@@ -82,8 +82,8 @@ Most palettes range from `50` to `900`, in increments of `100`, while **accent s
 (e.g., [`Colors.RED_ACCENT`][flet.Colors.RED_ACCENT]) have only `100`, `200`, `400`, and `700`.
 
 In addition to color swatches, Flet provides named black and white variants with built-in opacities, such as:
-- [`Colors.BLACK54`][flet.Colors.BLACK54] → black at 54% opacity
-- [`Colors.WHITE70`][flet.Colors.WHITE70] → white at 70% opacity
+- [`Colors.BLACK_54`][flet.Colors.BLACK_54] → black at 54% opacity
+- [`Colors.WHITE_70`][flet.Colors.WHITE_70] → white at 70% opacity
 
 These palette colors can be used:
 - directly as values for control color properties (e.g., `bgcolor`, `color`)

sdk/python/packages/flet/docs/cookbook/drag-and-drop.md

@@ -125,7 +125,7 @@ def main(page: ft.Page):
     def drag_will_accept(e):
         # black border when it's allowed to drop and red when it's not
         e.control.content.border = ft.border.all(
-            2, ft.Colors.BLACK45 if e.data == "true" else ft.Colors.RED
+            2, ft.Colors.BLACK_45 if e.data == "true" else ft.Colors.RED
         )
         e.control.update()
 

sdk/python/packages/flet/docs/tutorials/calculator.md

@@ -218,7 +218,7 @@ Now let's create child classes for all three types of buttons:
 class DigitButton(CalcButton):
     def __init__(self, text, expand=1):
         CalcButton.__init__(self, text, expand)
-        self.bgcolor = ft.Colors.WHITE24
+        self.bgcolor = ft.Colors.WHITE_24
         self.color = ft.Colors.WHITE
 
 class ActionButton(CalcButton):

sdk/python/packages/flet/docs/tutorials/chat.md

@@ -231,7 +231,7 @@ def on_message(message: Message):
         chat.controls.append(ft.Text(f"{message.user}: {message.text}"))
     elif message.message_type == "login_message":
         chat.controls.append(
-            ft.Text(message.text, italic=True, color=ft.Colors.BLACK45, size=12)
+            ft.Text(message.text, italic=True, color=ft.Colors.BLACK_45, size=12)
         )
     page.update()
 ```
@@ -365,7 +365,7 @@ Instances of `ChatMessage` will be created instead of plain `Text` chat messages
         if message.message_type == "chat_message":
             m = ChatMessage(message)
         elif message.message_type == "login_message":
-            m = ft.Text(message.text, italic=True, color=ft.Colors.BLACK45, size=12)
+            m = ft.Text(message.text, italic=True, color=ft.Colors.BLACK_45, size=12)
         chat.controls.append(m)
         page.update()
 ```

sdk/python/packages/flet/src/flet/components/observable.py

@@ -147,10 +147,9 @@ def __setattr__(self, name: str, value: Any):
             object.__setattr__(self, name, value)
             return
         value = self._wrap_if_collection(name, value)
-        had = hasattr(self, name)
-        old = object.__getattribute__(self, name) if had else None
+        old = object.__getattribute__(self, name) if hasattr(self, name) else None
+        object.__setattr__(self, name, value)
         if not value_equal(old, value):
-            object.__setattr__(self, name, value)
             self._notify(name)
 
     def __delattr__(self, name: str):

sdk/python/packages/flet/src/flet/controls/colors.py

@@ -55,13 +55,15 @@
 from enum import Enum
 from typing import TYPE_CHECKING, Optional, Union
 
+from flet.utils.deprecated_enum import DeprecatedEnumMeta
+
 if TYPE_CHECKING:
     from flet.controls.types import ColorValue
 
 __all__ = ["Colors"]
 
 
-class Colors(str, Enum):
+class Colors(str, Enum, metaclass=DeprecatedEnumMeta):
     def __eq__(self, other):
         if isinstance(other, str):
             return self.value.lower() == other.lower()
@@ -198,12 +200,12 @@ def with_opacity(opacity: Union[int, float], color: "ColorValue") -> str:
     AMBER_ACCENT_400 = "amberaccent400"
     AMBER_ACCENT_700 = "amberaccent700"
     BLACK = "black"
-    BLACK12 = "black12"
-    BLACK26 = "black26"
-    BLACK38 = "black38"
-    BLACK45 = "black45"
-    BLACK54 = "black54"
-    BLACK87 = "black87"
+    BLACK_12 = "black12"
+    BLACK_26 = "black26"
+    BLACK_38 = "black38"
+    BLACK_45 = "black45"
+    BLACK_54 = "black54"
+    BLACK_87 = "black87"
     BLUE = "blue"
     BLUE_100 = "blue100"
     BLUE_200 = "blue200"
@@ -463,14 +465,14 @@ def with_opacity(opacity: Union[int, float], color: "ColorValue") -> str:
     TEAL_ACCENT_700 = "tealaccent700"
     TRANSPARENT = "transparent"
     WHITE = "white"
-    WHITE10 = "white10"
-    WHITE12 = "white12"
-    WHITE24 = "white24"
-    WHITE30 = "white30"
-    WHITE38 = "white38"
-    WHITE54 = "white54"
-    WHITE60 = "white60"
-    WHITE70 = "white70"
+    WHITE_10 = "white10"
+    WHITE_12 = "white12"
+    WHITE_24 = "white24"
+    WHITE_30 = "white30"
+    WHITE_38 = "white38"
+    WHITE_54 = "white54"
+    WHITE_60 = "white60"
+    WHITE_70 = "white70"
     YELLOW = "yellow"
     YELLOW_100 = "yellow100"
     YELLOW_200 = "yellow200"
@@ -487,3 +489,27 @@ def with_opacity(opacity: Union[int, float], color: "ColorValue") -> str:
     YELLOW_ACCENT_200 = "yellowaccent200"
     YELLOW_ACCENT_400 = "yellowaccent400"
     YELLOW_ACCENT_700 = "yellowaccent700"
+
+
+# TODO - remove in Flet 1.0
+_DEPRECATED_COLOR_ALIASES = {
+    "BLACK12": ("BLACK_12", "Use Colors.BLACK_12 instead."),
+    "BLACK26": ("BLACK_26", "Use Colors.BLACK_26 instead."),
+    "BLACK38": ("BLACK_38", "Use Colors.BLACK_38 instead."),
+    "BLACK45": ("BLACK_45", "Use Colors.BLACK_45 instead."),
+    "BLACK54": ("BLACK_54", "Use Colors.BLACK_54 instead."),
+    "BLACK87": ("BLACK_87", "Use Colors.BLACK_87 instead."),
+    "WHITE10": ("WHITE_10", "Use Colors.WHITE_10 instead."),
+    "WHITE12": ("WHITE_12", "Use Colors.WHITE_12 instead."),
+    "WHITE24": ("WHITE_24", "Use Colors.WHITE_24 instead."),
+    "WHITE30": ("WHITE_30", "Use Colors.WHITE_30 instead."),
+    "WHITE38": ("WHITE_38", "Use Colors.WHITE_38 instead."),
+    "WHITE54": ("WHITE_54", "Use Colors.WHITE_54 instead."),
+    "WHITE60": ("WHITE_60", "Use Colors.WHITE_60 instead."),
+    "WHITE70": ("WHITE_70", "Use Colors.WHITE_70 instead."),
+}
+
+Colors._deprecated_members_ = _DEPRECATED_COLOR_ALIASES
+
+for alias_name, (target_name, _) in _DEPRECATED_COLOR_ALIASES.items():
+    Colors._member_map_[alias_name] = getattr(Colors, target_name)

sdk/python/packages/flet/src/flet/utils/__init__.py

@@ -1,6 +1,7 @@
 from flet.utils.browser import open_in_browser
 from flet.utils.classproperty import classproperty
 from flet.utils.deprecated import deprecated, deprecated_class, deprecated_warning
+from flet.utils.deprecated_enum import DeprecatedEnumMeta
 from flet.utils.files import (
     cleanup_path,
     copy_tree,
@@ -35,27 +36,23 @@
 from flet.utils.vector import Vector
 
 __all__ = [
-    "open_in_browser",
+    "DeprecatedEnumMeta",
+    "Once",
+    "Vector",
+    "calculate_file_hash",
     "classproperty",
+    "cleanup_path",
+    "copy_tree",
     "deprecated",
     "deprecated_class",
     "deprecated_warning",
-    "cleanup_path",
-    "copy_tree",
-    "get_current_script_dir",
-    "is_within_directory",
-    "safe_tar_extractall",
-    "which",
     "from_dict",
-    "calculate_file_hash",
-    "sha1",
-    "to_json",
-    "get_free_tcp_port",
-    "get_local_ip",
-    "Once",
-    "patch_dataclass",
     "get_arch",
     "get_bool_env_var",
+    "get_current_script_dir",
+    "get_free_tcp_port",
+    "get_local_ip",
+    "get_param_count",
     "get_platform",
     "is_android",
     "is_asyncio",
@@ -67,8 +64,13 @@
     "is_mobile",
     "is_pyodide",
     "is_windows",
-    "slugify",
+    "is_within_directory",
+    "open_in_browser",
+    "patch_dataclass",
     "random_string",
-    "Vector",
-    "get_param_count",
+    "safe_tar_extractall",
+    "sha1",
+    "slugify",
+    "to_json",
+    "which",
 ]

sdk/python/packages/flet/src/flet/utils/deprecated_enum.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import warnings
+from enum import EnumMeta
+
+__all__ = ["DeprecatedEnumMeta"]
+
+
+class DeprecatedEnumMeta(EnumMeta):
+    """Enum metaclass that supports deprecation aliases.
+
+    Enums can declare `_deprecated_members_` as a mapping of alias name to a tuple
+    containing the canonical member name and a deprecation message. Accessing an alias
+    returns the canonical member while emitting a `DeprecationWarning`.
+    """
+
+    def _resolve_deprecated(cls, name: str):
+        deprecated = getattr(cls, "_deprecated_members_", {})
+        info = deprecated.get(name)
+        if not info:
+            return None
+        target_name, message = info
+        warnings.warn(
+            f"{cls.__name__}.{name} is deprecated. {message}",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return getattr(cls, target_name)
+
+    def __getattr__(cls, name: str):
+        member = cls._resolve_deprecated(name)
+        if member is not None:
+            return member
+        return super().__getattr__(name)
+
+    def __getitem__(cls, name: str):
+        member = cls._resolve_deprecated(name)
+        if member is not None:
+            return member
+        return super().__getitem__(name)