flet 0.70.0.dev6365__py3-none-any.whl → 0.70.0.dev6412__py3-none-any.whl

flet/__init__.py

@@ -491,6 +491,7 @@ from flet.controls.types import (
     ClipBehavior,
     ColorValue,
     CrossAxisAlignment,
+    DeviceOrientation,
     FloatingActionButtonLocation,
     FontWeight,
     IconDataOrControl,
@@ -658,6 +659,7 @@ __all__ = [
     "DateTimeValue",
     "DecorationImage",
     "DeviceInfo",
+    "DeviceOrientation",
     "DialogControl",
     "DialogTheme",
     "DismissDirection",

flet/components/hooks/use_state.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from collections.abc import Callable
 from dataclasses import dataclass
 from typing import Any, TypeVar
@@ -6,6 +8,9 @@ from flet.components.hooks.hook import Hook
 from flet.components.observable import Observable, ObservableSubscription
 from flet.components.utils import current_component
 
+StateT = TypeVar("StateT")
+Updater = Callable[[StateT], StateT]
+
 
 @dataclass
 class StateHook(Hook):
@@ -14,20 +19,21 @@ class StateHook(Hook):
     version: int = 0
 
 
-StateT = TypeVar("StateT")
-
-
 def use_state(
     initial: StateT | Callable[[], StateT],
-) -> tuple[StateT, Callable[[StateT], None]]:
+) -> tuple[StateT, Callable[[StateT | Updater], None]]:
     """
-    Add state to function components.
+    Adds state to a function component, similar to React's useState().
+
+    The returned setter accepts either:
+      - a new value, or
+      - a function receiving the previous state and returning the next one.
 
     Args:
-        initial: Initial state value or a function that returns the initial state value.
+        initial: Initial state value or a function returning it.
 
     Returns:
-        A tuple of the current state value and a function to update it.
+        (value, set_value) tuple.
     """
     component = current_component()
     hook = component.use_hook(
@@ -37,17 +43,34 @@ def use_state(
         )
     )
 
-    def update_subscription(hook: StateHook):
-        if hook.subscription:
-            component._detach_observable_subscription(hook.subscription)
-            hook.subscription = None
-        if isinstance(hook.value, Observable):
-            hook.subscription = component._attach_observable_subscription(hook.value)
+    def update_subscription(h: StateHook):
+        # Detach previous subscription if any
+        if h.subscription:
+            component._detach_observable_subscription(h.subscription)
+            h.subscription = None
+
+        # Attach new subscription if value is Observable
+        if isinstance(h.value, Observable):
+            h.subscription = component._attach_observable_subscription(h.value)
 
     update_subscription(hook)
 
-    def set_state(new_value: Any):
-        # shallow equality; swap to "is" or custom comparator if needed
+    def set_state(new_value_or_fn: StateT | Updater):
+        """
+        Update the state value.
+
+        Can be called with either:
+          - a direct new value, or
+          - a function that takes the current value and returns the next one.
+        """
+        # Compute next value
+        new_value = (
+            new_value_or_fn(hook.value)
+            if callable(new_value_or_fn)
+            else new_value_or_fn
+        )
+
+        # Only trigger update if value changed (shallow equality)
         if new_value != hook.value:
             hook.value = new_value
             update_subscription(hook)

flet/controls/base_control.py

@@ -233,9 +233,10 @@ class BaseControl:
     def update(self) -> None:
         if hasattr(self, "_frozen"):
             raise Exception("Frozen control cannot be updated.")
-        assert (
-            self.page
-        ), f"{self.__class__.__qualname__} Control must be added to the page first"
+        if not self.page:
+            raise RuntimeError(
+                f"{self.__class__.__qualname__} Control must be added to the page first"
+            )
         self.page.update(self)
 
     async def _invoke_method(
@@ -244,9 +245,10 @@ class BaseControl:
         arguments: Optional[dict[str, Any]] = None,
         timeout: Optional[float] = None,
     ) -> Any:
-        assert (
-            self.page
-        ), f"{self.__class__.__qualname__} Control must be added to the page first"
+        if not self.page:
+            raise RuntimeError(
+                f"{self.__class__.__qualname__} Control must be added to the page first"
+            )
 
         return await self.page.session.invoke_method(
             self._i, method_name, arguments, timeout
@@ -282,10 +284,11 @@ class BaseControl:
 
             controls_log.debug(f"Trigger event {self}.{field_name} {e}")
 
-            assert self.page, (
-                "Control must be added to a page before triggering events. "
-                "Use page.add(control) or add it to a parent control that's on a page."
-            )
+            if not self.page:
+                raise RuntimeError(
+                    "Control must be added to a page before triggering events. Use "
+                    "page.add(control) or add it to a parent control that's on a page."
+                )
             session = self.page.session
 
             # Handle async and sync event handlers accordingly

flet/controls/base_page.py

@@ -35,6 +35,7 @@ from flet.controls.types import (
     LocaleConfiguration,
     MainAxisAlignment,
     Number,
+    Orientation,
     ScrollMode,
     ThemeMode,
 )
@@ -75,6 +76,11 @@ class PageMediaData:
     The number of device pixels for each logical pixel.
     """
 
+    orientation: Orientation
+    """
+    The orientation of the page.
+    """
+
 
 @dataclass
 class PageResizeEvent(Event["BasePage"]):
@@ -184,7 +190,7 @@ class BasePage(AdaptiveControl):
 
     on_media_change: Optional[EventHandler[PageMediaData]] = None
     """
-    Called when `media` has changed.
+    Called when [`media`][(c).] has changed.
     """
 
     media: PageMediaData = field(
@@ -193,6 +199,7 @@ class BasePage(AdaptiveControl):
             view_padding=Padding.zero(),
             view_insets=Padding.zero(),
             device_pixel_ratio=0,
+            orientation=Orientation.PORTRAIT,
         )
     )
     """
@@ -231,7 +238,8 @@ class BasePage(AdaptiveControl):
     _dialogs: "Dialogs" = field(default_factory=lambda: Dialogs())
 
     def __default_view(self) -> View:
-        assert len(self.views) > 0, "views list is empty."
+        if len(self.views) == 0:
+            raise RuntimeError("views list is empty.")
         return self.views[0]
 
     def update(self, *controls) -> None:

flet/controls/border.py

@@ -68,7 +68,7 @@ class BorderSide:
         to [`BorderStyle.NONE`][flet.].
 
     Raises:
-        AssertionError: If [`width`][(c).] is negative.
+        ValueError: If it is less than zero.
     """
 
     color: ColorValue = Colors.BLACK

flet/controls/box.py

@@ -336,17 +336,17 @@ class BoxDecoration:
     """
 
     def __post_init__(self):
-        assert (
+        if not (
             self.blend_mode is None
             or self.bgcolor is not None
             or self.gradient is not None
-        ), (
-            "blend_mode applies to the BoxDecoration's background color or gradient, "
-            "but no color or gradient was provided"
-        )
-        assert not (self.shape == BoxShape.CIRCLE and self.border_radius), (
-            "border_radius must be None when shape is BoxShape.CIRCLE"
-        )
+        ):
+            raise ValueError(
+                "blend_mode applies to the BoxDecoration's background color "
+                "or gradient, but no color or gradient was provided"
+            )
+        if self.shape == BoxShape.CIRCLE and self.border_radius:
+            raise ValueError("border_radius must be None when shape is BoxShape.CIRCLE")
 
     def copy(
         self,
@@ -414,14 +414,16 @@ class BoxConstraints:
     """
 
     def __post_init__(self):
-        assert 0 <= self.min_width <= self.max_width <= float("inf"), (
-            "min_width and max_width must be between 0 and infinity "
-            "and min_width must be less than or equal to max_width"
-        )
-        assert 0 <= self.min_height <= self.max_height <= float("inf"), (
-            "min_height and max_height must be between 0 and infinity "
-            "and min_height must be less than or equal to max_height"
-        )
+        if not (0 <= self.min_width <= self.max_width <= float("inf")):
+            raise ValueError(
+                "min_width and max_width must be between 0 and infinity "
+                "and min_width must be less than or equal to max_width"
+            )
+        if not (0 <= self.min_height <= self.max_height <= float("inf")):
+            raise ValueError(
+                "min_height and max_height must be between 0 and infinity "
+                "and min_height must be less than or equal to max_height"
+            )
 
     def copy(
         self,

flet/controls/colors.py

@@ -120,11 +120,12 @@ class Colors(str, Enum):
             'red,0.5'
 
         Raises:
-            AssertionError: If the opacity is not between `0` and `1` (inclusive).
+            ValueError: If the opacity is not between `0` and `1` (inclusive).
         """
-        assert 0 <= opacity <= 1, (
-            f"opacity must be between 0.0 and 1.0 inclusive, got {opacity}"
-        )
+        if not (0 <= opacity <= 1):
+            raise ValueError(
+                f"opacity must be between 0.0 and 1.0 inclusive, got {opacity}"
+            )
         color_str = color.value if isinstance(color, Enum) else color
         return f"{color_str},{opacity}"
 

flet/controls/context.py

@@ -32,7 +32,7 @@ class Context:
             The current page.
 
         Raises:
-            AssertionError: if property is called outside of Flet app.
+            RuntimeError: If the property is accessed outside a running Flet app.
         """
         page = _context_page.get()
         if page is None:

flet/controls/control_event.py

@@ -97,7 +97,8 @@ class Event(Generic[EventControlType]):
 
     @property
     def page(self) -> Union["Page", "BasePage"]:
-        assert self.control.page
+        if not self.control.page:
+            raise RuntimeError("event control is not attached to a page")
         return self.control.page
 
     @property

flet/controls/core/dismissible.py

@@ -70,12 +70,8 @@ class Dismissible(LayoutControl, AdaptiveControl):
     A control that is stacked behind the [`content`][(c).] and is
     exposed when it has been dragged up or to the left.
 
-    Note:
-        Can only be specified if [`background`][(c).] is also
-        specified/visible.
-
     Raises:
-        ValueError: If the [`secondary_background`][(c).] is provided and visible
+        ValueError: If it is provided and visible
             but the [`background`][(c).] is not provided and visible.
     """
 

flet/controls/core/interactive_viewer.py

@@ -58,36 +58,25 @@ class InteractiveViewer(LayoutControl):
     """
     The maximum allowed scale.
 
-    Note:
-        Must be greater than or equal to [`min_scale`][(c).].
-
     Raises:
-        ValueError: If [`max_scale`][(c).] is not greater than `0` or is less than
+        ValueError: If it is not greater than `0` or is less than
             [`min_scale`][(c).].
-    """  # noqa: E501
+    """
 
     min_scale: Number = 0.8
     """
     The minimum allowed scale.
 
-    Note:
-        Must be greater than `0` and less than or equal
-        to [`max_scale`][(c).].
-
     Raises:
-        ValueError: If [`min_scale`][(c).] is not greater than `0`.
+        ValueError: If it is not greater than `0` or less than [`max_scale`][(c).].
     """
 
     interaction_end_friction_coefficient: Number = 0.0000135
     """
     Changes the deceleration behavior after a gesture.
 
-    Note:
-        Must be greater than `0`.
-
     Raises:
-        ValueError: If [`interaction_end_friction_coefficient`][(c).] is not greater
-            than `0`.
+        ValueError: If it is less than or equal to `0`.
     """
 
     scale_factor: Number = 200
@@ -97,22 +86,23 @@ class InteractiveViewer(LayoutControl):
 
     clip_behavior: ClipBehavior = ClipBehavior.HARD_EDGE
     """
-    How to clip the `content`.
+    Defines how to clip the [`content`][(c).].
     """
 
     alignment: Optional[Alignment] = None
     """
-    Alignment of the `content` within.
+    The alignment of the [`content`][(c).] within this viewer.
     """
 
     boundary_margin: MarginValue = 0
     """
-    A margin for the visible boundaries of the `content`.
+    A margin for the visible boundaries of the [`content`][(c).].
     """
 
     interaction_update_interval: int = 200
     """
-    The interval (in milliseconds) at which the `on_interaction_update` event is fired.
+    The interval (in milliseconds) at which the
+    [`on_interaction_update`][(c).] event is fired.
     """
 
     on_interaction_start: Optional[
@@ -149,10 +139,7 @@ class InteractiveViewer(LayoutControl):
                 "max_scale must be greater than or equal to min_scale, "
                 f"got max_scale={self.max_scale}, min_scale={self.min_scale}"
             )
-        if (
-            self.interaction_end_friction_coefficient is not None
-            and self.interaction_end_friction_coefficient <= 0
-        ):
+        if self.interaction_end_friction_coefficient <= 0:
             raise ValueError(
                 "interaction_end_friction_coefficient must be greater than 0, "
                 f"got {self.interaction_end_friction_coefficient}"

flet/controls/core/responsive_row.py

@@ -56,8 +56,7 @@ class ResponsiveRow(LayoutControl, AdaptiveControl):
 
     Note:
         Has effect only when [`alignment`][(c).] is set to
-        [`MainAxisAlignment.START`][flet.],
-        [`MainAxisAlignment.END`][flet.],
+        [`MainAxisAlignment.START`][flet.], [`MainAxisAlignment.END`][flet.],
         or [`MainAxisAlignment.CENTER`][flet.].
     """
 

flet/controls/core/row.py

@@ -40,8 +40,7 @@ class Row(LayoutControl, ScrollableControl, AdaptiveControl):
 
     Note:
         Has effect only when [`alignment`][(c).] is set to
-        [`MainAxisAlignment.START`][flet.],
-        [`MainAxisAlignment.END`][flet.],
+        [`MainAxisAlignment.START`][flet.], [`MainAxisAlignment.END`][flet.],
         or [`MainAxisAlignment.CENTER`][flet.].
     """
 

flet/controls/core/stack.py

@@ -31,6 +31,33 @@ class Stack(LayoutControl, AdaptiveControl):
     Stack is also useful if you want to implement implicit animations
     (https://flet.dev/docs/guides/python/animations/) that require knowing absolute
     position of a target value.
+
+    ```python
+    ft.Stack(
+            width=300,
+            height=300,
+            controls=[
+                ft.Image(
+                    src="https://picsum.photos/300/300",
+                    width=300,
+                    height=300,
+                    fit=ft.BoxFit.CONTAIN,
+                ),
+                ft.Row(
+                    alignment=ft.MainAxisAlignment.CENTER,
+                    controls=[
+                        ft.Text(
+                            value="Image title",
+                            color=ft.Colors.SURFACE_TINT,
+                            size=40,
+                            weight=ft.FontWeight.BOLD,
+                            opacity=0.5,
+                        )
+                    ],
+                ),
+            ],
+        )
+    ```
     """
 
     controls: list[Control] = field(default_factory=list)

flet/controls/core/view.py

@@ -131,10 +131,8 @@ class View(ScrollableControl, LayoutControl):
 
     Note:
         Has effect only when [`vertical_alignment`][(c).]
-        is set to
-        [`MainAxisAlignment.START`][flet.],
-        [`MainAxisAlignment.END`][flet.],
-        or [`MainAxisAlignment.CENTER`][flet.].
+        is set to [`MainAxisAlignment.START`][flet.],
+        [`MainAxisAlignment.END`][flet.], or [`MainAxisAlignment.CENTER`][flet.].
     """
 
     padding: Optional[PaddingValue] = field(default_factory=lambda: Padding.all(10))

flet/controls/core/window.py

@@ -54,7 +54,7 @@ class Window(BaseControl):
     """
     Controls the app window.
 
-    Note:
+    Limitation:
         This control is for Desktop platforms (macOS, Windows, Linux) only.
     """
 
@@ -113,8 +113,8 @@ class Window(BaseControl):
     """
     Defines the opacity of the app window.
 
-    Note:
-        Must be between `0.0` and `1.0`.
+    Raises:
+        ValueError: If it is not between `0.0` and `1.0` inclusive.
     """
 
     aspect_ratio: Optional[Number] = None
@@ -160,7 +160,7 @@ class Window(BaseControl):
     """
     Whether the app window can be moved.
 
-    Note:
+    Limitation:
         Has effect on macOS only.
     """
 
@@ -178,7 +178,7 @@ class Window(BaseControl):
     """
     Whether the app window should always be displayed below other windows.
 
-    Note:
+    Limitation:
         Has effect on Linux and Windows only.
     """
 
@@ -204,7 +204,7 @@ class Window(BaseControl):
     """
     Whether to hide the app window's title bar buttons.
 
-    Note:
+    Limitation:
         Has effect on macOS only.
     """
 
@@ -246,7 +246,7 @@ class Window(BaseControl):
     """
     Sets a badge label on the app window.
 
-    Note:
+    Limitation:
         Has effect on macOS only.
     """
 
@@ -256,7 +256,7 @@ class Window(BaseControl):
 
     The file should have the `.ico` extension.
 
-    Note:
+    Limitation:
         Has effect on Windows only.
     """
 
@@ -275,6 +275,10 @@ class Window(BaseControl):
     def __post_init__(self, ref) -> None:
         super().__post_init__(ref)
         self._i = 2
+        if self.opacity < 0.0 or self.opacity > 1.0:
+            raise ValueError(
+                f"opacity must be between 0.0 and 1.0 inclusive, got {self.opacity}"
+            )
 
     async def wait_until_ready_to_show(self):
         """

flet/controls/cupertino/cupertino_colors.py

@@ -19,7 +19,7 @@ Code to sort the members:
 ```
 s = sorted(CupertinoColors, key=lambda i: i.name)
 for i in s:
-    print(f"{i.name} = \"{i.value}\"")
+    print(f'{i.name} = "{i.value}"')
 ```
 """
 
@@ -54,18 +54,20 @@ class CupertinoColors(str, Enum):
             color: The color to apply opacity to.
 
         Returns:
-            A string representing the color with opacity, in the format `"color,opacity"`.
+            A string representing the color with opacity,
+                in the format `"color,opacity"`.
 
         Examples:
             >>> CupertinoColors.with_opacity(0.5, CupertinoColors.WHITE)
             'white,0.5'
 
         Raises:
-            AssertionError: If the opacity is not between `0` and `1` (inclusive).
+            ValueError: If the opacity is not between `0` and `1` (inclusive).
         """
-        assert 0 <= opacity <= 1, (
-            f"opacity must be between 0.0 and 1.0 inclusive, got {opacity}"
-        )
+        if not (0 <= opacity <= 1):
+            raise ValueError(
+                f"opacity must be between 0.0 and 1.0 inclusive, got {opacity}"
+            )
         color_str = color.value if isinstance(color, Enum) else color
         return f"{color_str},{opacity}"
 

flet/controls/material/app_bar.py

@@ -103,7 +103,7 @@ class AppBar(AdaptiveControl):
         (when [`Theme.use_material3`][flet.] is `False`).
 
     Raises:
-        ValueError: If [`elevation`][(c).] is negative.
+        ValueError: If it is less than `0.0`.
     """
 
     elevation_on_scroll: Optional[Number] = None
@@ -111,7 +111,7 @@ class AppBar(AdaptiveControl):
     The elevation to be used if this app bar has something scrolled underneath it.
 
     Raises:
-        ValueError: If [`elevation_on_scroll`][(c).] is negative.
+        ValueError: If it is less than `0.0`.
     """
 
     shadow_color: Optional[ColorValue] = None
@@ -183,12 +183,11 @@ class AppBar(AdaptiveControl):
     """
     The opacity of the toolbar.
 
-    Note:
-        Must be in the range `0.0` (transparent) to `1.0` (fully opaque).
+    - `0.0`: transparent
+    - `1.0`: fully opaque
 
     Raises:
-        ValueError: If [`toolbar_opacity`][(c).] is not between `0.0`
-            and `1.0` inclusive.
+        ValueError: If it is not between `0.0` and `1.0` inclusive.
     """
 
     title_text_style: Optional[TextStyle] = None