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

flet/controls/material/auto_complete.py

@@ -1,9 +1,9 @@
 from dataclasses import dataclass, field
 from typing import Optional
 
+from flet import LayoutControl
 from flet.controls.base_control import control
-from flet.controls.control import Control
-from flet.controls.control_event import Event, EventHandler
+from flet.controls.control_event import ControlEventHandler, Event, EventHandler
 from flet.controls.types import Number
 
 __all__ = ["AutoComplete", "AutoCompleteSelectEvent", "AutoCompleteSuggestion"]
@@ -11,22 +11,45 @@ __all__ = ["AutoComplete", "AutoCompleteSelectEvent", "AutoCompleteSuggestion"]
 
 @dataclass
 class AutoCompleteSuggestion:
+    """
+    Represents a suggestion item for the [`AutoComplete`][flet.] control.
+    """
+
     key: str
+    """A unique identifier or value used for filtering and selection."""
+
     value: str
+    """The display text shown to the user."""
 
 
 @dataclass
 class AutoCompleteSelectEvent(Event["AutoComplete"]):
+    """Event representing the selection of a suggestion in the AutoComplete control."""
+
+    index: int
+    """
+    The index of the selected suggestion from the corresponding
+    [`AutoComplete.suggestions`][flet.] list.
+    """
+
     selection: AutoCompleteSuggestion
+    """The selected suggestion."""
 
 
 @control("AutoComplete")
-class AutoComplete(Control):
+class AutoComplete(LayoutControl):
     """
     Helps the user make a selection by entering some text and choosing from among a
     list of displayed options.
     """
 
+    value: str = ""
+    """
+    Current text displayed in the input field.
+
+    This value reflects user input even if it does not match any provided suggestion.
+    """
+
     suggestions: list[AutoCompleteSuggestion] = field(default_factory=list)
     """
     A list of [`AutoCompleteSuggestion`][flet.]
@@ -53,7 +76,19 @@ class AutoComplete(Control):
     Called when a suggestion is selected.
     """
 
+    on_change: Optional[ControlEventHandler["AutoComplete"]] = None
+    """
+    Called when the input text changes.
+    """
+
     @property
-    def selected_index(self):
-        # TODO: check availability of _selected_index + a default if not yet available
-        return self._selected_index
+    def selected_index(self) -> Optional[int]:
+        """
+        The index of the (last) selected suggestion.
+
+        It is `None` until a suggestion has been selected from the UI.
+
+        Note:
+            This property is read-only.
+        """
+        return getattr(self, "_selected_index", None)

flet/controls/material/chip.py

@@ -168,11 +168,8 @@ class Chip(LayoutControl):
 
     Defaults to `8.0`.
 
-    Note:
-        Must be non-negative.
-
     Raises:
-        ValueError: If [`elevation_on_click`][(c).] is negative.
+        ValueError: If it is less than `0.0`.
     """
 
     clip_behavior: ClipBehavior = ClipBehavior.NONE
@@ -230,12 +227,8 @@ class Chip(LayoutControl):
     """
     Called when the user clicks on this chip.
 
-    Note:
-        Cannot be specified together with [`on_select`][(c).].
-
     Raises:
-        ValueError: If both [`on_click`][(c).] and [`on_select`][(c).] callbacks
-            are provided.
+        ValueError: If specified together with [`on_select`][(c).].
     """
 
     on_delete: Optional[ControlEventHandler["Chip"]] = None
@@ -249,8 +242,8 @@ class Chip(LayoutControl):
 
     It internally changes [`selected`][(c).] property to the opposite value.
 
-    Note:
-        Cannot be specified together with [`on_click`][(c).].
+    Raises:
+        ValueError: If specified together with [`on_click`][(c).].
     """
 
     on_focus: Optional[ControlEventHandler["Chip"]] = None

flet/controls/material/circle_avatar.py

@@ -79,9 +79,8 @@ class CircleAvatar(LayoutControl):
     [`max_radius`][(c).] may be specified.
 
     Raises:
-        ValueError: If [`radius`][(c).] is negative.
-        ValueError: If [`radius`][(c).] is set while [`min_radius`][(c).]
-            or [`max_radius`][(c).] is provided.
+        ValueError: If it is less than `0.0` or if it is
+            provided while [`min_radius`][(c).] or [`max_radius`][(c).] is set.
     """
 
     min_radius: Optional[Number] = None
@@ -92,7 +91,7 @@ class CircleAvatar(LayoutControl):
     Defaults to `0.0`.
 
     Raises:
-        ValueError: If [`min_radius`][(c).] is negative.
+        ValueError: If it is negative.
     """
 
     max_radius: Optional[Number] = None
@@ -105,8 +104,8 @@ class CircleAvatar(LayoutControl):
         If `max_radius` is specified, then [`radius`][(c).] should not be specified.
 
     Raises:
-        ValueError: If [`max_radius`][(c).] is negative.
-        ValueError: If [`max_radius`][(c).] is provided while [`radius`][(c).] is set.
+        ValueError: If it is less than `0.0` or if it is
+            provided while [`radius`][(c).] is set.
     """
 
     on_image_error: Optional[ControlEventHandler["CircleAvatar"]] = None

flet/controls/material/dropdown.py

@@ -29,7 +29,7 @@ __all__ = ["Dropdown", "DropdownOption"]
 class DropdownOption(Control):
     """
     Represents an item in a dropdown. Either `key` or `text` must be specified, else an
-    `AssertionError` will be raised.
+    A `ValueError` will be raised.
     """
 
     key: Optional[str] = None
@@ -247,7 +247,8 @@ class Dropdown(LayoutControl):
     """
     Text that appears below the input border.
 
-    If non-null, the border's color animates to red and the `helper_text` is not shown.
+    If non-null, the border's color animates to red and the [`helper_text`][(c).] is
+    not shown.
     """
 
     text_size: Optional[Number] = None
@@ -291,13 +292,18 @@ class Dropdown(LayoutControl):
 
     border_width: Number = 1
     """
-    The width of the border in virtual pixels. Set to `0` to completely remove border.
+    The width of the border in virtual pixels.
+
+    Tip:
+        Set to `0` to completely remove the border.
     """
 
     border_color: Optional[ColorValue] = None
     """
-    Border color. Could be `transparent` to
-    hide the border.
+    Border color.
+
+    Tip:
+        Set to [`Colors.TRANSPARENT`][flet.] to hide the border.
     """
 
     border_radius: Optional[BorderRadiusValue] = None

flet/controls/material/dropdownm2.py

@@ -19,8 +19,8 @@ __all__ = ["DropdownM2", "Option"]
 @control("Option")
 class Option(Control):
     """
-    Represents an item in a dropdown. Either `key` or `text` must be specified, else an
-    `AssertionError` will be raised.
+    Represents an item in a dropdown. Either `key` or `text` must be specified, else a
+    `ValueError` will be raised.
     """
 
     key: Optional[str] = None
@@ -58,9 +58,8 @@ class Option(Control):
 
     def before_update(self):
         super().before_update()
-        assert self.key is not None or self.text is not None, (
-            "key or text must be specified"
-        )
+        if self.key is None and self.text is None:
+            raise ValueError("key or text must be specified")
 
 
 @control("DropdownM2")

flet/controls/material/expansion_panel.py

@@ -64,13 +64,12 @@ class ExpansionPanel(LayoutControl, AdaptiveControl):
 
     expanded: bool = False
     """
-    Whether expanded(`True`) or collapsed(`False`). Defaults to `False`.
+    Whether expanded(`True`) or collapsed(`False`).
     """
 
     can_tap_header: bool = False
     """
-    If `True`, tapping on the panel's `header` will expand or collapse it. Defaults to
-    `False`.
+    If `True`, tapping on the panel's `header` will expand or collapse it.
     """
 
     splash_color: Optional[ColorValue] = None
@@ -109,19 +108,21 @@ class ExpansionPanelList(LayoutControl):
 
     controls: list[ExpansionPanel] = field(default_factory=list)
     """
-    A list of `ExpansionPanel`s to display inside `ExpansionPanelList`.
+    A list of panels to display.
     """
 
     divider_color: Optional[ColorValue] = None
     """
     The color of the divider when
-    `ExpansionPanel.expanded` is `False`.
+    [`ExpansionPanel.expanded`][flet.] is `False`.
     """
 
     elevation: Number = 2
     """
-    Defines the elevation of the children controls (`ExpansionPanel`s), while it is
-    expanded. Default value is `2`.
+    Defines the elevation of the [`controls`][(c).], when expanded.
+
+    Raises:
+        ValueError: If it is less than zero.
     """
 
     expanded_header_padding: PaddingValue = field(
@@ -133,23 +134,26 @@ class ExpansionPanelList(LayoutControl):
 
     expand_icon_color: Optional[ColorValue] = None
     """
-    The color of the icon. Defaults to
-    `colors.BLACK_54` in light theme mode and `colors.WHITE_60` in dark theme mode.
+    The color of the icon.
+
+    Defaults to [`Colors.BLACK_54`][flet.] in light theme mode and
+    [`Colors.WHITE_60`][flet.] in dark theme mode.
     """
 
     spacing: Optional[Number] = None
     """
-    The size of the gap between the `ExpansionPanel`s when expanded.
+    The size of the gap between the [`controls`][(c).]s when expanded.
     """
 
     on_change: Optional[ControlEventHandler["ExpansionPanelList"]] = None
     """
-    Called when an `ExpansionPanel` is expanded or collapsed. The event's data
-    (`e.data`), contains the index of the `ExpansionPanel` which triggered this event.
+    Called when an item of [`controls`][(c).] is expanded or collapsed.
+
+    The event's [`data`][flet.Event.], contains the index of the
+    child panel (in [`controls`][(c).]) which triggered this event.
     """
 
     def before_update(self):
         super().before_update()
-        assert self.elevation is None or self.elevation >= 0, (
-            "elevation cannot be negative"
-        )
+        if self.elevation < 0:
+            raise ValueError("elevation must be greater than or equal to zero")

flet/controls/material/menu_bar.py

@@ -48,7 +48,10 @@ class MenuBar(Control):
 
     controls: list[Control] = field(default_factory=list)
     """
-    The list of menu items that are the top level children of the `MenuBar`.
+    A list of top-level menu controls to display in this menu bar.
+
+    Raises:
+        ValueError: If none of the controls are visible.
     """
 
     clip_behavior: ClipBehavior = ClipBehavior.NONE
@@ -58,11 +61,10 @@ class MenuBar(Control):
 
     style: Optional[MenuStyle] = None
     """
-    TBD
+    The menu bar style.
     """
 
     def before_update(self):
         super().before_update()
-        assert any(c.visible for c in self.controls), (
-            "MenuBar must have at minimum one visible control"
-        )
+        if not any(c.visible for c in self.controls):
+            raise ValueError("MenuBar must have at minimum one visible control")

flet/controls/material/menu_item_button.py

@@ -80,7 +80,7 @@ class MenuItemButton(LayoutControl):
 
     on_click: Optional[ControlEventHandler["MenuItemButton"]] = None
     """
-    Called when the button is clicked.
+    Called when the button is clicked.If not defined the button will be disabled.
     """
 
     on_hover: Optional[ControlEventHandler["MenuItemButton"]] = None

flet/controls/material/snack_bar.py

@@ -219,11 +219,8 @@ class SnackBar(DialogControl):
 
     At a value of `0.0`, the `action` will not overflow to a new line.
 
-    Note:
-        Must be between `0.0` and `1.0` inclusive.
-
     Raises:
-        ValueError: If [`action_overflow_threshold`][(c).] is not between `0` and `1`.
+        ValueError: If it is not between `0.0` and `1.0` inclusive.
     """
 
     on_action: Optional[ControlEventHandler["SnackBar"]] = None

flet/controls/material/submenu_button.py

@@ -19,6 +19,25 @@ class SubmenuButton(LayoutControl):
     A menu button that displays a cascading menu.
 
     Typically used in a [`MenuBar`][flet.] control.
+
+    ```python
+    ft.SubmenuButton(
+        content=ft.Text("Choose text style"),
+        key="smbutton",
+        expand=True,
+        menu_style=ft.MenuStyle(
+            alignment=ft.Alignment.BOTTOM_LEFT, side=ft.BorderSide(1)
+        ),
+        controls=[
+            ft.MenuItemButton(
+                content=ft.Text("Underlined"),
+                on_click=lambda e: print(f"{e.control.content.value}.on_click")
+            ),
+            ft.MenuItemButton(...),
+            ...
+        ]
+    )
+    ```
     """
 
     content: Optional[StrOrControl] = None

flet/controls/material/switch.py

@@ -26,6 +26,11 @@ class Switch(LayoutControl, AdaptiveControl):
     two mutually exclusive options.
 
     For example, "On/Off", "Show/Hide".
+
+    ```python
+        ft.Switch(label="Unchecked switch", value=False)
+        ft.Switch(label="Disabled switch", disabled=True)
+    ```
     """
 
     label: Optional[StrOrControl] = None

flet/controls/material/tabs.py

@@ -172,7 +172,7 @@ class Tabs(LayoutControl, AdaptiveControl):
         it when adding/removing tabs.
 
     Raises:
-        ValueError: If [`length`][(c).] is negative.
+        ValueError: If it is negative.
     """
 
     selected_index: int = 0
@@ -191,8 +191,7 @@ class Tabs(LayoutControl, AdaptiveControl):
             use [`move_to`][(c).] directly.
 
     Raises:
-        IndexError: If [`selected_index`][(c).] is not in the range
-            `[-length, length - 1]`.
+        IndexError: If it is not in the range `[-length, length - 1]`.
     """
 
     animation_duration: DurationValue = field(
@@ -353,18 +352,14 @@ class TabBar(LayoutControl, AdaptiveControl):
     otherwise [`TabAlignment.FILL`][flet.] is used.
 
     Note:
-        - If [`scrollable`][(c).] is `False`, then
-            [`tab_alignment`][(c).] must be either
-            [`TabAlignment.FILL`][flet.] or
-            [`TabAlignment.CENTER`][flet.].
-        - If [`scrollable`][(c).] is `True`, then
-            [`tab_alignment`][(c).] must be
-            [`TabAlignment.START`][flet.],
-            [`TabAlignment.START_OFFSET`][flet.]
+        - If [`scrollable`][(c).] is `False`, then [`tab_alignment`][(c).] must be
+            either [`TabAlignment.FILL`][flet.] or [`TabAlignment.CENTER`][flet.].
+        - If [`scrollable`][(c).] is `True`, then [`tab_alignment`][(c).] must be
+            [`TabAlignment.START`][flet.], [`TabAlignment.START_OFFSET`][flet.]
             or [`TabAlignment.CENTER`][flet.].
 
     Raises:
-        ValueError: If [`tab_alignment`][(c).] is not valid for the current
+        ValueError: If it is not valid for the current
             [`scrollable`][(c).] configuration.
     """
 

flet/controls/material/text_button.py

@@ -22,6 +22,14 @@ class TextButton(LayoutControl, AdaptiveControl):
     Text buttons are used for the lowest priority actions, especially when presenting
     multiple options. Text buttons can be placed on a variety of backgrounds. Until the
     button is interacted with, its container isn’t visible.
+
+    ```python
+    ft.TextButton(
+            content="Text Button",
+            icon=ft.Icons.STAR_BORDER,
+            icon_color=ft.Colors.BLUE_300,
+        )
+    ```
     """
 
     content: Optional[StrOrControl] = None

flet/controls/material/time_picker.py

@@ -38,6 +38,14 @@ class TimePicker(DialogControl):
 
     Depending on the `time_picker_entry_mode`, it will show either a Dial or
     an Input (hour and minute text fields) for picking a time.
+
+    ```python
+    ft.TimePicker(
+        value=time(1, 2),
+        time_picker_entry_mode=ft.TimePickerEntryMode.INPUT_ONLY,
+        open=True,
+    )
+    ```
     """
 
     value: Optional[time] = field(default_factory=lambda: datetime.now().time())

flet/controls/page.py

@@ -42,6 +42,7 @@ from flet.controls.device_info import (
     WebDeviceInfo,
     WindowsDeviceInfo,
 )
+from flet.controls.exceptions import FletUnsupportedPlatformException
 from flet.controls.multi_view import MultiView
 from flet.controls.query_string import QueryString
 from flet.controls.ref import Ref
@@ -54,6 +55,7 @@ from flet.controls.services.url_launcher import UrlLauncher
 from flet.controls.types import (
     AppLifecycleState,
     Brightness,
+    DeviceOrientation,
     PagePlatform,
     Url,
     UrlTarget,
@@ -198,7 +200,7 @@ class Page(BasePage):
     Used to enable or disable the context menu that appears when the user
     right-clicks on the web page.
 
-    Note:
+    Limitation:
         Web only.
     """
 
@@ -939,3 +941,48 @@ class Page(BasePage):
             return from_dict(WindowsDeviceInfo, info)
         else:
             return None
+
+    async def set_allowed_device_orientations(
+        self, orientations: list[DeviceOrientation]
+    ) -> None:
+        """
+        Constrains the allowed orientations for the app when running on a mobile device.
+
+        Args:
+            orientations: A list of allowed device orientations.
+                Set to an empty list to use the system default behavior.
+
+        Raises:
+            FletUnsupportedPlatformException: If the method is called
+                on a non-mobile platform.
+
+        Limitations:
+            - **Android**: On Android 16 (API 36) or later, this method won't be able to
+                change the orientation of **devices with a display width ≥ 600 dp**
+                cannot change orientation. For more details see Android 16 docs
+                [here](https://developer.android.com/about/versions/16/behavior-changes-16#ignore-orientation).
+                Also, Android limits the [orientations](https://developer.android.com/reference/android/R.attr#screenOrientation) to the following combinations:
+                    - `[]` → `unspecified`
+                    - `[PORTRAIT_UP]` → `portrait`
+                    - `[LANDSCAPE_LEFT]` → `landscape`
+                    - `[PORTRAIT_DOWN]` → `reversePortrait`
+                    - `[PORTRAIT_UP, PORTRAIT_DOWN]` → `userPortrait`
+                    - `[LANDSCAPE_RIGHT]` → `reverseLandscape`
+                    - `[LANDSCAPE_LEFT, LANDSCAPE_RIGHT]` → `userLandscape`
+                    - `[PORTRAIT_UP, LANDSCAPE_LEFT, LANDSCAPE_RIGHT]` → `user`
+                    - `[PORTRAIT_UP, PORTRAIT_DOWN, LANDSCAPE_LEFT, LANDSCAPE_RIGHT]` → `fullUser`
+
+            - **iOS**: This setting will only be respected on iPad if multitasking is disabled.
+                You can decide to opt out of multitasking on iPad, then this will work
+                but your app will not support Slide Over and Split View multitasking
+                anymore. Should you decide to opt out of multitasking you can do this by
+                setting "Requires full screen" to true in the Xcode Deployment Info.
+        """  # noqa: E501
+        if not self.platform.is_mobile():
+            raise FletUnsupportedPlatformException(
+                "set_allowed_device_orientations is only supported on mobile platforms"
+            )
+        await self._invoke_method(
+            "set_allowed_device_orientations",
+            arguments={"orientations": orientations},
+        )

flet/controls/services/shared_preferences.py

@@ -9,7 +9,8 @@ __all__ = ["SharedPreferences"]
 @control("SharedPreferences")
 class SharedPreferences(Service):
     async def set(self, key: str, value: Any) -> bool:
-        assert value is not None
+        if value is None:
+            raise ValueError("value can't be None")
         return await self._invoke_method("set", {"key": key, "value": value})
 
     async def get(self, key: str):

flet/controls/types.py

@@ -544,17 +544,43 @@ class Brightness(Enum):
 
 class Orientation(Enum):
     """
-    Whether in portrait or landscape.
+    Represents the layout orientation.
     """
 
     PORTRAIT = "portrait"
     """
-    Taller than wide.
+    Orientation with greater height than width.
     """
 
     LANDSCAPE = "landscape"
     """
-    Wider than tall.
+    Orientation with greater width than height.
+    """
+
+
+class DeviceOrientation(Enum):
+    """
+    Supported physical orientations for mobile devices.
+    """
+
+    PORTRAIT_UP = "portraitUp"
+    """
+    Device held upright in portrait mode.
+    """
+
+    PORTRAIT_DOWN = "portraitDown"
+    """
+    Device held upside-down in portrait mode.
+    """
+
+    LANDSCAPE_LEFT = "landscapeLeft"
+    """
+    Device rotated 90° counter-clockwise (home button or primary edge on the right).
+    """
+
+    LANDSCAPE_RIGHT = "landscapeRight"
+    """
+    Device rotated 90° clockwise (home button or primary edge on the left).
     """
 
 

flet/pubsub/pubsub_hub.py

@@ -147,7 +147,8 @@ class PubSubHub:
     def __send(
         self, handler: Union[Callable, Callable[..., Awaitable[Any]]], args: Iterable
     ):
-        assert self.__loop, "PubSub event loop is not set"
+        if not self.__loop:
+            raise RuntimeError("PubSub event loop is not set")
 
         if asyncio.iscoroutinefunction(handler):
             asyncio.run_coroutine_threadsafe(handler(*args), self.__loop)

flet/testing/flet_test_app.py

@@ -136,7 +136,8 @@ class FletTestApp:
         """
         Returns an instance of Flet's app [`Page`][flet.].
         """
-        assert self.__page
+        if self.__page is None:
+            raise RuntimeError("page is not initialized")
         return self.__page
 
     @property
@@ -145,7 +146,8 @@ class FletTestApp:
         Returns an instance of [`Tester`][flet.testing.] class
         that programmatically interacts with page controls and the test environment.
         """
-        assert self.__tester
+        if self.__tester is None:
+            raise RuntimeError("tester is not initialized")
         return self.__tester
 
     async def start(self):
@@ -330,10 +332,13 @@ class FletTestApp:
             name: Screenshot name - will be used as a base for a screenshot filename.
             screenshot: Screenshot contents in PNG format.
         """
-        assert self.test_platform, (
-            "FLET_TEST_PLATFORM must be set to test with screenshots"
-        )
-        assert self.__test_path, "test_path must be set to test with screenshots"
+        if not self.test_platform:
+            raise RuntimeError(
+                "FLET_TEST_PLATFORM environment variable must be set "
+                "to test with screenshots"
+            )
+        if not self.__test_path:
+            raise RuntimeError("test_path must be set to test with screenshots")
 
         golden_image_path = (
             Path(self.__test_path).parent