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.

Author: FeodorFitsner

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/packages/flet/docs/types/cache.md

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

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

@@ -60,7 +60,7 @@ def control(
         isolated: If `True`, marks the control as isolated. An isolated control
             is excluded from page updates when its parent control is updated.
         post_init_args: Number of InitVar arguments to pass to __post_init__.
-        **dataclass_kwargs: Additional keyword arguments passed to @dataclass.
+        dataclass_kwargs: Additional keyword arguments passed to @dataclass.
 
     Usage:
         - Supports `@control` (without parentheses)

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

@@ -7,7 +7,6 @@
 R = TypeVar("R")
 
 
-# --- Utility to create a hashable signature from args ---
 def _hash_args(*args, **kwargs):
     try:
         # Convert args/kwargs to a string and hash it
@@ -18,7 +17,6 @@ def _hash_args(*args, **kwargs):
         return str(id(args)) + str(id(kwargs))
 
 
-# --- Freeze controls in the returned structure ---
 def _freeze_controls(control):
     if isinstance(control, list):
         return [_freeze_controls(c) for c in control]
@@ -29,9 +27,6 @@ def _freeze_controls(control):
     return control
 
 
-# --- Main decorator with `freeze` option ---
-
-
 @overload
 def cache(
     _fn: None = ..., *, freeze: bool = False
@@ -41,28 +36,50 @@ def cache(_fn: Callable[P, R], *, freeze: bool = False) -> Callable[P, R]: ...
 
 
 def cache(_fn: Optional[Callable[P, R]] = None, *, freeze: bool = False):
+    """
+    A decorator to cache the results of a function based on its arguments.
+    Used with Flet controls to optimize comparisons in declarative apps.
+
+    Args:
+        _fn: The function to be decorated.
+            If None, the decorator is used with arguments.
+        freeze: If `True`, freezes the returned controls
+            by setting a `_frozen` attribute.
+
+    Returns:
+        A decorated function that caches its results.
+    """
+
     def decorator(fn: Callable[P, R]) -> Callable[P, R]:
+        # Use a weak reference dictionary to store cached results
         cache_store = weakref.WeakValueDictionary()
 
         @functools.wraps(fn)
         def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            # Generate a unique hash key based on the function arguments
             key = _hash_args(*args, **kwargs)
 
+            # Return cached result if it exists
             if key in cache_store:
                 return cache_store[key]
 
+            # Call the original function and cache the result
             result = fn(*args, **kwargs)
             if result is not None:
                 if freeze:
+                    # Freeze the controls if the freeze flag is set
                     _freeze_controls(result)
                 cache_store[key] = result
             elif key in cache_store:
+                # Remove the cache entry if the result is None
                 del cache_store[key]
             return result
 
         return wrapper
 
+    # If _fn is None, return the decorator itself for use with arguments
     if _fn is None:
         return decorator
     else:
+        # Apply the decorator directly if _fn is provided
         return decorator(_fn)