From 107c62aeed9450c4eff5675f1eb719377e826141 Mon Sep 17 00:00:00 2001 From: ndonkoHenri Date: Fri, 17 Oct 2025 00:52:11 +0200 Subject: [PATCH 1/6] initial commit --- .../flet-ads/src/flet_ads/banner_ad.py | 3 +- .../packages/flet-ads/src/flet_ads/base_ad.py | 11 +-- .../flet-ads/src/flet_ads/interstitial_ad.py | 3 +- .../flet-ads/src/flet_ads/native_ad.py | 7 +- .../src/flet_audio_recorder/audio_recorder.py | 8 ++- .../flet-audio/src/flet_audio/audio.py | 7 +- .../flet-charts/src/flet_charts/bar_chart.py | 6 +- .../flet-charts/src/flet_charts/chart_axis.py | 6 +- .../src/flet_charts/line_chart_data.py | 4 +- .../src/flet_charts/line_chart_data_point.py | 2 +- .../src/flet_charts/pie_chart_section.py | 22 +++--- .../src/flet_datatable2/datacolumn2.py | 2 +- .../flet-desktop/src/flet_desktop/__init__.py | 12 ++-- .../src/flet_geolocator/geolocator.py | 25 ++++--- .../flet-lottie/src/flet_lottie/lottie.py | 21 +++--- .../flet-map/src/flet_map/circle_layer.py | 22 +++--- .../src/flet_map/simple_attribution.py | 2 +- .../src/flet_map/source_attribution.py | 6 +- .../packages/flet-map/src/flet_map/types.py | 60 ++++++++-------- .../src/flet_permission_handler/types.py | 6 +- .../flet-video/src/flet_video/types.py | 2 +- .../flet-video/src/flet_video/video.py | 10 +-- .../flet/src/flet/controls/base_control.py | 23 ++++--- .../flet/src/flet/controls/base_page.py | 3 +- .../packages/flet/src/flet/controls/border.py | 2 +- .../packages/flet/src/flet/controls/box.py | 34 +++++----- .../packages/flet/src/flet/controls/colors.py | 9 +-- .../flet/src/flet/controls/context.py | 2 +- .../flet/src/flet/controls/control_event.py | 3 +- .../controls/cupertino/cupertino_colors.py | 14 ++-- .../src/flet/controls/material/dropdown.py | 16 +++-- .../src/flet/controls/material/dropdownm2.py | 9 ++- .../flet/controls/material/expansion_panel.py | 68 ++++++------------- .../src/flet/controls/material/menu_bar.py | 12 ++-- .../controls/services/shared_preferences.py | 3 +- .../flet/src/flet/pubsub/pubsub_hub.py | 3 +- .../flet/src/flet/testing/flet_test_app.py | 21 +++--- .../packages/flet/src/flet/utils/pip.py | 33 +++++---- 38 files changed, 256 insertions(+), 246 deletions(-) diff --git a/sdk/python/packages/flet-ads/src/flet_ads/banner_ad.py b/sdk/python/packages/flet-ads/src/flet_ads/banner_ad.py index 16f6a74b25..0f375cf2fe 100644 --- a/sdk/python/packages/flet-ads/src/flet_ads/banner_ad.py +++ b/sdk/python/packages/flet-ads/src/flet_ads/banner_ad.py @@ -11,7 +11,8 @@ class BannerAd(BaseAd): Displays a banner ad. Raises: - AssertionError: When this control is used on a web and/or non-mobile platform. + FletUnsupportedPlatformException: When this control is used on a web + and/or non-mobile platform. """ on_will_dismiss: Optional[ft.ControlEventHandler["BannerAd"]] = None diff --git a/sdk/python/packages/flet-ads/src/flet_ads/base_ad.py b/sdk/python/packages/flet-ads/src/flet_ads/base_ad.py index b020176405..d835886d90 100644 --- a/sdk/python/packages/flet-ads/src/flet_ads/base_ad.py +++ b/sdk/python/packages/flet-ads/src/flet_ads/base_ad.py @@ -11,7 +11,8 @@ class BaseAd(ft.Control): Base class for all ad controls in Flet Ads package. Raises: - AssertionError: When using this control on a web and/or non-mobile platform. + FletUnsupportedPlatformException: When using this control on a web + and/or non-mobile platform. """ unit_id: str @@ -63,6 +64,8 @@ class BaseAd(ft.Control): """ def before_update(self): - assert not self.page.web and self.page.platform.is_mobile(), ( - f"{self.__class__.__name__} is only supported on Mobile (Android and iOS)" - ) + if self.page.web or not self.page.platform.is_mobile(): + raise ft.FletUnsupportedPlatformException( + f"{self.__class__.__name__} is only supported on " + f"Mobile (Android and iOS)" + ) diff --git a/sdk/python/packages/flet-ads/src/flet_ads/interstitial_ad.py b/sdk/python/packages/flet-ads/src/flet_ads/interstitial_ad.py index 77c3b48c51..719c0aca9d 100644 --- a/sdk/python/packages/flet-ads/src/flet_ads/interstitial_ad.py +++ b/sdk/python/packages/flet-ads/src/flet_ads/interstitial_ad.py @@ -8,7 +8,8 @@ class InterstitialAd(BaseAd): Displays a full-screen interstitial ad. Raises: - AssertionError: When using this control on a web and/or non-mobile platform. + FletUnsupportedPlatformException: When using this control on a + web and/or non-mobile platform. """ async def show(self): diff --git a/sdk/python/packages/flet-ads/src/flet_ads/native_ad.py b/sdk/python/packages/flet-ads/src/flet_ads/native_ad.py index 624a337670..a7c74a25f8 100644 --- a/sdk/python/packages/flet-ads/src/flet_ads/native_ad.py +++ b/sdk/python/packages/flet-ads/src/flet_ads/native_ad.py @@ -11,7 +11,7 @@ class NativeAd(BannerAd): Renders a native ad. Raises: - AssertionError: When neither [`factory_id`][(c).] nor + ValueError: When neither [`factory_id`][(c).] nor [`template_style`][(c).] is set. """ @@ -27,6 +27,5 @@ class NativeAd(BannerAd): def before_update(self): super().before_update() - assert self.factory_id is not None or self.template_style is not None, ( - "factory_id or template_style must be set" - ) + if self.factory_id is None and self.template_style is None: + raise ValueError("factory_id or template_style must be set") diff --git a/sdk/python/packages/flet-audio-recorder/src/flet_audio_recorder/audio_recorder.py b/sdk/python/packages/flet-audio-recorder/src/flet_audio_recorder/audio_recorder.py index 49e86270be..bf77a875e0 100644 --- a/sdk/python/packages/flet-audio-recorder/src/flet_audio_recorder/audio_recorder.py +++ b/sdk/python/packages/flet-audio-recorder/src/flet_audio_recorder/audio_recorder.py @@ -54,10 +54,12 @@ async def start_recording( Returns: `True` if recording was successfully started, `False` otherwise. + + Raises: + ValueError: If `output_path` is not provided on platforms other than web. """ - assert self.page.web or output_path, ( - "output_path must be provided on platforms other than web" - ) + if not (self.page.web or output_path): + raise ValueError("output_path must be provided on platforms other than web") return await self._invoke_method( method_name="start_recording", arguments={ diff --git a/sdk/python/packages/flet-audio/src/flet_audio/audio.py b/sdk/python/packages/flet-audio/src/flet_audio/audio.py index a3a29d9d5a..fd2e72ba50 100644 --- a/sdk/python/packages/flet-audio/src/flet_audio/audio.py +++ b/sdk/python/packages/flet-audio/src/flet_audio/audio.py @@ -27,7 +27,7 @@ class Audio(ft.Service): is a list of supported audio formats. Raises: - AssertionError: If both [`src`][(c).] and [`src_base64`][(c).] are `None`. + ValueError: If both [`src`][(c).] and [`src_base64`][(c).] are `None`. """ src_base64: Optional[str] = None @@ -41,7 +41,7 @@ class Audio(ft.Service): is a list of supported audio formats. Raises: - AssertionError: If both [`src`][(c).] and [`src_base64`][(c).] are `None`. + ValueError: If both [`src`][(c).] and [`src_base64`][(c).] are `None`. """ autoplay: bool = False @@ -118,7 +118,8 @@ class Audio(ft.Service): def before_update(self): super().before_update() - assert self.src or self.src_base64, "either src or src_base64 must be provided" + if not (self.src or self.src_base64): + raise ValueError("either src or src_base64 must be provided") async def play(self, position: ft.DurationValue = 0): """ diff --git a/sdk/python/packages/flet-charts/src/flet_charts/bar_chart.py b/sdk/python/packages/flet-charts/src/flet_charts/bar_chart.py index 3ea8ce14d0..5c12e7676c 100644 --- a/sdk/python/packages/flet-charts/src/flet_charts/bar_chart.py +++ b/sdk/python/packages/flet-charts/src/flet_charts/bar_chart.py @@ -175,15 +175,15 @@ class BarChart(ft.LayoutControl): group_spacing: ft.Number = 16.0 """ - A amount of space between bar [`groups`][..]. + A amount of space between bar [`groups`][(c).]. """ group_alignment: ft.MainAxisAlignment = ft.MainAxisAlignment.SPACE_EVENLY """ - The alignment of the bar [`groups`][..] within this chart. + The alignment of the bar [`groups`][(c).] within this chart. If set to [`MainAxisAlignment.CENTER`][flet.MainAxisAlignment.CENTER], - the space between the `groups` can be specified using [`group_spacing`][..]. + the space between the `groups` can be specified using [`group_spacing`][(c).]. """ animation: ft.AnimationValue = field( diff --git a/sdk/python/packages/flet-charts/src/flet_charts/chart_axis.py b/sdk/python/packages/flet-charts/src/flet_charts/chart_axis.py index 0bcd696e61..5a26d6968d 100644 --- a/sdk/python/packages/flet-charts/src/flet_charts/chart_axis.py +++ b/sdk/python/packages/flet-charts/src/flet_charts/chart_axis.py @@ -19,7 +19,7 @@ class ChartAxisLabel(ft.BaseControl): label: Optional[ft.StrOrControl] = None """ - The label to display for the specified [`value`][..]. + The label to display for the specified [`value`][(c).]. """ @@ -41,7 +41,7 @@ class ChartAxis(ft.BaseControl): show_labels: bool = True """ - Whether to display the [`labels`][..] along the axis. + Whether to display the [`labels`][(c).] along the axis. If `labels` is empty then automatic labels are displayed. """ @@ -61,7 +61,7 @@ class ChartAxis(ft.BaseControl): label_size: ft.Number = 22 """ - The maximum space for each label in [`labels`][..]. + The maximum space for each label in [`labels`][(c).]. Each label will stretch to fit this space. """ diff --git a/sdk/python/packages/flet-charts/src/flet_charts/line_chart_data.py b/sdk/python/packages/flet-charts/src/flet_charts/line_chart_data.py index 11689d84ab..7f823e1320 100644 --- a/sdk/python/packages/flet-charts/src/flet_charts/line_chart_data.py +++ b/sdk/python/packages/flet-charts/src/flet_charts/line_chart_data.py @@ -48,7 +48,7 @@ class LineChartData(ft.BaseControl): prevent_curve_over_shooting_threshold: ft.Number = 10.0 """ - Threshold for [`prevent_curve_over_shooting`][..] algorithm. + Threshold for [`prevent_curve_over_shooting`][(c).] algorithm. """ dash_pattern: Optional[list[int]] = None @@ -131,7 +131,7 @@ class LineChartData(ft.BaseControl): curve_smoothness: ft.Number = 0.35 """ Defines the smoothness of a curve line, - when [`curved`][..] is set to `True`. + when [`curved`][(c).] is set to `True`. """ rounded_stroke_join: bool = False diff --git a/sdk/python/packages/flet-charts/src/flet_charts/line_chart_data_point.py b/sdk/python/packages/flet-charts/src/flet_charts/line_chart_data_point.py index 355930522f..03e51fbd07 100644 --- a/sdk/python/packages/flet-charts/src/flet_charts/line_chart_data_point.py +++ b/sdk/python/packages/flet-charts/src/flet_charts/line_chart_data_point.py @@ -99,7 +99,7 @@ class LineChartDataPoint(ft.BaseControl): show_tooltip: bool = True """ - Whether the [`tooltip`][..] should be shown when this data point is hovered over. + Whether the [`tooltip`][(c).] should be shown when this data point is hovered over. """ def before_update(self): diff --git a/sdk/python/packages/flet-charts/src/flet_charts/pie_chart_section.py b/sdk/python/packages/flet-charts/src/flet_charts/pie_chart_section.py index 3b2e1749a6..ff8f68475c 100644 --- a/sdk/python/packages/flet-charts/src/flet_charts/pie_chart_section.py +++ b/sdk/python/packages/flet-charts/src/flet_charts/pie_chart_section.py @@ -12,8 +12,8 @@ class PieChartSection(ft.BaseControl): Configures a [PieChart][(p).] section. Raises: - AssertionError: If [`title_position`][(c).] or - [`badge_position`][(c).] is not between `0.0` and `1.0` inclusive. + ValueError: If [`title_position`][(c).] or [`badge_position`][(c).] + is not between `0.0` and `1.0` inclusive. """ value: ft.Number @@ -81,11 +81,13 @@ class PieChartSection(ft.BaseControl): def before_update(self): super().before_update() - assert self.title_position is None or (0.0 <= self.title_position <= 1.0), ( - f"title_position must be between 0.0 and 1.0 inclusive, " - f"got {self.title_position}" - ) - assert self.badge_position is None or (0.0 <= self.badge_position <= 1.0), ( - f"badge_position must be between 0.0 and 1.0 inclusive, " - f"got {self.badge_position}" - ) + if self.title_position is not None and not (0.0 <= self.title_position <= 1.0): + raise ValueError( + "title_position must be between 0.0 and 1.0 inclusive, " + f"got {self.title_position}" + ) + if self.badge_position is not None and not (0.0 <= self.badge_position <= 1.0): + raise ValueError( + "badge_position must be between 0.0 and 1.0 inclusive, " + f"got {self.badge_position}" + ) diff --git a/sdk/python/packages/flet-datatable2/src/flet_datatable2/datacolumn2.py b/sdk/python/packages/flet-datatable2/src/flet_datatable2/datacolumn2.py index e2f55cde0f..b4d8690d1b 100644 --- a/sdk/python/packages/flet-datatable2/src/flet_datatable2/datacolumn2.py +++ b/sdk/python/packages/flet-datatable2/src/flet_datatable2/datacolumn2.py @@ -34,7 +34,7 @@ class DataColumn2(ft.DataColumn): fixed_width: Optional[ft.Number] = None """ Defines absolute width of the column in pixels - (as opposed to relative [`size`][..] used by default). + (as opposed to relative [`size`][(c).] used by default). """ size: Optional[DataColumnSize] = DataColumnSize.S diff --git a/sdk/python/packages/flet-desktop/src/flet_desktop/__init__.py b/sdk/python/packages/flet-desktop/src/flet_desktop/__init__.py index 6ec17da3be..39f16197ca 100644 --- a/sdk/python/packages/flet-desktop/src/flet_desktop/__init__.py +++ b/sdk/python/packages/flet-desktop/src/flet_desktop/__init__.py @@ -10,6 +10,8 @@ import zipfile from pathlib import Path +import flet_desktop +import flet_desktop.version from flet.utils import ( get_arch, is_linux, @@ -19,9 +21,6 @@ safe_tar_extractall, ) -import flet_desktop -import flet_desktop.version - logger = logging.getLogger(flet_desktop.__name__) @@ -146,9 +145,10 @@ def __locate_and_unpack_flet_view(page_url, assets_dir, hidden): for f in os.listdir(temp_flet_dir): if f.endswith(".app"): app_name = f - assert app_name is not None, ( - f"Application bundle not found in {temp_flet_dir}" - ) + if app_name is None: + raise FileNotFoundError( + f"Application bundle not found in {temp_flet_dir}" + ) app_path = temp_flet_dir.joinpath(app_name) logger.info(f"page_url: {page_url}") logger.info(f"pid_file: {pid_file}") diff --git a/sdk/python/packages/flet-geolocator/src/flet_geolocator/geolocator.py b/sdk/python/packages/flet-geolocator/src/flet_geolocator/geolocator.py index 45dfa60c97..8dc5cec8d7 100644 --- a/sdk/python/packages/flet-geolocator/src/flet_geolocator/geolocator.py +++ b/sdk/python/packages/flet-geolocator/src/flet_geolocator/geolocator.py @@ -55,9 +55,9 @@ async def get_current_position( Note: Depending on the availability of different location services, this can take several seconds. It is recommended to call the - [`get_last_known_position`][..] method first to receive a + [`get_last_known_position`][(c).] method first to receive a known/cached position and update it with the result of the - [`get_current_position`][..] method. + [`get_current_position`][(c).] method. Args: configuration: Additional configuration for the location request. @@ -86,9 +86,12 @@ async def get_last_known_position(self) -> GeolocatorPosition: The last known position of the device as a [`GeolocatorPosition`][(p).]. Raises: - AssertionError: If invoked on a web platform. + FletUnsupportedPlatformException: If invoked on a web platform. """ - assert not self.page.web, "get_last_known_position is not supported on web" + if self.page.web: + raise ft.FletUnsupportedPlatformException( + "get_last_known_position is not supported on web" + ) r = await self._invoke_method( "get_last_known_position", ) @@ -138,9 +141,12 @@ async def open_app_settings(self) -> bool: `True` if the app's settings were opened successfully, `False` otherwise. Raises: - AssertionError: If invoked on a web platform. + FletUnsupportedPlatformException: If invoked on a web platform. """ - assert not self.page.web, "open_app_settings is not supported on web" + if self.page.web: + raise ft.FletUnsupportedPlatformException( + "open_app_settings is not supported on web" + ) return await self._invoke_method( "open_app_settings", ) @@ -156,9 +162,12 @@ async def open_location_settings(self) -> bool: `True` if the device's settings were opened successfully, `False` otherwise. Raises: - AssertionError: If invoked on a web platform. + FletUnsupportedPlatformException: If invoked on a web platform. """ - assert not self.page.web, "open_location_settings is not supported on web" + if self.page.web: + raise ft.FletUnsupportedPlatformException( + "open_location_settings is not supported on web" + ) return await self._invoke_method( "open_location_settings", ) diff --git a/sdk/python/packages/flet-lottie/src/flet_lottie/lottie.py b/sdk/python/packages/flet-lottie/src/flet_lottie/lottie.py index cfb2ab7e90..3995ad5db2 100644 --- a/sdk/python/packages/flet-lottie/src/flet_lottie/lottie.py +++ b/sdk/python/packages/flet-lottie/src/flet_lottie/lottie.py @@ -18,12 +18,11 @@ class Lottie(ft.LayoutControl): Can be a URL or a local [asset file](https://flet.dev/docs/cookbook/assets). Note: - If both `src` and [`src_base64`][..] are provided, + If both `src` and [`src_base64`][(c).] are provided, `src_base64` will be prioritized/used. Raises: - AssertionError: If neither [`src`][(c).] nor - [`src_base64`][(c).] is provided. + ValueError: If neither [`src`][(c).] nor [`src_base64`][(c).] is provided. """ src_base64: Optional[str] = None @@ -31,12 +30,11 @@ class Lottie(ft.LayoutControl): The base64 encoded string of the Lottie file. Note: - If both `src_base64` and [`src`][..] are provided, + If both `src_base64` and [`src`][(c).] are provided, `src_base64` will be prioritized/used. Raises: - AssertionError: If neither [`src`][(c).] nor - [`src_base64`][(c).] is provided. + ValueError: If neither [`src`][(c).] nor [`src_base64`][(c).] is provided. """ repeat: bool = True @@ -44,7 +42,7 @@ class Lottie(ft.LayoutControl): Whether the animation should repeat in a loop. Note: - Has no effect if [`animate`][..] is `False`. + Has no effect if [`animate`][(c).] is `False`. """ reverse: bool = False @@ -53,7 +51,7 @@ class Lottie(ft.LayoutControl): (from start to end and then continuously from end to start). Note: - Has no effect if [`animate`][..] or [`repeat`][..] is `False`. + Has no effect if [`animate`][(c).] or [`repeat`][(c).] is `False`. """ animate: bool = True @@ -97,7 +95,7 @@ class Lottie(ft.LayoutControl): A control to display when an error occurs while loading the Lottie animation. - For more information on the error, see [`on_error`][..]. + For more information on the error, see [`on_error`][(c).]. """ on_error: Optional[ft.ControlEventHandler["Lottie"]] = None @@ -110,6 +108,5 @@ class Lottie(ft.LayoutControl): def before_update(self): super().before_update() - assert self.src or self.src_base64, ( - "at least one of src and src_base64 must be provided" - ) + if not (self.src or self.src_base64): + raise ValueError("at least one of src and src_base64 must be provided") diff --git a/sdk/python/packages/flet-map/src/flet_map/circle_layer.py b/sdk/python/packages/flet-map/src/flet_map/circle_layer.py index 56035ee8e0..16e861f913 100644 --- a/sdk/python/packages/flet-map/src/flet_map/circle_layer.py +++ b/sdk/python/packages/flet-map/src/flet_map/circle_layer.py @@ -12,9 +12,6 @@ class CircleMarker(ft.Control): """ A circular marker displayed on the Map at the specified location through the [`CircleLayer`][(p).]. - - Raises: - AssertionError: If the [`border_stroke_width`][(c).] is negative. """ radius: ft.Number @@ -30,8 +27,8 @@ class CircleMarker(ft.Control): """ The color of the circle border line. - Note: - [`border_stroke_width`][..] must to be greater than + Tip: + [`border_stroke_width`][(c).] must be greater than `0.0` in order for this color to be visible. """ @@ -39,21 +36,22 @@ class CircleMarker(ft.Control): """ The stroke width for the circle border. - Note: - Must be non-negative. + Raises: + ValueError: If it is less than `0.0`. """ use_radius_in_meter: bool = False """ - Whether the [`radius`][..] should use the unit meters. + Whether the [`radius`][(c).] should use the unit meters. """ def before_update(self): super().before_update() - assert self.border_stroke_width >= 0, ( - f"border_stroke_width must be greater than or equal to 0, " - f"got {self.border_stroke_width}" - ) + if self.border_stroke_width < 0: + raise ValueError( + "border_stroke_width must be greater than or equal to 0, " + f"got {self.border_stroke_width}" + ) @ft.control("CircleLayer") diff --git a/sdk/python/packages/flet-map/src/flet_map/simple_attribution.py b/sdk/python/packages/flet-map/src/flet_map/simple_attribution.py index f6495c744f..03c90fc1bc 100644 --- a/sdk/python/packages/flet-map/src/flet_map/simple_attribution.py +++ b/sdk/python/packages/flet-map/src/flet_map/simple_attribution.py @@ -25,7 +25,7 @@ class SimpleAttribution(MapLayer): bgcolor: ft.ColorValue = ft.Colors.SURFACE """ - The color of the box containing the [`text`][..]. + The color of the box containing the [`text`][(c).]. """ on_click: Optional[ft.ControlEventHandler["SimpleAttribution"]] = None diff --git a/sdk/python/packages/flet-map/src/flet_map/source_attribution.py b/sdk/python/packages/flet-map/src/flet_map/source_attribution.py index 4cc81fb5c9..146e0dddb1 100644 --- a/sdk/python/packages/flet-map/src/flet_map/source_attribution.py +++ b/sdk/python/packages/flet-map/src/flet_map/source_attribution.py @@ -63,14 +63,14 @@ class TextSourceAttribution(SourceAttribution): """ text: str - """The text to display as attribution, styled with [`text_style`][..].""" + """The text to display as attribution, styled with [`text_style`][(c).].""" text_style: Optional[ft.TextStyle] = None - """Style used to display the [`text`][..].""" + """Style used to display the [`text`][(c).].""" prepend_copyright: bool = True """ - Whether to add the '©' character to the start of [`text`][..] automatically. + Whether to add the '©' character to the start of [`text`][(c).] automatically. """ on_click: Optional[ft.ControlEventHandler["TextSourceAttribution"]] = None diff --git a/sdk/python/packages/flet-map/src/flet_map/types.py b/sdk/python/packages/flet-map/src/flet_map/types.py index d63a93742c..56e22f1495 100644 --- a/sdk/python/packages/flet-map/src/flet_map/types.py +++ b/sdk/python/packages/flet-map/src/flet_map/types.py @@ -91,13 +91,13 @@ class PatternFit(Enum): SCALE_DOWN = "scaleDown" """ Scale the pattern to ensure it fits an integer number of times into the - polyline (smaller version regarding rounding, cf. [`SCALE_UP`][..]). + polyline (smaller version regarding rounding, cf. [`SCALE_UP`][(c).]). """ SCALE_UP = "scaleUp" """ Scale the pattern to ensure it fits an integer number of times into the - polyline (bigger version regarding rounding, cf. [`SCALE_DOWN`][..]). + polyline (bigger version regarding rounding, cf. [`SCALE_DOWN`][(c).]). """ APPEND_DOT = "appendDot" @@ -396,7 +396,7 @@ def has_double_tap_zoom(flags: int) -> bool: def has_rotate(flags: int) -> bool: """ Returns: - `True` if the [`ROTATE`][..] interactive flag is enabled. + `True` if the [`ROTATE`][(c).] interactive flag is enabled. """ return InteractionFlag.has_flag(flags, InteractionFlag.ROTATE) @@ -404,7 +404,7 @@ def has_rotate(flags: int) -> bool: def has_scroll_wheel_zoom(flags: int) -> bool: """ Returns: - `True` if the [`SCROLL_WHEEL_ZOOM`][..] interaction flag is enabled. + `True` if the [`SCROLL_WHEEL_ZOOM`][(c).] interaction flag is enabled. """ return InteractionFlag.has_flag(flags, InteractionFlag.SCROLL_WHEEL_ZOOM) @@ -434,11 +434,11 @@ class MultiFingerGesture(IntFlag): class InteractionConfiguration: enable_multi_finger_gesture_race: bool = False """ - If `True`, then [`rotation_threshold`][..] and [`pinch_zoom_threshold`][..] - and [`pinch_move_threshold`][..] will race. + If `True`, then [`rotation_threshold`][(c).] and [`pinch_zoom_threshold`][(c).] + and [`pinch_move_threshold`][(c).] will race. If multiple gestures win at the same time, then precedence: - [`pinch_zoom_win_gestures`][..] > [`rotation_win_gestures`][..] > - [`pinch_move_win_gestures`][..] + [`pinch_zoom_win_gestures`][(c).] > [`rotation_win_gestures`][(c).] > + [`pinch_move_win_gestures`][(c).] """ pinch_move_threshold: ft.Number = 40.0 @@ -450,7 +450,7 @@ class InteractionConfiguration: Note: If [`InteractionConfiguration.flags`][(p).] doesn't contain [`InteractionFlag.PINCH_MOVE`][(p).] - or [`enable_multi_finger_gesture_race`][..] is false then pinch move cannot win. + or [`enable_multi_finger_gesture_race`][(c).] is false then pinch move cannot win. """ scroll_wheel_velocity: ft.Number = 0.005 @@ -468,7 +468,7 @@ class InteractionConfiguration: Note: If [`InteractionConfiguration.flags`][(p).] doesn't contain [`InteractionFlag.PINCH_ZOOM`][(p).] - or [`enable_multi_finger_gesture_race`][..] is false then zoom cannot win. + or [`enable_multi_finger_gesture_race`][(c).] is false then zoom cannot win. """ rotation_threshold: ft.Number = 20.0 @@ -479,7 +479,7 @@ class InteractionConfiguration: Note: If [`InteractionConfiguration.flags`][(p).] doesn't contain [`InteractionFlag.ROTATE`][(p).] - or [`enable_multi_finger_gesture_race`][..] is false then rotate cannot win. + or [`enable_multi_finger_gesture_race`][(c).] is false then rotate cannot win. """ flags: InteractionFlag = InteractionFlag.ALL @@ -489,16 +489,16 @@ class InteractionConfiguration: rotation_win_gestures: MultiFingerGesture = MultiFingerGesture.ROTATE """ - When [`rotation_threshold`][..] wins over [`pinch_zoom_threshold`][..] and - [`pinch_move_threshold`][..] then `rotation_win_gestures` gestures will be used. + When [`rotation_threshold`][(c).] wins over [`pinch_zoom_threshold`][(c).] and + [`pinch_move_threshold`][(c).] then `rotation_win_gestures` gestures will be used. """ pinch_move_win_gestures: MultiFingerGesture = ( MultiFingerGesture.PINCH_ZOOM | MultiFingerGesture.PINCH_MOVE ) """ - When [`pinch_move_threshold`][..] wins over [`rotation_threshold`][..] - and [`pinch_zoom_threshold`][..] then `pinch_move_win_gestures` gestures + When [`pinch_move_threshold`][(c).] wins over [`rotation_threshold`][(c).] + and [`pinch_zoom_threshold`][(c).] then `pinch_move_win_gestures` gestures will be used. By default [`MultiFingerGesture.PINCH_MOVE`][(p).] @@ -510,8 +510,8 @@ class InteractionConfiguration: MultiFingerGesture.PINCH_ZOOM | MultiFingerGesture.PINCH_MOVE ) """ - When [`pinch_zoom_threshold`][..] wins over [`rotation_threshold`][..] - and [`pinch_move_threshold`][..] + When [`pinch_zoom_threshold`][(c).] wins over [`rotation_threshold`][(c).] + and [`pinch_move_threshold`][(c).] then `pinch_zoom_win_gestures` gestures will be used. By default [`MultiFingerGesture.PINCH_ZOOM`][(p).] @@ -629,7 +629,7 @@ class CameraFit: The bounds which the camera should contain once it is fitted. Note: - If this is not `None`, [`coordinates`][..] should be `None`, and vice versa. + If this is not `None`, [`coordinates`][(c).] should be `None`, and vice versa. """ coordinates: Optional[list[MapLatitudeLongitude]] = None @@ -637,7 +637,7 @@ class CameraFit: The coordinates which the camera should contain once it is fitted. Note: - If this is not `None`, [`bounds`][..] should be `None`, and vice versa. + If this is not `None`, [`bounds`][(c).] should be `None`, and vice versa. """ max_zoom: Optional[ft.Number] = None @@ -798,7 +798,7 @@ class KeyboardConfiguration: Duration of the curved ([`AnimationCurve.EASE_IN`][flet.AnimationCurve.EASE_IN]) portion of the animation occuring after a key down event (and after a key up event if - [`animation_curve_reverse_duration`][..] is `None`) + [`animation_curve_reverse_duration`][(c).] is `None`) """ animation_curve_reverse_duration: Optional[ft.DurationValue] = field( @@ -809,7 +809,7 @@ class KeyboardConfiguration: [`AnimationCurve.EASE_IN`][flet.AnimationCurve.EASE_IN]) portion of the animation occuring after a key up event. - Set to `None` to use [`animation_curve_duration`][..]. + Set to `None` to use [`animation_curve_duration`][(c).]. """ animation_curve_curve: AnimationCurve = AnimationCurve.EASE_IN_OUT @@ -872,7 +872,7 @@ class KeyboardConfiguration: Must be greater than 0 and less than or equal to 1. To disable leaping, or change the maximum length of the key press - that will trigger a leap, see [`perform_leap_trigger_duration`][..]. + that will trigger a leap, see [`perform_leap_trigger_duration`][(c).]. """ max_rotate_velocity: ft.Number = 3 @@ -896,7 +896,7 @@ class KeyboardConfiguration: The amount to scale the panning offset velocity by during a leap animation. The larger the number, the larger the movement during a leap. - To change the duration of a leap, see [`leap_max_of_curve_component`][..]. + To change the duration of a leap, see [`leap_max_of_curve_component`][(c).]. """ rotate_leap_velocity_multiplier: ft.Number = 3 @@ -904,9 +904,9 @@ class KeyboardConfiguration: The amount to scale the rotation velocity by during a leap animation The larger the number, the larger the rotation difference during a leap. - To change the duration of a leap, see [`leap_max_of_curve_component`][..]. + To change the duration of a leap, see [`leap_max_of_curve_component`][(c).]. - This may cause the pan velocity to exceed [`max_rotate_velocity`][..]. + This may cause the pan velocity to exceed [`max_rotate_velocity`][(c).]. """ zoom_leap_velocity_multiplier: ft.Number = 3 @@ -914,9 +914,9 @@ class KeyboardConfiguration: The amount to scale the zooming velocity by during a leap animation. The larger the number, the larger the zoom difference during a leap. To - change the duration of a leap, see [`leap_max_of_curve_component`][..]. + change the duration of a leap, see [`leap_max_of_curve_component`][(c).]. - This may cause the pan velocity to exceed [`max_zoom_velocity`][..]. + This may cause the pan velocity to exceed [`max_zoom_velocity`][(c).]. """ perform_leap_trigger_duration: Optional[ft.DurationValue] = field( @@ -926,9 +926,9 @@ class KeyboardConfiguration: Maximum duration between the key down and key up events of an animation which will trigger a 'leap'. - To customize the leap itself, see the [`leap_max_of_curve_component`][..] & - `*leap_velocity_multiplier` ([`zoom_leap_velocity_multiplier`][..], - [`pan_leap_velocity_multiplier`][..] and [`rotate_leap_velocity_multiplier`][..]) + To customize the leap itself, see the [`leap_max_of_curve_component`][(c).] & + `*leap_velocity_multiplier` ([`zoom_leap_velocity_multiplier`][(c).], + [`pan_leap_velocity_multiplier`][(c).] and [`rotate_leap_velocity_multiplier`][(c).]) properties. Set to `None` to disable leaping. diff --git a/sdk/python/packages/flet-permission-handler/src/flet_permission_handler/types.py b/sdk/python/packages/flet-permission-handler/src/flet_permission_handler/types.py index a4f918e501..584133ec73 100644 --- a/sdk/python/packages/flet-permission-handler/src/flet_permission_handler/types.py +++ b/sdk/python/packages/flet-permission-handler/src/flet_permission_handler/types.py @@ -183,7 +183,7 @@ class Permission(Enum): Permission for writing to the device's calendar. On iOS 16 and lower, this permission is identical to - [`CALENDAR_FULL_ACCESS`][..]. + [`CALENDAR_FULL_ACCESS`][(c).]. """ CAMERA = "camera" @@ -376,9 +376,9 @@ class Permission(Enum): Info: - Android: Requests access to microphone - (identical to requesting [`MICROPHONE`][..]). + (identical to requesting [`MICROPHONE`][(c).]). - iOS: Requests speech access (different from requesting - [`MICROPHONE`][..]). + [`MICROPHONE`][(c).]). """ STORAGE = "storage" diff --git a/sdk/python/packages/flet-video/src/flet_video/types.py b/sdk/python/packages/flet-video/src/flet_video/types.py index 4661adb7ea..89b68c7a63 100644 --- a/sdk/python/packages/flet-video/src/flet_video/types.py +++ b/sdk/python/packages/flet-video/src/flet_video/types.py @@ -87,7 +87,7 @@ class VideoConfiguration: scale: ft.Number = 1.0 """ The scale for the video output. - Specifying this option will cause [`width`][..] & [`height`][..] to be ignored. + Specifying this option will cause [`width`][(c).] & [`height`][(c).] to be ignored. """ diff --git a/sdk/python/packages/flet-video/src/flet_video/video.py b/sdk/python/packages/flet-video/src/flet_video/video.py index 606a6bfa27..d94df48d25 100644 --- a/sdk/python/packages/flet-video/src/flet_video/video.py +++ b/sdk/python/packages/flet-video/src/flet_video/video.py @@ -119,7 +119,7 @@ class Video(ft.LayoutControl): resume_upon_entering_foreground_mode: bool = False """ Whether to resume the video when application enters foreground mode. - Has effect only if [`pause_upon_entering_background_mode`][..] is also set to + Has effect only if [`pause_upon_entering_background_mode`][(c).] is also set to `True`. """ @@ -201,17 +201,17 @@ async def stop(self): await self._invoke_method("stop") async def next(self): - """Jumps to the next `VideoMedia` in the [`playlist`][..].""" + """Jumps to the next `VideoMedia` in the [`playlist`][(c).].""" await self._invoke_method("next") async def previous(self): - """Jumps to the previous `VideoMedia` in the [`playlist`][..].""" + """Jumps to the previous `VideoMedia` in the [`playlist`][(c).].""" await self._invoke_method("previous") async def seek(self, position: ft.DurationValue): """ Seeks the currently playing `VideoMedia` from the - [`playlist`][..] at the specified `position`. + [`playlist`][(c).] at the specified `position`. """ await self._invoke_method( "seek", @@ -221,7 +221,7 @@ async def seek(self, position: ft.DurationValue): async def jump_to(self, media_index: int): """ Jumps to the `VideoMedia` at the specified `media_index` - in the [`playlist`][..]. + in the [`playlist`][(c).]. """ assert self.playlist[media_index], "media_index is out of range" if media_index < 0: diff --git a/sdk/python/packages/flet/src/flet/controls/base_control.py b/sdk/python/packages/flet/src/flet/controls/base_control.py index 69d1e7633c..d805f5abf3 100644 --- a/sdk/python/packages/flet/src/flet/controls/base_control.py +++ b/sdk/python/packages/flet/src/flet/controls/base_control.py @@ -233,9 +233,10 @@ def will_unmount(self): 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 @@ async def _invoke_method( 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 @@ async def _trigger_event(self, event_name: str, event_data: Any): 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 diff --git a/sdk/python/packages/flet/src/flet/controls/base_page.py b/sdk/python/packages/flet/src/flet/controls/base_page.py index 0a1603d171..508dfd289c 100644 --- a/sdk/python/packages/flet/src/flet/controls/base_page.py +++ b/sdk/python/packages/flet/src/flet/controls/base_page.py @@ -231,7 +231,8 @@ def page_resize(e): _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: diff --git a/sdk/python/packages/flet/src/flet/controls/border.py b/sdk/python/packages/flet/src/flet/controls/border.py index 1854a3b201..1a03ffabd7 100644 --- a/sdk/python/packages/flet/src/flet/controls/border.py +++ b/sdk/python/packages/flet/src/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 diff --git a/sdk/python/packages/flet/src/flet/controls/box.py b/sdk/python/packages/flet/src/flet/controls/box.py index 642f1df17f..d208d2d7a0 100644 --- a/sdk/python/packages/flet/src/flet/controls/box.py +++ b/sdk/python/packages/flet/src/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, diff --git a/sdk/python/packages/flet/src/flet/controls/colors.py b/sdk/python/packages/flet/src/flet/controls/colors.py index dcd99e8e1a..35de21a985 100644 --- a/sdk/python/packages/flet/src/flet/controls/colors.py +++ b/sdk/python/packages/flet/src/flet/controls/colors.py @@ -120,11 +120,12 @@ def with_opacity(opacity: Union[int, float], color: "ColorValue") -> str: '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}" diff --git a/sdk/python/packages/flet/src/flet/controls/context.py b/sdk/python/packages/flet/src/flet/controls/context.py index 1043a99d4f..e31053bc86 100644 --- a/sdk/python/packages/flet/src/flet/controls/context.py +++ b/sdk/python/packages/flet/src/flet/controls/context.py @@ -32,7 +32,7 @@ def page(self) -> "Page": 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: diff --git a/sdk/python/packages/flet/src/flet/controls/control_event.py b/sdk/python/packages/flet/src/flet/controls/control_event.py index 3942c6d430..2e729d86c9 100644 --- a/sdk/python/packages/flet/src/flet/controls/control_event.py +++ b/sdk/python/packages/flet/src/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 diff --git a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_colors.py b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_colors.py index c04ebdb2ec..7fd544120f 100644 --- a/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_colors.py +++ b/sdk/python/packages/flet/src/flet/controls/cupertino/cupertino_colors.py @@ -19,7 +19,7 @@ ``` 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 @@ def with_opacity(opacity: Union[int, float], color: "ColorValue") -> str: 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}" diff --git a/sdk/python/packages/flet/src/flet/controls/material/dropdown.py b/sdk/python/packages/flet/src/flet/controls/material/dropdown.py index ff8c4e4648..b41fc39979 100644 --- a/sdk/python/packages/flet/src/flet/controls/material/dropdown.py +++ b/sdk/python/packages/flet/src/flet/controls/material/dropdown.py @@ -29,7 +29,7 @@ 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 diff --git a/sdk/python/packages/flet/src/flet/controls/material/dropdownm2.py b/sdk/python/packages/flet/src/flet/controls/material/dropdownm2.py index 0b3f9f5de3..a32bdb0835 100644 --- a/sdk/python/packages/flet/src/flet/controls/material/dropdownm2.py +++ b/sdk/python/packages/flet/src/flet/controls/material/dropdownm2.py @@ -19,8 +19,8 @@ @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") diff --git a/sdk/python/packages/flet/src/flet/controls/material/expansion_panel.py b/sdk/python/packages/flet/src/flet/controls/material/expansion_panel.py index d1afd95d45..23829667d4 100644 --- a/sdk/python/packages/flet/src/flet/controls/material/expansion_panel.py +++ b/sdk/python/packages/flet/src/flet/controls/material/expansion_panel.py @@ -20,23 +20,6 @@ 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 @@ -64,13 +47,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 @@ -88,40 +70,25 @@ 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) """ - 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 or equal to zero. """ expanded_header_padding: PaddingValue = field( @@ -133,23 +100,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") diff --git a/sdk/python/packages/flet/src/flet/controls/material/menu_bar.py b/sdk/python/packages/flet/src/flet/controls/material/menu_bar.py index 63befb24a6..43ccb9c94c 100644 --- a/sdk/python/packages/flet/src/flet/controls/material/menu_bar.py +++ b/sdk/python/packages/flet/src/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 at least one control in this list is not 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") diff --git a/sdk/python/packages/flet/src/flet/controls/services/shared_preferences.py b/sdk/python/packages/flet/src/flet/controls/services/shared_preferences.py index 623e643da7..9ae5796c3c 100644 --- a/sdk/python/packages/flet/src/flet/controls/services/shared_preferences.py +++ b/sdk/python/packages/flet/src/flet/controls/services/shared_preferences.py @@ -9,7 +9,8 @@ @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): diff --git a/sdk/python/packages/flet/src/flet/pubsub/pubsub_hub.py b/sdk/python/packages/flet/src/flet/pubsub/pubsub_hub.py index e1eb448ca4..8f2c931db2 100644 --- a/sdk/python/packages/flet/src/flet/pubsub/pubsub_hub.py +++ b/sdk/python/packages/flet/src/flet/pubsub/pubsub_hub.py @@ -147,7 +147,8 @@ def __unsubscribe_topic(self, session_id: str, topic: str): 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) diff --git a/sdk/python/packages/flet/src/flet/testing/flet_test_app.py b/sdk/python/packages/flet/src/flet/testing/flet_test_app.py index 2cf7e13d4c..6de2a8ad93 100644 --- a/sdk/python/packages/flet/src/flet/testing/flet_test_app.py +++ b/sdk/python/packages/flet/src/flet/testing/flet_test_app.py @@ -135,7 +135,8 @@ def page(self) -> ft.Page: """ 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 @@ -144,7 +145,8 @@ def tester(self) -> Tester: 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): @@ -329,10 +331,13 @@ def assert_screenshot( 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 @@ -364,9 +369,7 @@ def assert_screenshot( ) with open(actual_image_path, "bw") as f: f.write(screenshot) - assert similarity > similarity_threshold, ( - f"{name} screenshots are not identical" - ) + raise ValueError(f"{name} screenshots are not identical") def _load_image_from_file(self, file_name): return Image.open(file_name) diff --git a/sdk/python/packages/flet/src/flet/utils/pip.py b/sdk/python/packages/flet/src/flet/utils/pip.py index 9bcbccbc09..d41a494155 100644 --- a/sdk/python/packages/flet/src/flet/utils/pip.py +++ b/sdk/python/packages/flet/src/flet/utils/pip.py @@ -28,26 +28,30 @@ def install_flet_package(name: str): def ensure_flet_desktop_package_installed(): try: - import flet.version import flet_desktop.version - assert ( - not flet_desktop.version.version - or flet_desktop.version.version == flet.version.version - ) + import flet.version + + if ( + flet_desktop.version.version + and flet_desktop.version.version != flet.version.version + ): + raise RuntimeError("flet-desktop version mismatch") except: install_flet_package("flet-desktop") def ensure_flet_web_package_installed(): try: - import flet.version import flet_web.version - assert ( - not flet_web.version.version - or flet_web.version.version == flet.version.version - ) + import flet.version + + if ( + flet_web.version.version + and flet_web.version.version != flet.version.version + ): + raise RuntimeError("flet-web version mismatch") except: install_flet_package("flet-web") @@ -57,9 +61,10 @@ def ensure_flet_cli_package_installed(): import flet.version import flet_cli.version - assert ( - not flet_cli.version.version - or flet_cli.version.version == flet.version.version - ) + if ( + flet_cli.version.version + and flet_cli.version.version != flet.version.version + ): + raise RuntimeError("flet-cli version mismatch") except: install_flet_package("flet-cli") From 2efd1702d692b395555103ebcb942212c08471cf Mon Sep 17 00:00:00 2001 From: ndonkoHenri Date: Fri, 17 Oct 2025 01:19:03 +0200 Subject: [PATCH 2/6] Replace assertions with appropriate exceptions for better error handling. --- .../packages/flet-map/src/flet_map/map.py | 13 ++- .../flet-map/src/flet_map/marker_layer.py | 49 +++++----- .../flet-map/src/flet_map/polygon_layer.py | 22 +++-- .../flet-map/src/flet_map/polyline_layer.py | 27 +++--- .../src/flet_map/source_attribution.py | 12 +-- .../flet-map/src/flet_map/tile_layer.py | 96 ++++++++++--------- .../packages/flet-map/src/flet_map/types.py | 79 +++++++++------ .../flet-video/src/flet_video/video.py | 22 +++-- .../flet-web/src/flet_web/fastapi/flet_app.py | 5 +- .../flet-webview/src/flet_webview/webview.py | 3 +- 10 files changed, 179 insertions(+), 149 deletions(-) diff --git a/sdk/python/packages/flet-map/src/flet_map/map.py b/sdk/python/packages/flet-map/src/flet_map/map.py index aa6973f22b..f4c8edba9e 100644 --- a/sdk/python/packages/flet-map/src/flet_map/map.py +++ b/sdk/python/packages/flet-map/src/flet_map/map.py @@ -100,7 +100,7 @@ class Map(ft.LayoutControl): initial_camera_fit: Optional[CameraFit] = None """ Defines the visible bounds when the map is first loaded. - Takes precedence over [`initial_center`][..]/[`initial_zoom`][..]. + Takes precedence over [`initial_center`][(c).]/[`initial_zoom`][(c).]. """ on_init: Optional[ft.ControlEventHandler["Map"]] = None @@ -244,7 +244,7 @@ async def zoom_out( Zooms out by one zoom-level from the current one. Args: - animation_curve: The curve of the animation. If None (the default), + animation_curve: The curve of the animation. If `None` (the default), [`Map.animation_curve`][(p).] will be used. animation_duration: The duration of the animation. If None (the default), [`Map.animation_duration`][(p).] will be used. @@ -272,7 +272,7 @@ async def zoom_to( Args: zoom: The zoom level to zoom to. - animation_curve: The curve of the animation. If None (the default), + animation_curve: The curve of the animation. If `None` (the default), [`Map.animation_curve`][(p).] will be used. animation_duration: The duration of the animation. If None (the default), [`Map.animation_duration`][(p).] will be used. @@ -316,11 +316,10 @@ async def move_to( ongoing map-animations before starting this new one. Raises: - AssertionError: If `zoom` is not `None` and is negative. + ValueError: If `zoom` is not `None` and is negative. """ - assert zoom is None or zoom >= 0, ( - f"zoom must be greater than or equal to zero, got {zoom}" - ) + if zoom is not None and zoom < 0: + raise ValueError(f"zoom must be greater than or equal to zero, got {zoom}") await self._invoke_method( method_name="move_to", arguments={ diff --git a/sdk/python/packages/flet-map/src/flet_map/marker_layer.py b/sdk/python/packages/flet-map/src/flet_map/marker_layer.py index e9aa6a9738..f16281af3f 100644 --- a/sdk/python/packages/flet-map/src/flet_map/marker_layer.py +++ b/sdk/python/packages/flet-map/src/flet_map/marker_layer.py @@ -13,18 +13,14 @@ class Marker(ft.Control): """ A marker displayed on the Map at the specified location through the [`MarkerLayer`][(p).]. - - Raises: - AssertionError: If the [`content`][(c).] is not visible, or - if [`height`][(c).] or [`width`][(c).] are negative. """ content: ft.Control """ - The content to be displayed at [`coordinates`][..]. + The content to be displayed at [`coordinates`][(c).]. - Note: - Must be provided and visible. + Raises: + ValueError: If it is not [`visible`][(c).]. """ coordinates: MapLatitudeLongitude @@ -32,7 +28,7 @@ class Marker(ft.Control): The coordinates of the marker. This will be the center of the marker, - if [`alignment`][..] is [`Alignment.CENTER`][flet.Alignment.CENTER]. + if [`alignment`][(c).] is [`Alignment.CENTER`][flet.Alignment.]. """ rotate: Optional[bool] = None @@ -51,36 +47,39 @@ class Marker(ft.Control): height: ft.Number = 30.0 """ - The height of the [`content`][..] Control. + The height of the [`content`][(c).] Control. - Note: - Must be non-negative. + Raises: + ValueError: If it is less than `0.0`. """ width: ft.Number = 30.0 """ - The width of the [`content`][..] Control. + The width of the [`content`][(c).] Control. - Note: - Must be non-negative. + Raises: + ValueError: If it is less than `0.0`. """ alignment: Optional[ft.Alignment] = None """ - Alignment of the marker relative to the normal center at [`coordinates`][..]. + Alignment of the marker relative to the normal center at [`coordinates`][(c).]. Defaults to the value of the parent [`MarkerLayer.alignment`][(p).]. """ def before_update(self): super().before_update() - assert self.content.visible, "content must be visible" - assert self.height >= 0, ( - f"height must be greater than or equal to 0, got {self.height}" - ) - assert self.width >= 0, ( - f"width must be greater than or equal to 0, got {self.width}" - ) + if not self.content.visible: + raise ValueError("content must be visible") + if self.height < 0: + raise ValueError( + f"height must be greater than or equal to 0, got {self.height}" + ) + if self.width < 0: + raise ValueError( + f"width must be greater than or equal to 0, got {self.width}" + ) @ft.control("MarkerLayer") @@ -91,7 +90,7 @@ class MarkerLayer(MapLayer): markers: list[Marker] """ - A list of [`Marker`][(m).]s to display. + A list of [`Marker`][(p).]s to display. """ alignment: Optional[ft.Alignment] = field( @@ -99,11 +98,11 @@ class MarkerLayer(MapLayer): ) """ The alignment of each marker relative to its normal center at - [`Marker.coordinates`][(m).]. + [`Marker.coordinates`][(p).]. """ rotate: bool = False """ - Whether to counter-rotate `markers` to the map's rotation, + Whether to counter-rotate [`markers`][(c).] to the map's rotation, to keep a fixed orientation. """ diff --git a/sdk/python/packages/flet-map/src/flet_map/polygon_layer.py b/sdk/python/packages/flet-map/src/flet_map/polygon_layer.py index 240a0fedc8..2e9843a6b8 100644 --- a/sdk/python/packages/flet-map/src/flet_map/polygon_layer.py +++ b/sdk/python/packages/flet-map/src/flet_map/polygon_layer.py @@ -22,10 +22,11 @@ class PolygonMarker(ft.Control): """ An optional label for this polygon. - Note: specifying a label will reduce performance, as the internal - canvas must be drawn to and 'saved' more frequently to ensure the proper - stacking order is maintained. This can be avoided, potentially at the - expense of appearance, by setting [`PolygonLayer.draw_labels_last`][(p).]. + Note: + Specifying a label will reduce performance, as the internal + canvas must be drawn to and 'saved' more frequently to ensure the proper + stacking order is maintained. This can be avoided, potentially at the + expense of appearance, by setting [`PolygonLayer.draw_labels_last`][(p).]. """ label_text_style: Optional[ft.TextStyle] = None @@ -47,8 +48,8 @@ class PolygonMarker(ft.Control): """ The width of the border outline. - Note: - Must be non-negative. + Raises: + ValueError: If it is less than `0.0`. """ disable_holes_border: bool = False @@ -74,10 +75,11 @@ class PolygonMarker(ft.Control): def before_update(self): super().before_update() - assert self.border_stroke_width >= 0, ( - f"border_stroke_width must be greater than or equal to 0, " - f"got {self.border_stroke_width}" - ) + if self.border_stroke_width < 0: + raise ValueError( + "border_stroke_width must be greater than or equal to 0, " + f"got {self.border_stroke_width}" + ) @ft.control("PolygonLayer") diff --git a/sdk/python/packages/flet-map/src/flet_map/polyline_layer.py b/sdk/python/packages/flet-map/src/flet_map/polyline_layer.py index 7a515ac19c..f2f27090e1 100644 --- a/sdk/python/packages/flet-map/src/flet_map/polyline_layer.py +++ b/sdk/python/packages/flet-map/src/flet_map/polyline_layer.py @@ -21,7 +21,7 @@ class PolylineMarker(ft.Control): colors_stop: Optional[list[ft.Number]] = None """ - The stops for the [`gradient_colors`][..]. + The stops for the [`gradient_colors`][(c).]. """ gradient_colors: Optional[list[ft.ColorValue]] = None @@ -43,16 +43,16 @@ class PolylineMarker(ft.Control): """ The width of the stroke. - Note: - Must be non-negative. + Raises: + ValueError: If it is less than `0.0`. """ border_stroke_width: ft.Number = 0.0 """ The width of the stroke with of the line border. - Note: - Must be non-negative. + Raises: + ValueError: If it is less than `0.0`. """ use_stroke_width_in_meter: bool = False @@ -78,13 +78,16 @@ class PolylineMarker(ft.Control): def before_update(self): super().before_update() - assert self.border_stroke_width >= 0, ( - f"border_stroke_width must be greater than or equal to 0, " - f"got {self.border_stroke_width}" - ) - assert self.stroke_width >= 0, ( - f"stroke_width must be greater than or equal to 0, got {self.stroke_width}" - ) + if self.border_stroke_width < 0: + raise ValueError( + "border_stroke_width must be greater than or equal to 0, " + f"got {self.border_stroke_width}" + ) + if self.stroke_width < 0: + raise ValueError( + f"stroke_width must be greater than or equal to 0, " + f"got {self.stroke_width}" + ) @ft.control("PolylineLayer") diff --git a/sdk/python/packages/flet-map/src/flet_map/source_attribution.py b/sdk/python/packages/flet-map/src/flet_map/source_attribution.py index 146e0dddb1..622b862962 100644 --- a/sdk/python/packages/flet-map/src/flet_map/source_attribution.py +++ b/sdk/python/packages/flet-map/src/flet_map/source_attribution.py @@ -23,17 +23,14 @@ class ImageSourceAttribution(SourceAttribution): open/close icon of a [`RichAttribution`][(p).] control. For it to be displayed, it should be part of a [`RichAttribution.attributions`][(p).] list. - - Raises: - AssertionError: If the [`image`][(c).] is not visible. """ image: ft.Image """ - The `Image` to be displayed. + The [`Image`][flet.] to be displayed. - Note: - Must be provided and visible. + Raises: + ValueError: If the image is not visible. """ height: ft.Number = 24.0 @@ -51,7 +48,8 @@ class ImageSourceAttribution(SourceAttribution): def before_update(self): super().before_update() - assert self.image.visible, "image must be visible" + if not self.image.visible: + raise ValueError("image must be visible") @ft.control("TextSourceAttribution") diff --git a/sdk/python/packages/flet-map/src/flet_map/tile_layer.py b/sdk/python/packages/flet-map/src/flet_map/tile_layer.py index d73ae23198..7d1ddef5ae 100644 --- a/sdk/python/packages/flet-map/src/flet_map/tile_layer.py +++ b/sdk/python/packages/flet-map/src/flet_map/tile_layer.py @@ -22,12 +22,6 @@ class TileLayer(MapLayer): Typically the first layer to be added to a [`Map`][(p).], as it provides the tiles on which other layers are displayed. - - Raises: - AssertionError: If one or more of the following is negative: - [`tile_size`][(c).], [`min_native_zoom`][(c).], - [`max_native_zoom`][(c).], [`zoom_offset`][(c).], - [`max_zoom`][(c).], [`min_zoom`][(c).] """ url_template: str @@ -39,21 +33,21 @@ class TileLayer(MapLayer): fallback_url: Optional[str] = None """ Fallback URL template, used if an error occurs when fetching tiles from - the [`url_template`][..]. + the [`url_template`][(c).]. Note that specifying this (non-none) will result in tiles not being cached - in memory. This is to avoid issues where the [`url_template`][..] is flaky, to + in memory. This is to avoid issues where the [`url_template`][(c).] is flaky, to prevent different tilesets being displayed at the same time. It is expected that this follows the same retina support behaviour - as [`url_template`][..]. + as [`url_template`][(c).]. """ subdomains: list[str] = field(default_factory=lambda: ["a", "b", "c"]) """ List of subdomains used in the URL template. - For example, if [`subdomains`][..] is set to `["a", "b", "c"]` and the + For example, if [`subdomains`][(c).] is set to `["a", "b", "c"]` and the `url_template` is `"https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"`, the resulting tile URLs will be: @@ -73,8 +67,8 @@ class TileLayer(MapLayer): The size in pixels of each tile image. Should be a positive power of 2. - Note: - Must be greater than or equal to `0.0`. + Raises: + ValueError: If it is less than `0.0`. """ min_native_zoom: int = 0 @@ -87,8 +81,8 @@ class TileLayer(MapLayer): This should usually be 0 (as default), as most tile sources will support zoom levels onwards from this. - Note: - Must be greater than or equal to `0.0`. + Raises: + ValueError: If it is less than `0.0`. """ max_native_zoom: int = 19 @@ -101,8 +95,8 @@ class TileLayer(MapLayer): Most tile servers support up to zoom level `19`, which is the default. Otherwise, this should be specified. - Note: - Must be greater than or equal to `0.0`. + Raises: + ValueError: If it is less than `0.0`. """ zoom_reverse: bool = False @@ -115,8 +109,8 @@ class TileLayer(MapLayer): """ The zoom number used in tile URLs will be offset with this value. - Note: - Must be greater than or equal to `0.0`. + Raises: + ValueError: If it is less than `0.0`. """ keep_buffer: int = 2 @@ -148,7 +142,7 @@ class TileLayer(MapLayer): additional_options: dict[str, str] = field(default_factory=dict) """ - Static information that should replace placeholders in the [`url_template`][..]. + Static information that should replace placeholders in the [`url_template`][(c).]. Applying API keys, for example, is a good usecase of this parameter. Example: @@ -159,7 +153,7 @@ class TileLayer(MapLayer): 'accessToken': '', 'id': 'mapbox.streets', }, - ), + ) ``` """ @@ -169,29 +163,30 @@ class TileLayer(MapLayer): The main usage for this property is to display a different `TileLayer` when zoomed far in. - Prefer [`max_native_zoom`][..] for setting the maximum zoom level supported by the + Prefer [`max_native_zoom`][(c).] for setting the maximum zoom level supported by the tile source. Typically set to infinity so that there are tiles always displayed. - Note: - Must be greater than or equal to `0.0`. + Raises: + ValueError: If it is less than `0.0`. """ min_zoom: ft.Number = 0.0 """ The minimum zoom level at which this layer is displayed (inclusive). + Typically `0.0`. - Note: - Must be greater than or equal to `0.0`. + Raises: + ValueError: If it is less than `0.0`. """ error_image_src: Optional[str] = None """ The source of the tile image to show in place of the tile that failed to load. - See [`on_image_error`][..] property for details on the error. + See [`on_image_error`][(c).] property for details on the error. """ evict_error_tile_strategy: Optional[TileLayerEvictErrorTileStrategy] = ( @@ -217,29 +212,36 @@ class TileLayer(MapLayer): """ Fires if an error occurs when fetching the tiles. - Event handler argument [`data`][flet.Event.data] property contains + Event handler argument [`data`][flet.Event.] property contains information about the error. """ def before_update(self): super().before_update() - assert self.tile_size >= 0, ( - f"tile_size must be greater than or equal to 0, got {self.tile_size}" - ) - assert self.min_native_zoom >= 0, ( - f"min_native_zoom must be greater than or equal to 0, " - f"got {self.min_native_zoom}" - ) - assert self.max_native_zoom >= 0, ( - f"max_native_zoom must be greater than or equal to 0, " - f"got {self.max_native_zoom}" - ) - assert self.zoom_offset >= 0, ( - f"zoom_offset must be greater than or equal to 0, got {self.zoom_offset}" - ) - assert self.max_zoom >= 0, ( - f"max_zoom must be greater than or equal to 0, got {self.max_zoom}" - ) - assert self.min_zoom >= 0, ( - f"min_zoom must be greater than or equal to 0, got {self.min_zoom}" - ) + if self.tile_size < 0: + raise ValueError( + f"tile_size must be greater than or equal to 0, got {self.tile_size}" + ) + if self.min_native_zoom < 0: + raise ValueError( + "min_native_zoom must be greater than or equal to 0, " + f"got {self.min_native_zoom}" + ) + if self.max_native_zoom < 0: + raise ValueError( + "max_native_zoom must be greater than or equal to 0, " + f"got {self.max_native_zoom}" + ) + if self.zoom_offset < 0: + raise ValueError( + f"zoom_offset must be greater than or equal to 0, " + f"got {self.zoom_offset}" + ) + if self.max_zoom < 0: + raise ValueError( + f"max_zoom must be greater than or equal to 0, got {self.max_zoom}" + ) + if self.min_zoom < 0: + raise ValueError( + f"min_zoom must be greater than or equal to 0, got {self.min_zoom}" + ) diff --git a/sdk/python/packages/flet-map/src/flet_map/types.py b/sdk/python/packages/flet-map/src/flet_map/types.py index 56e22f1495..30e36b8930 100644 --- a/sdk/python/packages/flet-map/src/flet_map/types.py +++ b/sdk/python/packages/flet-map/src/flet_map/types.py @@ -177,7 +177,7 @@ class DashedStrokePattern(StrokePattern): A stroke pattern of alternating dashes and gaps, defined by [`segments`][(c).]. Raises: - AssertionError: If [`segments`][(c).] does not contain at least two items, + ValueError: If [`segments`][(c).] does not contain at least two items, or has an odd length. """ @@ -185,9 +185,11 @@ class DashedStrokePattern(StrokePattern): """ A list of alternating dash and gap lengths, in pixels. - Note: - Must contain at least two items, and have an even length. + Raises: + ValueError: If the list does not contain at least two items, + or if its length is not even. """ + pattern_fit: PatternFit = PatternFit.SCALE_UP """ Determines how this stroke pattern should be fit to a line when their lengths @@ -195,10 +197,12 @@ class DashedStrokePattern(StrokePattern): """ def __post_init__(self): - assert len(self.segments) >= 2, ( - f"segments must contain at least two items, got {len(self.segments)}" - ) - assert len(self.segments) % 2 == 0, "segments must have an even length" + if len(self.segments) < 2: + raise ValueError( + f"segments must contain at least two items, got {len(self.segments)}" + ) + if len(self.segments) % 2 != 0: + raise ValueError("segments must have an even length") self._type = "dashed" @@ -206,9 +210,6 @@ def __post_init__(self): class DottedStrokePattern(StrokePattern): """ A stroke pattern of circular dots, spaced with [`spacing_factor`][(c).]. - - Raises: - AssertionError: If [`spacing_factor`][(c).] is negative. """ spacing_factor: ft.Number = 1.5 @@ -220,9 +221,12 @@ class DottedStrokePattern(StrokePattern): May also be scaled by the use of [`PatternFit.SCALE_UP`][(p).]. + Raises: + ValueError: If it is less than or equal to zero. Note: Must be non-negative. """ + pattern_fit: PatternFit = PatternFit.SCALE_UP """ Determines how this stroke pattern should be fit to a line when their @@ -230,10 +234,11 @@ class DottedStrokePattern(StrokePattern): """ def __post_init__(self): - assert self.spacing_factor > 0, ( - f"spacing_factor must be greater than or equal to 0.0, " - f"got {self.spacing_factor}" - ) + if self.spacing_factor <= 0: + raise ValueError( + "spacing_factor must be greater than or equal to 0.0, " + f"got {self.spacing_factor}" + ) self._type = "dotted" @@ -620,7 +625,7 @@ class CameraFit: depending on which one was provided. Raises: - AssertionError: If both [`bounds`][(c).] and [`coordinates`][(c).] + ValueError: If both [`bounds`][(c).] and [`coordinates`][(c).] are `None` or not `None`. """ @@ -664,9 +669,13 @@ class CameraFit: """ def __post_init__(self): - assert (self.bounds and not self.coordinates) or ( - self.coordinates and not self.bounds - ), "only one of bounds or coordinates must be provided, not both" + if not ( + (self.bounds and not self.coordinates) + or (self.coordinates and not self.bounds) + ): + raise ValueError( + "only one of bounds or coordinates must be provided, not both" + ) @dataclass @@ -724,12 +733,16 @@ class InstantaneousTileDisplay(TileDisplay): opacity: ft.Number = 1.0 """ The optional opacity of the tile. + + Raises: + ValueError: If its value is not between `0.0` and `1.0` inclusive. """ def __post_init__(self): - assert 0.0 <= self.opacity <= 1.0, ( - f"opacity must be between 0.0 and 1.0 inclusive, got {self.opacity}" - ) + if not (0.0 <= self.opacity <= 1.0): + raise ValueError( + f"opacity must be between 0.0 and 1.0 inclusive, got {self.opacity}" + ) self._type = "instantaneous" @@ -747,22 +760,30 @@ class FadeInTileDisplay(TileDisplay): start_opacity: ft.Number = 0.0 """ Opacity start value when a tile is faded in. + + Raises: + ValueError: If its value is not between `0.0` and `1.0` inclusive. """ reload_start_opacity: ft.Number = 0.0 """ Opacity start value when a tile is reloaded. + + Raises: + ValueError: If its value is not between `0.0` and `1.0` inclusive. """ def __post_init__(self): - assert 0.0 <= self.start_opacity <= 1.0, ( - f"start_opacity must be between 0.0 and 1.0 inclusive, " - f"got {self.start_opacity}" - ) - assert 0.0 <= self.reload_start_opacity <= 1.0, ( - f"reload_start_opacity must be between 0.0 and 1.0 inclusive, " - f"got {self.reload_start_opacity}" - ) + if not (0.0 <= self.start_opacity <= 1.0): + raise ValueError( + "start_opacity must be between 0.0 and 1.0 inclusive, " + f"got {self.start_opacity}" + ) + if not (0.0 <= self.reload_start_opacity <= 1.0): + raise ValueError( + "reload_start_opacity must be between 0.0 and 1.0 inclusive, " + f"got {self.reload_start_opacity}" + ) self._type = "fadein" diff --git a/sdk/python/packages/flet-video/src/flet_video/video.py b/sdk/python/packages/flet-video/src/flet_video/video.py index d94df48d25..d501fa58eb 100644 --- a/sdk/python/packages/flet-video/src/flet_video/video.py +++ b/sdk/python/packages/flet-video/src/flet_video/video.py @@ -86,8 +86,7 @@ class Video(ft.LayoutControl): An exception will be raised if the value is outside this range. Raises: - AssertionError: If the [`volume`][(c).] is not between - `0.0` and `100.0` (inclusive). + ValueError: If its value is not between `0.0` and `100.0` (inclusive). """ playback_rate: ft.Number = 1.0 @@ -177,9 +176,10 @@ class Video(ft.LayoutControl): def before_update(self): super().before_update() - assert 0 <= self.volume <= 100, ( - f"volume must be between 0 and 100 inclusive, got {self.volume}" - ) + if not (0 <= self.volume <= 100): + raise ValueError( + f"volume must be between 0 and 100 inclusive, got {self.volume}" + ) async def play(self): """Starts playing the video.""" @@ -223,7 +223,8 @@ async def jump_to(self, media_index: int): Jumps to the `VideoMedia` at the specified `media_index` in the [`playlist`][(c).]. """ - assert self.playlist[media_index], "media_index is out of range" + if not (-len(self.playlist) <= media_index < len(self.playlist)): + raise IndexError("media_index is out of range") if media_index < 0: # dart doesn't support negative indexes media_index = len(self.playlist) + media_index @@ -234,7 +235,8 @@ async def jump_to(self, media_index: int): async def playlist_add(self, media: VideoMedia): """Appends/Adds the provided `media` to the `playlist`.""" - assert media.resource, "media has no resource" + if not media.resource: + raise ValueError("media has no resource") await self._invoke_method( method_name="playlist_add", arguments={"media": media}, @@ -243,7 +245,11 @@ async def playlist_add(self, media: VideoMedia): async def playlist_remove(self, media_index: int): """Removes the provided `media` from the `playlist`.""" - assert self.playlist[media_index], "index out of range" + playlist_length = len(self.playlist) + if not (-playlist_length <= media_index < playlist_length): + raise IndexError("media_index is out of range") + if media_index < 0: + media_index = playlist_length + media_index await self._invoke_method( method_name="playlist_remove", arguments={"media_index": media_index}, diff --git a/sdk/python/packages/flet-web/src/flet_web/fastapi/flet_app.py b/sdk/python/packages/flet-web/src/flet_web/fastapi/flet_app.py index 951b0d9870..d888ee2ac0 100644 --- a/sdk/python/packages/flet-web/src/flet_web/fastapi/flet_app.py +++ b/sdk/python/packages/flet-web/src/flet_web/fastapi/flet_app.py @@ -340,9 +340,8 @@ def send_message(self, message: ClientMessage): self.__send_queue.put_nowait(m) def get_upload_url(self, file_name: str, expires: int) -> str: - assert self.__upload_endpoint_path, ( - "upload_path should be specified to enable uploads" - ) + if not self.__upload_endpoint_path: + raise RuntimeError("upload_path should be specified to enable uploads") return build_upload_url( self.__upload_endpoint_path, file_name, diff --git a/sdk/python/packages/flet-webview/src/flet_webview/webview.py b/sdk/python/packages/flet-webview/src/flet_webview/webview.py index 5c25b22379..3234b5e7bc 100644 --- a/sdk/python/packages/flet-webview/src/flet_webview/webview.py +++ b/sdk/python/packages/flet-webview/src/flet_webview/webview.py @@ -113,7 +113,8 @@ def _check_mobile_or_mac_platform(self): """ Checks/Validates support for the current platform (iOS, Android, or macOS). """ - assert self.page is not None, "WebView must be added to page first." + if self.page is None: + raise RuntimeError("WebView must be added to page first.") if self.page.web or self.page.platform not in [ ft.PagePlatform.ANDROID, ft.PagePlatform.IOS, From 34176dc99f893aa894985342cfc5b39a257f8290 Mon Sep 17 00:00:00 2001 From: Feodor Fitsner Date: Fri, 17 Oct 2025 09:01:58 -0700 Subject: [PATCH 3/6] Apply suggestion from @Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- sdk/python/packages/flet-charts/src/flet_charts/bar_chart.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/python/packages/flet-charts/src/flet_charts/bar_chart.py b/sdk/python/packages/flet-charts/src/flet_charts/bar_chart.py index 5c12e7676c..e51fd4e2c8 100644 --- a/sdk/python/packages/flet-charts/src/flet_charts/bar_chart.py +++ b/sdk/python/packages/flet-charts/src/flet_charts/bar_chart.py @@ -175,7 +175,7 @@ class BarChart(ft.LayoutControl): group_spacing: ft.Number = 16.0 """ - A amount of space between bar [`groups`][(c).]. + An amount of space between bar [`groups`][(c).]. """ group_alignment: ft.MainAxisAlignment = ft.MainAxisAlignment.SPACE_EVENLY From ad43b32f539d289a8356c83a802c01d4437a29cd Mon Sep 17 00:00:00 2001 From: Feodor Fitsner Date: Fri, 17 Oct 2025 09:22:43 -0700 Subject: [PATCH 4/6] Apply suggestion from @Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .../packages/flet/src/flet/controls/material/expansion_panel.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/python/packages/flet/src/flet/controls/material/expansion_panel.py b/sdk/python/packages/flet/src/flet/controls/material/expansion_panel.py index 23829667d4..685f293c65 100644 --- a/sdk/python/packages/flet/src/flet/controls/material/expansion_panel.py +++ b/sdk/python/packages/flet/src/flet/controls/material/expansion_panel.py @@ -88,7 +88,7 @@ class ExpansionPanelList(LayoutControl): Defines the elevation of the [`controls`][(c).], when expanded. Raises: - ValueError: If it is less than or equal to zero. + ValueError: If it is less than zero. """ expanded_header_padding: PaddingValue = field( From 26fb2ad12b1b93b698cb70af4aa471fd0376862c Mon Sep 17 00:00:00 2001 From: Feodor Fitsner Date: Fri, 17 Oct 2025 09:24:50 -0700 Subject: [PATCH 5/6] Apply suggestion from @Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- sdk/python/packages/flet/src/flet/controls/material/menu_bar.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/python/packages/flet/src/flet/controls/material/menu_bar.py b/sdk/python/packages/flet/src/flet/controls/material/menu_bar.py index 43ccb9c94c..06aaf51f22 100644 --- a/sdk/python/packages/flet/src/flet/controls/material/menu_bar.py +++ b/sdk/python/packages/flet/src/flet/controls/material/menu_bar.py @@ -51,7 +51,7 @@ class MenuBar(Control): A list of top-level menu controls to display in this menu bar. Raises: - ValueError: If at least one control in this list is not visible. + ValueError: If none of the controls are visible. """ clip_behavior: ClipBehavior = ClipBehavior.NONE From 0dc41d4b3bde28ce3a71fc2c70d8327ab9bc5ea6 Mon Sep 17 00:00:00 2001 From: ndonkoHenri Date: Sat, 18 Oct 2025 14:58:08 +0200 Subject: [PATCH 6/6] improve docstrings --- packages/flet/lib/src/utils/drawing.dart | 9 +++-- .../flet-ads/src/flet_ads/native_ad.py | 10 +++--- .../flet-audio/src/flet_audio/audio.py | 4 +-- .../src/flet_charts/pie_chart_section.py | 20 +++++------ .../flet-lottie/src/flet_lottie/lottie.py | 6 ++-- .../packages/flet-map/src/flet_map/types.py | 13 +++---- .../src/flet/controls/core/dismissible.py | 6 +--- .../flet/controls/core/interactive_viewer.py | 33 ++++++------------ .../src/flet/controls/core/responsive_row.py | 3 +- .../flet/src/flet/controls/core/row.py | 3 +- .../flet/src/flet/controls/core/view.py | 6 ++-- .../flet/src/flet/controls/core/window.py | 20 ++++++----- .../src/flet/controls/material/app_bar.py | 11 +++--- .../flet/src/flet/controls/material/chip.py | 15 +++----- .../flet/controls/material/circle_avatar.py | 11 +++--- .../flet/controls/material/expansion_panel.py | 34 +++++++++++++++++++ .../src/flet/controls/material/snack_bar.py | 5 +-- .../flet/src/flet/controls/material/tabs.py | 19 ++++------- .../packages/flet/src/flet/controls/page.py | 2 +- .../flet/src/flet/testing/flet_test_app.py | 4 ++- 20 files changed, 117 insertions(+), 117 deletions(-) diff --git a/packages/flet/lib/src/utils/drawing.dart b/packages/flet/lib/src/utils/drawing.dart index 1d57a634e7..d5be3aaf7b 100644 --- a/packages/flet/lib/src/utils/drawing.dart +++ b/packages/flet/lib/src/utils/drawing.dart @@ -40,12 +40,11 @@ List? parsePaintStrokeDashPattern(dynamic value, [List? defaultValue]) { if (value == null) return defaultValue; - return value["stroke_dash_pattern"] != null - ? (value["stroke_dash_pattern"] as List) - .map((e) => parseDouble(e)) + return (value["stroke_dash_pattern"] as List?) + ?.map((e) => parseDouble(e)) .nonNulls - .toList() - : null; + .toList() ?? + defaultValue; } ui.Gradient? parsePaintGradient(Map? value, ThemeData? theme, diff --git a/sdk/python/packages/flet-ads/src/flet_ads/native_ad.py b/sdk/python/packages/flet-ads/src/flet_ads/native_ad.py index a7c74a25f8..fcbe7069bf 100644 --- a/sdk/python/packages/flet-ads/src/flet_ads/native_ad.py +++ b/sdk/python/packages/flet-ads/src/flet_ads/native_ad.py @@ -9,20 +9,22 @@ class NativeAd(BannerAd): """ Renders a native ad. - - Raises: - ValueError: When neither [`factory_id`][(c).] nor - [`template_style`][(c).] is set. """ factory_id: str = None """ An identifier for the factory that creates the Platform view. + + Raises: + ValueError: When neither `factory_id` nor [`template_style`][(c).] is set. """ template_style: NativeAdTemplateStyle = None """ A style for the native ad template. + + Raises: + ValueError: When neither [`factory_id`][(c).] nor `template_style` is set. """ def before_update(self): diff --git a/sdk/python/packages/flet-audio/src/flet_audio/audio.py b/sdk/python/packages/flet-audio/src/flet_audio/audio.py index fd2e72ba50..5fa2f0871a 100644 --- a/sdk/python/packages/flet-audio/src/flet_audio/audio.py +++ b/sdk/python/packages/flet-audio/src/flet_audio/audio.py @@ -27,7 +27,7 @@ class Audio(ft.Service): is a list of supported audio formats. Raises: - ValueError: If both [`src`][(c).] and [`src_base64`][(c).] are `None`. + ValueError: If both `src` and [`src_base64`][(c).] are `None`. """ src_base64: Optional[str] = None @@ -41,7 +41,7 @@ class Audio(ft.Service): is a list of supported audio formats. Raises: - ValueError: If both [`src`][(c).] and [`src_base64`][(c).] are `None`. + ValueError: If both `src_base64` and [`src`][(c).] are `None`. """ autoplay: bool = False diff --git a/sdk/python/packages/flet-charts/src/flet_charts/pie_chart_section.py b/sdk/python/packages/flet-charts/src/flet_charts/pie_chart_section.py index ff8f68475c..88f84fa002 100644 --- a/sdk/python/packages/flet-charts/src/flet_charts/pie_chart_section.py +++ b/sdk/python/packages/flet-charts/src/flet_charts/pie_chart_section.py @@ -10,10 +10,6 @@ class PieChartSection(ft.BaseControl): """ Configures a [PieChart][(p).] section. - - Raises: - ValueError: If [`title_position`][(c).] or [`badge_position`][(c).] - is not between `0.0` and `1.0` inclusive. """ value: ft.Number @@ -51,11 +47,13 @@ class PieChartSection(ft.BaseControl): """ The position/offset of the title relative to the section's center. + - `0.0`: near the center + - `1.0`: near the outside of the chart + By default the title is drawn in the middle of the section. - Note: - Must be between `0.0` (near the center) - and `1.0`(near the outside of the chart) inclusive. + Raises: + ValueError: If it is not between `0.0` and `1.0` inclusive. """ badge: Optional[ft.Control] = None @@ -67,11 +65,13 @@ class PieChartSection(ft.BaseControl): """ The position/offset of the badge relative to the section's center. + - `0.0`: near the center + - `1.0`: near the outside of the chart + By default the badge is drawn in the middle of the section. - Note: - Must be between `0.0` (near the center) - and `1.0`(near the outside of the chart) inclusive. + Raises: + ValueError: If it is not between `0.0` and `1.0` inclusive. """ gradient: Optional[ft.Gradient] = None diff --git a/sdk/python/packages/flet-lottie/src/flet_lottie/lottie.py b/sdk/python/packages/flet-lottie/src/flet_lottie/lottie.py index 3995ad5db2..b0ee89ee94 100644 --- a/sdk/python/packages/flet-lottie/src/flet_lottie/lottie.py +++ b/sdk/python/packages/flet-lottie/src/flet_lottie/lottie.py @@ -15,14 +15,14 @@ class Lottie(ft.LayoutControl): """ The source of the Lottie file. - Can be a URL or a local [asset file](https://flet.dev/docs/cookbook/assets). + Can be a URL or a local [asset file](https://docs.flet.dev/cookbook/assets). Note: If both `src` and [`src_base64`][(c).] are provided, `src_base64` will be prioritized/used. Raises: - ValueError: If neither [`src`][(c).] nor [`src_base64`][(c).] is provided. + ValueError: If neither `src` nor [`src_base64`][(c).] is provided. """ src_base64: Optional[str] = None @@ -34,7 +34,7 @@ class Lottie(ft.LayoutControl): `src_base64` will be prioritized/used. Raises: - ValueError: If neither [`src`][(c).] nor [`src_base64`][(c).] is provided. + ValueError: If neither `src_base64` nor [`src`][(c).] is provided. """ repeat: bool = True diff --git a/sdk/python/packages/flet-map/src/flet_map/types.py b/sdk/python/packages/flet-map/src/flet_map/types.py index 30e36b8930..5c05b44f25 100644 --- a/sdk/python/packages/flet-map/src/flet_map/types.py +++ b/sdk/python/packages/flet-map/src/flet_map/types.py @@ -223,8 +223,6 @@ class DottedStrokePattern(StrokePattern): Raises: ValueError: If it is less than or equal to zero. - Note: - Must be non-negative. """ pattern_fit: PatternFit = PatternFit.SCALE_UP @@ -236,8 +234,7 @@ class DottedStrokePattern(StrokePattern): def __post_init__(self): if self.spacing_factor <= 0: raise ValueError( - "spacing_factor must be greater than or equal to 0.0, " - f"got {self.spacing_factor}" + f"spacing_factor must be greater than to 0.0, got {self.spacing_factor}" ) self._type = "dotted" @@ -454,8 +451,8 @@ class InteractionConfiguration: Note: If [`InteractionConfiguration.flags`][(p).] doesn't contain - [`InteractionFlag.PINCH_MOVE`][(p).] - or [`enable_multi_finger_gesture_race`][(c).] is false then pinch move cannot win. + [`InteractionFlag.PINCH_MOVE`][(p).] or + [`enable_multi_finger_gesture_race`][(c).] is false then pinch move cannot win. """ scroll_wheel_velocity: ft.Number = 0.005 @@ -949,8 +946,8 @@ class KeyboardConfiguration: To customize the leap itself, see the [`leap_max_of_curve_component`][(c).] & `*leap_velocity_multiplier` ([`zoom_leap_velocity_multiplier`][(c).], - [`pan_leap_velocity_multiplier`][(c).] and [`rotate_leap_velocity_multiplier`][(c).]) - properties. + [`pan_leap_velocity_multiplier`][(c).] and + [`rotate_leap_velocity_multiplier`][(c).]) properties. Set to `None` to disable leaping. """ diff --git a/sdk/python/packages/flet/src/flet/controls/core/dismissible.py b/sdk/python/packages/flet/src/flet/controls/core/dismissible.py index 58b35960b3..611e10a42f 100644 --- a/sdk/python/packages/flet/src/flet/controls/core/dismissible.py +++ b/sdk/python/packages/flet/src/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. """ diff --git a/sdk/python/packages/flet/src/flet/controls/core/interactive_viewer.py b/sdk/python/packages/flet/src/flet/controls/core/interactive_viewer.py index f60f5576d1..ce028a15b1 100644 --- a/sdk/python/packages/flet/src/flet/controls/core/interactive_viewer.py +++ b/sdk/python/packages/flet/src/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 @@ def before_update(self): "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}" diff --git a/sdk/python/packages/flet/src/flet/controls/core/responsive_row.py b/sdk/python/packages/flet/src/flet/controls/core/responsive_row.py index 84ad3336b0..02e30e7227 100644 --- a/sdk/python/packages/flet/src/flet/controls/core/responsive_row.py +++ b/sdk/python/packages/flet/src/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.]. """ diff --git a/sdk/python/packages/flet/src/flet/controls/core/row.py b/sdk/python/packages/flet/src/flet/controls/core/row.py index 7e30d1dd5d..25b26115a0 100644 --- a/sdk/python/packages/flet/src/flet/controls/core/row.py +++ b/sdk/python/packages/flet/src/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.]. """ diff --git a/sdk/python/packages/flet/src/flet/controls/core/view.py b/sdk/python/packages/flet/src/flet/controls/core/view.py index c3f3e229c1..645c5cc3a1 100644 --- a/sdk/python/packages/flet/src/flet/controls/core/view.py +++ b/sdk/python/packages/flet/src/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)) diff --git a/sdk/python/packages/flet/src/flet/controls/core/window.py b/sdk/python/packages/flet/src/flet/controls/core/window.py index 61f47757ba..533c4e5e86 100644 --- a/sdk/python/packages/flet/src/flet/controls/core/window.py +++ b/sdk/python/packages/flet/src/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): """ diff --git a/sdk/python/packages/flet/src/flet/controls/material/app_bar.py b/sdk/python/packages/flet/src/flet/controls/material/app_bar.py index 0de1546d87..44e664ae4d 100644 --- a/sdk/python/packages/flet/src/flet/controls/material/app_bar.py +++ b/sdk/python/packages/flet/src/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 diff --git a/sdk/python/packages/flet/src/flet/controls/material/chip.py b/sdk/python/packages/flet/src/flet/controls/material/chip.py index 1ea84ebc84..37a7e5c1b7 100644 --- a/sdk/python/packages/flet/src/flet/controls/material/chip.py +++ b/sdk/python/packages/flet/src/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 diff --git a/sdk/python/packages/flet/src/flet/controls/material/circle_avatar.py b/sdk/python/packages/flet/src/flet/controls/material/circle_avatar.py index 7e693051d7..d3991510d6 100644 --- a/sdk/python/packages/flet/src/flet/controls/material/circle_avatar.py +++ b/sdk/python/packages/flet/src/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 diff --git a/sdk/python/packages/flet/src/flet/controls/material/expansion_panel.py b/sdk/python/packages/flet/src/flet/controls/material/expansion_panel.py index 685f293c65..baab761f92 100644 --- a/sdk/python/packages/flet/src/flet/controls/material/expansion_panel.py +++ b/sdk/python/packages/flet/src/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 @@ -70,6 +87,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) diff --git a/sdk/python/packages/flet/src/flet/controls/material/snack_bar.py b/sdk/python/packages/flet/src/flet/controls/material/snack_bar.py index 4c9ce24d23..5d38f1986b 100644 --- a/sdk/python/packages/flet/src/flet/controls/material/snack_bar.py +++ b/sdk/python/packages/flet/src/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 diff --git a/sdk/python/packages/flet/src/flet/controls/material/tabs.py b/sdk/python/packages/flet/src/flet/controls/material/tabs.py index b95d8c8baf..1f90483ba7 100644 --- a/sdk/python/packages/flet/src/flet/controls/material/tabs.py +++ b/sdk/python/packages/flet/src/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. """ diff --git a/sdk/python/packages/flet/src/flet/controls/page.py b/sdk/python/packages/flet/src/flet/controls/page.py index 642b627b0d..62f71988de 100644 --- a/sdk/python/packages/flet/src/flet/controls/page.py +++ b/sdk/python/packages/flet/src/flet/controls/page.py @@ -198,7 +198,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. """ diff --git a/sdk/python/packages/flet/src/flet/testing/flet_test_app.py b/sdk/python/packages/flet/src/flet/testing/flet_test_app.py index 6de2a8ad93..94d9aad18a 100644 --- a/sdk/python/packages/flet/src/flet/testing/flet_test_app.py +++ b/sdk/python/packages/flet/src/flet/testing/flet_test_app.py @@ -369,7 +369,9 @@ def assert_screenshot( ) with open(actual_image_path, "bw") as f: f.write(screenshot) - raise ValueError(f"{name} screenshots are not identical") + assert similarity > similarity_threshold, ( + f"{name} screenshots are not identical" + ) def _load_image_from_file(self, file_name): return Image.open(file_name)