feature: Support covariance for Control lists (use Sequence/Mapping or Mutable ones)

[Iaw4tch]

Duplicate Check

• I have searched the opened issues and there are no duplicates

Describe the requested feature

Currently, many Flet containers (like Column, Row, View, etc.) define their controls property strictly as list[Control]. Because Python's list is invariant, this causes significant issues when building custom structured UI architectures.

Suggest a solution

Change the type hinting for controls in constructors from list[Control] to a covariant alternative, like typing.Sequence[Control]. This allows passing lists of subclasses (e.g., list[MyCustomControl]) without breaking type safety or triggering linter warnings (e.g., Pylance(reportArgumentType)

Screenshots

No response

Additional details

I've ran into this problem writing my own Tabs class wrapper that coordinates specific child components.

class InertiaListViewResponsibleTabs(ft.Tabs):
    def __init__(
        self,
        tab_bar: EmphasisTabBar, # My own TabBar wrapper
        view_controls: list[ft.Control],
        ...
    ):
        super().__init__(
            on_change=self._on_change,
            ...,
            content=ft.Column(
                ...,
                controls=[tab_bar, ft.TabBarView(controls=view_controls)],
            ),
        )

The bad workaround I am forced to use:
To bypass this, I have to lower my type safety, accept any Control, and then manually pollute my runtime code with isinstance checks to filter out unexpected controls:

def __init__(
    self,
    ...,
    view_controls: list[ft.Control],
    ...
):
    super().__init__(...)

    # Runtime overhead and boilerplate just because of invariant list hints
    self._inertia_list_view_mask = [isinstance(control, InertiaListView) for control in view_controls]

    self._view_controls = view_controls

def _on_change(self, e: ft.Event[ft.Tabs]):
    if self._inertia_list_view_mask[e.control.selected_index]:
        # Cast is a bad tone
        list_view = cast(
            InertiaListView, self._view_controls[e.control.selected_index]
        )
        list_view.scroll_to(list_view.current_offset)

If ft.TabBarView accepted Sequence[Control], Python's type checkers would naturally allow writing:

def __init__(
    self,
    tab_bar: EmphasisTabBar,
    view_controls: list[InertiaListView],
    ...
):
    super().__init__(
        on_change=self._on_change,
        ...,
        content=ft.Column(
            ...,
            # Assignment without Pylance[reportArgumentType]
            controls=[tab_bar, ft.TabBarView(controls=view_controls)],
        ),
    )

This simplifies _on_change logic:

def _on_change(self, e: ft.Event[ft.Tabs]):
    list_view = self._view_controls[e.control.selected_index]
    list_view.scroll_to(list_view.current_offset)

[FeodorFitsner]

If Sequence used a user won't be able to see controls.append() in IDE autocompletion?

[Iaw4tch]

If Sequence used a user won't be able to see controls.append() in IDE autocompletion?

but it converts into list

[FeodorFitsner]

OK. Soooo, the fix is to change list[Control] to Sequence[Control] across all Flet controls, but leave default factory as []?

[Iaw4tch]

OK. Soooo, the fix is to change list[Control] to Sequence[Control] across all Flet controls, but leave default factory as []?

maybe, but it might cause some issues inside flet's insides typing

its maybe not quite good that immutable type becomes mutable later on, not sure

[Iaw4tch]

You can possibly just receive Sequence from the user, and handle the list as it was before

Make __init__ wait for Sequence, but the .controls property will still be list