v1: Move UpdateBehavior methods to ft.context, rename DataView decorator to cache (#5570)

* Refactor auto update control to context API

Replaces usage of UpdateBehavior with a new context API for managing auto update state across the codebase. Updates examples, main app logic, and event handling to use ft.context methods. Removes UpdateBehavior from public API and documentation, adds integration tests for auto update behavior, and updates documentation and navigation to reflect the new context API.

* Add docstrings and improve type hints in Context class

Added detailed docstrings to Context class methods for better clarity and documentation. Improved type hints and assertions, including stricter return type for page property and assertion to ensure context is associated with a page.

* Replace data_view decorator with cache decorator

Renamed and enhanced the data_view decorator to cache, adding a freeze option for control freezing. Updated imports, __all__, and all usages in tests to use the new cache decorator.

* Add type annotations and overloads to cache decorator

Introduces ParamSpec and TypeVar for improved type safety in the cache decorator. Adds overloads to the cache function and updates argument and return type annotations for better compatibility with type checkers.

* Add context exception test and update autoupdate app

Added assertions for ft.context.page in autoupdate.py to ensure context is associated with a page. Renamed test_autoupdate.py to test_context.py and added a test to verify that accessing ft.context.page outside of a Flet app raises an exception.

* Refactor Context docs and API exposure

Updated documentation for the Context class with usage examples and improved docstrings. Exposed Context in the public API via __init__.py and reorganized mkdocs navigation to move Context under Utility. Minor code reordering for clarity.

* Copilot fix: Add docs to UpdateBehavior class

Co-authored-by: Copilot <[email protected]>

* Delete update_behavior.py

* Add context usage examples and update docs

Added example scripts for disabling auto update and accessing page via context. Updated documentation to include new examples and improved references to ft.context. Renamed window_width and window_height to web_popup_window_width and web_popup_window_height in Page class for clarity.

* Add decorators docs and refactor control decorator

Added documentation for 'cache' and 'control' decorators. Updated mkdocs navigation to include new decorator docs. Refactored the 'control' decorator in base_control.py to rename 'cls_or_type_name' to 'dart_widget_name' and improved docstring for clarity. Renamed test functions in test_object_diff_frozen.py for consistency.

* Add cache decorator example and improve docs

Introduces a basic example for the cache decorator in Flet, updates documentation to include usage and example, and refines the cache decorator implementation with improved comments and docstring. Also fixes a minor docstring typo in base_control.py.

* Update control decorator docstring for clarity

Improved the docstring for the control decorator by clarifying references to @DataClass and its keyword arguments, and enhancing formatting for better readability.

---------

Co-authored-by: Copilot <[email protected]>

Author: FeodorFitsner

sdk/python/examples/apps/controls-gallery/main.py

@@ -1,15 +1,16 @@
 import logging
 
-import flet as ft
-import flet.version
 from components.gallery_view import GalleryView
 from gallerydata import GalleryData
 
+import flet as ft
+import flet.version
+
 gallery = GalleryData()
 
 logging.basicConfig(level=logging.DEBUG)
 
-# ft.UpdateBehavior.disable_auto_update()
+ft.context.disable_auto_update()
 
 
 def main(page: ft.Page):

sdk/python/examples/apps/counter/counter.py

@@ -1,5 +1,7 @@
 import flet as ft
 
+ft.context.disable_auto_update()
+
 
 def main(page: ft.Page):
     page.title = "Flet counter example"

sdk/python/examples/controls/canvas/brush.py

@@ -27,7 +27,7 @@ def handle_pan_start(e: ft.DragStartEvent):
         state.y = e.local_position.y
 
     async def handle_pan_update(e: ft.DragUpdateEvent):
-        ft.UpdateBehavior.disable_auto_update()
+        ft.context.disable_auto_update()
         canvas.shapes.append(
             cv.Line(
                 x1=state.x,

sdk/python/examples/controls/decorators/cache/basic.py

@@ -0,0 +1,50 @@
+import logging
+from dataclasses import dataclass, field
+
+import flet as ft
+
+logging.basicConfig(level=logging.DEBUG)
+
+
+@dataclass
+class AppState:
+    number: int = 0
+    items: list[int] = field(default_factory=list)
+
+    def __post_init__(self):
+        for _ in range(10):
+            self.add_item()
+
+    def add_item(self):
+        self.items.append(self.number)
+        self.number += 1
+
+
+@ft.cache
+def item_view(i: int):
+    return ft.Container(
+        ft.Text(f"Item {i}"),
+        padding=10,
+        bgcolor=ft.Colors.AMBER_100,
+        key=i,
+    )
+
+
+def main(page: ft.Page):
+    state = AppState()
+
+    page.floating_action_button = ft.FloatingActionButton(
+        icon=ft.Icons.ADD, on_click=state.add_item
+    )
+    page.add(
+        ft.ControlBuilder(
+            state,
+            lambda state: ft.SafeArea(
+                ft.Row([item_view(i) for i in state.items], wrap=True)
+            ),
+            expand=True,
+        )
+    )
+
+
+ft.run(main)

sdk/python/examples/controls/types/context/disable_auto_update.py

@@ -0,0 +1,18 @@
+import flet as ft
+
+
+def main(page: ft.Page):
+    def button_click():
+        ft.context.disable_auto_update()
+        b.content = "Button clicked!"
+        # update just the button
+        b.update()
+
+        page.controls.append(ft.Text("This won't appear"))
+        # no page.update() will be called here
+
+    page.controls.append(b := ft.Button("Action!", on_click=button_click))
+    # page.update() - auto-update is enabled by default
+
+
+ft.run(main)

sdk/python/examples/controls/types/context/get_page.py

@@ -0,0 +1,11 @@
+import flet as ft
+
+
+def main(page: ft.Page):
+    def button_click(e):
+        print("Page width:", ft.context.page.width)
+
+    page.add(ft.Button("Get page width", on_click=button_click))
+
+
+ft.run(main)

sdk/python/packages/flet-web/src/flet_web/fastapi/flet_app.py

@@ -10,10 +10,11 @@
 
 import msgpack
 from fastapi import WebSocket, WebSocketDisconnect
+
+import flet_web.fastapi as flet_fastapi
 from flet.controls.base_control import BaseControl
-from flet.controls.context import _context_page
+from flet.controls.context import _context_page, context
 from flet.controls.exceptions import FletPageDisconnectedException
-from flet.controls.update_behavior import UpdateBehavior
 from flet.messaging.connection import Connection
 from flet.messaging.protocol import (
     ClientAction,
@@ -28,8 +29,6 @@
 )
 from flet.messaging.session import Session
 from flet.utils import random_string, sha1
-
-import flet_web.fastapi as flet_fastapi
 from flet_web.fastapi.flet_app_manager import app_manager
 from flet_web.fastapi.oauth_state import OAuthState
 from flet_web.uploads import build_upload_url
@@ -140,24 +139,24 @@ async def __on_session_created(self):
         try:
             assert self.__main is not None
             _context_page.set(self.__session.page)
-            UpdateBehavior.reset()
+            context.reset_auto_update()
 
             if asyncio.iscoroutinefunction(self.__main):
                 await self.__main(self.__session.page)
 
             elif inspect.isasyncgenfunction(self.__main):
                 async for _ in self.__main(self.__session.page):
-                    if UpdateBehavior.auto_update_enabled():
+                    if context.auto_update_enabled():
                         await self.__session.auto_update(self.__session.page)
 
             elif inspect.isgeneratorfunction(self.__main):
                 for _ in self.__main(self.__session.page):
-                    if UpdateBehavior.auto_update_enabled():
+                    if context.auto_update_enabled():
                         await self.__session.auto_update(self.__session.page)
             else:
                 self.__main(self.__session.page)
 
-            if UpdateBehavior.auto_update_enabled():
+            if context.auto_update_enabled():
                 await self.__session.auto_update(self.__session.page)
         except FletPageDisconnectedException:
             logger.debug(

sdk/python/packages/flet/docs/types/aliases.md

@@ -5,6 +5,7 @@
 ::: flet.BorderSideStrokeAlignValue
 ::: flet.BoxShadowValue
 ::: flet.ColorValue
+::: flet.context
 ::: flet.ControlEvent
 ::: flet.ControlEventHandler
 ::: flet.ControlStateValue

sdk/python/packages/flet/docs/types/cache.md

@@ -0,0 +1,9 @@
+::: flet.cache
+
+## Examples
+
+### Cached item view
+
+```python
+--8<-- "../../examples/controls/decorators/cache/basic.py"
+```

sdk/python/packages/flet/docs/types/context.md

@@ -0,0 +1,20 @@
+Manages the context for Flet controls, including page reference
+and auto-update behavior.
+
+Context instance is accessed via [`ft.context`][flet.context].
+
+## Examples
+
+### Get page
+
+```python
+--8<-- "../../examples/controls/types/context/get_page.py"
+```
+
+### Disable auto update
+
+```python
+--8<-- "../../examples/controls/types/context/disable_auto_update.py"
+```
+
+::: flet.Context