flet 0.70.0.dev6214__py3-none-any.whl → 0.70.0.dev6268__py3-none-any.whl

flet/controls/material/chip.py

@@ -27,11 +27,12 @@ class Chip(LayoutControl):
     """
     Chips are compact elements that represent an attribute, text, entity, or action.
 
-    Raises:
-        ValueError: If [`elevation`][(c).] or [`elevation_on_click`][(c).] is
-            negative.
-        ValueError: If callback for both [`on_click`][(c).] and [`on_select`][(c).]
-            are specified.
+    ```python
+    ft.Chip(
+        label="Explore topics",
+        leading=ft.Icon(ft.Icons.EXPLORE_OUTLINED),
+    )
+    ```
     """
 
     label: StrOrControl
@@ -64,6 +65,9 @@ class Chip(LayoutControl):
     A non-negative value which defines the size of the shadow below this chip.
 
     Defaults to `0`.
+
+    Raises:
+        ValueError: If [`elevation`][(c).] is negative.
     """
 
     bgcolor: Optional[ColorValue] = None
@@ -166,6 +170,9 @@ class Chip(LayoutControl):
 
     Note:
         Must be non-negative.
+
+    Raises:
+        ValueError: If [`elevation_on_click`][(c).] is negative.
     """
 
     clip_behavior: ClipBehavior = ClipBehavior.NONE
@@ -225,6 +232,10 @@ class Chip(LayoutControl):
 
     Note:
         Cannot be specified together with [`on_select`][(c).].
+
+    Raises:
+        ValueError: If both [`on_click`][(c).] and [`on_select`][(c).] callbacks
+            are provided.
     """
 
     on_delete: Optional[ControlEventHandler["Chip"]] = None

flet/controls/material/circle_avatar.py

@@ -20,11 +20,13 @@ class CircleAvatar(LayoutControl):
     If [`foreground_image_src`][(c).] fails then [`background_image_src`][(c).] is used,
     and if this also fails, then [`bgcolor`][(c).] is used.
 
-    Raises:
-        ValueError: If [`radius`][(c).] or [`min_radius`][(c).]
-            or [`max_radius`][(c).] is negative.
-        ValueError: If [`radius`][(c).] is set and [`min_radius`][(c).]
-            or [`max_radius`][(c).] is not None.
+    ```python
+    ft.CircleAvatar(
+        content=ft.Text("AB"),
+        bgcolor=ft.Colors.PRIMARY,
+        color=ft.Colors.ON_PRIMARY,
+    )
+    ```
     """
 
     content: Optional[StrOrControl] = None
@@ -75,6 +77,11 @@ class CircleAvatar(LayoutControl):
     The size of the avatar, expressed as the radius (half the diameter). If `radius` is
     specified, then neither [`min_radius`][(c).] nor
     [`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.
     """
 
     min_radius: Optional[Number] = None
@@ -83,6 +90,9 @@ class CircleAvatar(LayoutControl):
     `min_radius` is specified, then [`radius`][(c).] should not be specified.
 
     Defaults to `0.0`.
+
+    Raises:
+        ValueError: If [`min_radius`][(c).] is negative.
     """
 
     max_radius: Optional[Number] = None
@@ -93,6 +103,10 @@ class CircleAvatar(LayoutControl):
 
     Note:
         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.
     """
 
     on_image_error: Optional[ControlEventHandler["CircleAvatar"]] = None

flet/controls/material/datatable.py

@@ -34,10 +34,6 @@ class DataColumnSortEvent(Event["DataColumn"]):
 class DataColumn(Control):
     """
     Column configuration for a [`DataTable`][flet.].
-
-    Raises:
-        ValueError: If the [`label`][(c).] is neither a string nor
-            a visible control.
     """
 
     label: StrOrControl
@@ -47,6 +43,10 @@ class DataColumn(Control):
     Typically, this will be a [`Text`][flet.] control.
     It could also be an [`Icon`][flet.] (typically using size 18),
     or a combination of both in a [`Row`][flet.].
+
+    Raises:
+        ValueError: If the [`label`][(c).] is neither a string nor
+            a visible control.
     """
 
     numeric: bool = False
@@ -93,10 +93,6 @@ class DataColumn(Control):
 class DataCell(Control):
     """
     The data for a cell of a [`DataTable`][flet.].
-
-    Raises:
-        ValueError: If the [`content`][(c).] is neither a string nor a visible
-            control.
     """
 
     content: StrOrControl
@@ -113,6 +109,10 @@ class DataCell(Control):
         To lay out multiple children, set the [`content`][(c).] to a
         container-like control such as [`Row`][flet.], [`Column`][flet.], or
         [`Stack`][flet.], which have a `controls` property.
+
+    Raises:
+        ValueError: If the [`content`][(c).] is neither a string nor a visible
+            control.
     """
 
     placeholder: bool = False
@@ -199,9 +199,6 @@ class DataRow(Control):
     One row configuration must be provided for each row to display in the table.
 
     The data for this row of the table is provided in the [`cells`][(c).] property.
-
-    Raises:
-        ValueError: If [`cells`][(c).] does not contain at least one visible DataCell.
     """
 
     cells: list[DataCell] = field(default_factory=list)
@@ -210,6 +207,10 @@ class DataRow(Control):
 
     Note:
         There must be exactly as many cells as there are columns in the table.
+
+    Raises:
+        ValueError: If [`cells`][(c).] does not contain at least one visible
+            [`DataCell`][flet.].
     """
 
     color: Optional[ControlStateValue[ColorValue]] = None
@@ -281,24 +282,45 @@ class DataTable(LayoutControl):
     """
     A Material Design data table.
 
-    Raises:
-        ValueError: If there are no visible [`columns`][(c).].
-        ValueError: If any visible row does not contain exactly as many visible
-            [`DataRow.cells`][flet.] as there are visible [`columns`][(c).].
-        ValueError: If [`data_row_min_height`][(c).] is greater than
-            [`data_row_max_height`][(c).].
-        ValueError: If [`divider_thickness`][(c).] is negative.
-        ValueError: If [`sort_column_index`][(c).] is out of range.
+    ```python
+    ft.DataTable(
+        columns=[
+            ft.DataColumn(label=ft.Text("Name")),
+            ft.DataColumn(label=ft.Text("Role")),
+        ],
+        rows=[
+            ft.DataRow(
+                cells=[
+                    ft.DataCell(ft.Text("Alice")),
+                    ft.DataCell(ft.Text("Engineer")),
+                ]
+            ),
+            ft.DataRow(
+                cells=[
+                    ft.DataCell(ft.Text("Bob")),
+                    ft.DataCell(ft.Text("Designer")),
+                ]
+            ),
+        ],
+    )
+    ```
     """
 
     columns: list[DataColumn]
     """
     A list of [`DataColumn`][flet.] controls describing table columns.
+
+    Raises:
+        ValueError: If there are no visible [`columns`][(c).].
     """
 
     rows: list[DataRow] = field(default_factory=list)
     """
     A list of [`DataRow`][flet.] controls defining table rows.
+
+    Raises:
+        ValueError: If any visible row does not contain exactly as many visible
+            [`DataCell`][flet.]s as there are visible [`columns`][(c).].
     """
 
     sort_ascending: bool = False
@@ -336,6 +358,10 @@ class DataTable(LayoutControl):
 
     When this is `None`, it implies that the table's sort order does not correspond to
     any of the columns.
+
+    Raises:
+        ValueError: If [`sort_column_index`][(c).] is out of range relative to the
+            visible [`columns`][(c).].
     """
 
     show_bottom_border: bool = False
@@ -397,6 +423,10 @@ class DataTable(LayoutControl):
 
     Note:
         Must be less than or equal to [`data_row_max_height`][(c).].
+
+    Raises:
+        ValueError: If [`data_row_min_height`][(c).] is greater than
+            [`data_row_max_height`][(c).].
     """
 
     data_row_max_height: Optional[Number] = None
@@ -409,6 +439,10 @@ class DataTable(LayoutControl):
 
     Note:
         Must be greater than or equal to [`data_row_min_height`][(c).].
+
+    Raises:
+        ValueError: If [`data_row_max_height`][(c).] is less than
+            [`data_row_min_height`][(c).].
     """
 
     data_text_style: Optional[TextStyle] = None
@@ -432,6 +466,9 @@ class DataTable(LayoutControl):
 
     Note:
         Must be greater than or equal to zero.
+
+    Raises:
+        ValueError: If [`divider_thickness`][(c).] is negative.
     """
 
     heading_row_color: Optional[ControlStateValue[ColorValue]] = None

flet/controls/material/divider.py

@@ -13,11 +13,17 @@ class Divider(Control):
     """
     A thin horizontal line (divider), with padding on either side.
 
-    Raises:
-        ValueError: If [`height`][(c).] is negative.
-        ValueError: If [`thickness`][(c).] is negative.
-        ValueError: If [`leading_indent`][(c).] is negative.
-        ValueError: If [`trailing_indent`][(c).] is negative.
+    ```python
+    ft.Column(
+        width=240,
+        spacing=10,
+        controls=[
+            ft.Text("Section A", weight=ft.FontWeight.W_600),
+            ft.Divider(),
+            ft.Text("Section B"),
+        ],
+    )
+    ```
     """
 
     color: Optional[ColorValue] = None
@@ -34,6 +40,9 @@ class Divider(Control):
 
     If `None`, [`DividerTheme.space`][flet.] is used.
     If that's is also `None`, defaults to `16.0`.
+
+    Raises:
+        ValueError: If [`height`][(c).] is negative.
     """
 
     leading_indent: Optional[Number] = None
@@ -42,6 +51,9 @@ class Divider(Control):
 
     If `None`, [`DividerTheme.leading_indent`][flet.] is used.
     If that's is also `None`, defaults to `0.0`.
+
+    Raises:
+        ValueError: If [`leading_indent`][(c).] is negative.
     """
 
     thickness: Optional[Number] = None
@@ -53,6 +65,9 @@ class Divider(Control):
 
     If `None`, [`DividerTheme.thickness`][flet.] is used.
     If that is also `None`, defaults to `0.0`.
+
+    Raises:
+        ValueError: If [`thickness`][(c).] is negative.
     """
 
     trailing_indent: Optional[Number] = None
@@ -61,6 +76,9 @@ class Divider(Control):
 
     If `None`, [`DividerTheme.trailing_indent`][flet.] is used.
     If that is also `None`, defaults to `0.0`.
+
+    Raises:
+        ValueError: If [`trailing_indent`][(c).] is negative.
     """
 
     radius: Optional[BorderRadiusValue] = None

flet/controls/material/dropdown.py

@@ -30,9 +30,6 @@ class DropdownOption(Control):
     """
     Represents an item in a dropdown. Either `key` or `text` must be specified, else an
     `AssertionError` will be raised.
-
-    Raises:
-        ValueError: If neither [`key`][(c).] nor [`text`][(c).] are provided.
     """
 
     key: Optional[str] = None
@@ -44,6 +41,9 @@ class DropdownOption(Control):
     text: Optional[str] = None
     """
     Option's display text. If not specified `key` will be used as fallback.
+
+    Raises:
+        ValueError: If neither [`key`][(c).] nor [`text`][(c).] are provided.
     """
 
     content: Optional[Control] = None
@@ -81,6 +81,17 @@ class Dropdown(LayoutControl):
     """
     A dropdown control that allows users to select a single option from a list of
     options.
+
+    ```python
+    ft.Dropdown(
+        width=220,
+        value="alice",
+        options=[
+            ft.dropdown.Option(key="alice", text="Alice"),
+            ft.dropdown.Option(key="bob", text="Bob"),
+        ],
+    )
+    ```
     """
 
     value: Optional[str] = None

flet/controls/material/dropdownm2.py

@@ -69,6 +69,17 @@ class DropdownM2(FormFieldControl):
     A dropdown lets the user select from a number of items. The dropdown shows the
     currently selected item as well as an arrow that opens a menu for selecting another
     item.
+
+    ```python
+    ft.DropdownM2(
+        width=220,
+        value="Alice",
+        options=[
+            ft.dropdownm2.Option(key="Alice", text="Alice"),
+            ft.dropdownm2.Option(key="Bob", text="Bob"),
+        ],
+    )
+    ```
     """
 
     value: Optional[str] = None

flet/controls/material/expansion_panel.py

@@ -20,6 +20,23 @@ class ExpansionPanel(LayoutControl, AdaptiveControl):
     """
     A material expansion panel. It can either be expanded or collapsed. Its body is
     only visible when it is expanded.
+
+    ```python
+    ft.ExpansionPanelList(
+        width=400,
+        controls=[
+            ft.ExpansionPanel(
+                header=ft.Text("Shipping address"),
+                content=ft.Text("123 Market Street, Springfield"),
+                expanded=True,
+            ),
+            ft.ExpansionPanel(
+                header=ft.Text("Billing address"),
+                content=ft.Text("Same as shipping"),
+            ),
+        ],
+    )
+    ```
     """
 
     header: Optional[Control] = None
@@ -71,6 +88,23 @@ class ExpansionPanel(LayoutControl, AdaptiveControl):
 class ExpansionPanelList(LayoutControl):
     """
     A material expansion panel list that lays out its children and animates expansions.
+
+    ```python
+    ft.ExpansionPanelList(
+        width=400,
+        controls=[
+            ft.ExpansionPanel(
+                header=ft.Text("Details"),
+                content=ft.Text("More information here"),
+                expanded=True,
+            ),
+            ft.ExpansionPanel(
+                header=ft.Text("History"),
+                content=ft.Text("View previous updates"),
+            ),
+        ],
+    )
+    ```
     """
 
     controls: list[ExpansionPanel] = field(default_factory=list)

flet/controls/material/expansion_tile.py

@@ -34,8 +34,18 @@ class ExpansionTile(LayoutControl, AdaptiveControl):
     A single-line ListTile with an expansion arrow icon that expands or collapses the
     tile to reveal or hide its controls.
 
-    Raises:
-        ValueError: If [`title`][(c).] is neither a string nor a visible Control.
+    ```python
+    ft.ExpansionTile(
+        width=400,
+        title="Account",
+        subtitle="Manage profile and security",
+        controls=[
+            ft.ListTile(title=ft.Text("Profile")),
+            ft.ListTile(title=ft.Text("Security")),
+        ],
+        initially_expanded=True,
+    )
+    ```
     """
 
     title: StrOrControl
@@ -43,6 +53,9 @@ class ExpansionTile(LayoutControl, AdaptiveControl):
     A `Control` to display as primary content of the tile.
 
     Typically a [`Text`][flet.] control.
+
+    Raises:
+        ValueError: If [`title`][(c).] is neither a string nor a visible Control.
     """
 
     controls: Optional[list[Control]] = None

flet/controls/material/filled_button.py

@@ -9,6 +9,10 @@ class FilledButton(Button):
     [`FloatingActionButton`][flet.], and is typically used for
     important, final actions that complete a flow, like "Save",
     "Join now", or "Confirm".
+
+    ```python
+    ft.FilledButton(content="Tap me")
+    ```
     """
 
     pass

flet/controls/material/filled_tonal_button.py

@@ -9,6 +9,10 @@ class FilledTonalButton(Button):
     OutlinedButton buttons. They're useful in contexts where a lower-priority button
     requires slightly more emphasis than an outline would give, such as "Next" in an
     onboarding flow. Tonal buttons use the secondary color mapping.
+
+    ```python
+    ft.FilledTonalButton(content="Tap me")
+    ```
     """
 
     pass

flet/controls/material/floating_action_button.py

@@ -26,18 +26,18 @@ class FloatingActionButton(LayoutControl):
     to `page.floating_action_button`, but can also be added as a regular control at any
     place on a page.
 
-    Raises:
-        ValueError: If neither [`icon`][(c).] nor a valid [`content`][(c).]
-            (string or visible Control) is provided.
-        ValueError: If [`elevation`][(c).],
-            [`disabled_elevation`][(c).], [`focus_elevation`][(c).],
-            [`highlight_elevation`][(c).], or [`hover_elevation`][(c).]
-            is negative.
+    ```python
+    ft.FloatingActionButton(icon=ft.Icons.ADD)
+    ```
     """
 
     content: Optional[StrOrControl] = None
     """
     The content of this button.
+
+    Raises:
+        ValueError: If neither [`icon`][(c).] nor a valid [`content`][(c).]
+            (string or visible Control) is provided.
     """
 
     icon: Optional[IconDataOrControl] = None
@@ -93,6 +93,9 @@ class FloatingActionButton(LayoutControl):
     The elevation of this button.
 
     Defaults to `6`.
+
+    Raises:
+        ValueError: If [`elevation`][(c).] is negative.
     """
 
     disabled_elevation: Optional[Number] = None
@@ -100,6 +103,9 @@ class FloatingActionButton(LayoutControl):
     The elevation of this button when disabled.
 
     Defaults to the same value as `elevation`.
+
+    Raises:
+        ValueError: If [`disabled_elevation`][(c).] is negative.
     """
 
     focus_elevation: Optional[Number] = None
@@ -107,6 +113,9 @@ class FloatingActionButton(LayoutControl):
     The elevation of this button when it has input focus.
 
     Defaults to `8`.
+
+    Raises:
+        ValueError: If [`focus_elevation`][(c).] is negative.
     """
 
     highlight_elevation: Optional[Number] = None
@@ -114,6 +123,9 @@ class FloatingActionButton(LayoutControl):
     The elevation of this button when it is highlighted.
 
     Defaults to `12`.
+
+    Raises:
+        ValueError: If [`highlight_elevation`][(c).] is negative.
     """
 
     hover_elevation: Optional[Number] = None
@@ -121,6 +133,9 @@ class FloatingActionButton(LayoutControl):
     The elevation of this button it is enabled and being hovered over.
 
     Defaults to `8`.
+
+    Raises:
+        ValueError: If [`hover_elevation`][(c).] is negative.
     """
 
     hover_color: Optional[ColorValue] = None

flet/controls/material/icon_button.py

@@ -35,8 +35,9 @@ class IconButton(LayoutControl, AdaptiveControl):
     Icon buttons are commonly used in the toolbars, but they can be used in many other
     places as well.
 
-    Raises:
-        ValueError: If [`splash_radius`][(c).] is not greater than `0`.
+    ```python
+    ft.IconButton(icon=ft.Icons.FAVORITE, icon_color=ft.Colors.PRIMARY)
+    ```
     """
 
     icon: Optional[IconDataOrControl] = None
@@ -136,6 +137,9 @@ class IconButton(LayoutControl, AdaptiveControl):
     Note:
         This value is honoured only when in Material 2
         ([`Theme.use_material3`][flet.] is `False`).
+
+    Raises:
+        ValueError: If [`splash_radius`][(c).] is not greater than `0`.
     """
 
     alignment: Optional[Alignment] = None
@@ -233,6 +237,10 @@ class FilledIconButton(IconButton):
 
     Filled icon buttons have higher visual impact and should be used for high emphasis
     actions, such as turning off a microphone or camera.
+
+    ```python
+    ft.FilledIconButton(icon=ft.Icons.CHECK)
+    ```
     """
 
 
@@ -245,6 +253,10 @@ class FilledTonalIconButton(IconButton):
     outlined icon buttons. They're useful in contexts where the button requires
     slightly more emphasis than an outline would give, such as a secondary action
     paired with a high emphasis action.
+
+    ```python
+    ft.FilledTonalIconButton(icon=ft.Icons.CHECK)
+    ```
     """
 
 

flet/controls/material/list_tile.py

@@ -47,6 +47,17 @@ class ListTile(LayoutControl, AdaptiveControl):
     """
     A single fixed-height row that typically contains some text as well as a leading or
     trailing icon.
+
+    ```python
+    ft.ListTile(
+        width=400,
+        leading=ft.Icon(ft.Icons.ACCOUNT_CIRCLE),
+        title="Jane Doe",
+        subtitle="Product Manager",
+        trailing=ft.Icon(ft.Icons.CHEVRON_RIGHT),
+        bgcolor=ft.Colors.SURFACE_CONTAINER_LOW,
+    )
+    ```
     """
 
     title: Optional[StrOrControl] = None

flet/controls/material/navigation_rail.py

@@ -81,11 +81,6 @@ class NavigationRail(LayoutControl):
     """
     A material widget that is meant to be displayed at the left or right of an app to
     navigate between a small number of views, typically between three and five.
-
-    Raises:
-        ValueError: If [`elevation`][(c).] is negative.
-        ValueError: If [`min_width`][(c).] is negative.
-        ValueError: If [`min_extended_width`][(c).] is negative.
     """
 
     destinations: list[NavigationRailDestination] = field(default_factory=list)
@@ -101,6 +96,9 @@ class NavigationRail(LayoutControl):
     Controls the size of the shadow below the NavigationRail.
 
     Defaults to `0.0`.
+
+    Raises:
+        ValueError: If [`elevation`][(c).] is negative.
     """
 
     selected_index: Optional[int] = None
@@ -180,6 +178,9 @@ class NavigationRail(LayoutControl):
     This value also defines the min width and min height of the destinations.
 
     To make a compact rail, set this to `56` and use `label_type='none'`.
+
+    Raises:
+        ValueError: If [`min_width`][(c).] is negative.
     """
 
     min_extended_width: Optional[Number] = None
@@ -187,6 +188,9 @@ class NavigationRail(LayoutControl):
     The final width when the animation is complete for setting `extended` to `True`.
 
     Defaults to `256`.
+
+    Raises:
+        ValueError: If [`min_extended_width`][(c).] is negative.
     """
 
     group_alignment: Optional[Number] = None

flet/controls/material/outlined_button.py

@@ -23,14 +23,14 @@ class OutlinedButton(LayoutControl, AdaptiveControl):
     Outlined buttons are medium-emphasis buttons. They contain actions that are
     important, but aren't the primary action in an app. Outlined buttons pair well with
     filled buttons to indicate an alternative, secondary action.
-
-    Raises:
-        ValueError: If neither [`icon`][(c).] nor [`content`][(c).] is provided.
     """
 
     content: Optional[StrOrControl] = None
     """
     A Control representing custom button content.
+
+    Raises:
+        ValueError: If neither [`icon`][(c).] nor [`content`][(c).] is provided.
     """
 
     icon: Optional[IconDataOrControl] = None