API Reference¶

class FletEasy:
    """Main application class for Flet-Easy.

    Configure the app with:

    * `route_prefix` : Route prefix different from `/`.
    * `route_init` : Initial route, default is `/`.
    * `route_login` : Route for redirect when using protected routes.
    * `on_keyboard` : Enable on_keyboard event (default: False).
    * `on_resize` : Enable on_resize event (default: False).
    * `secret_key` : Configure JWT or client storage with `SecretKey`.
    * `auto_logout` : Auto-logout with JWT expiry (default: False).
    * `path_views` : Folder path for auto-discovered page files.
    * `logger` : Enable logger (default: False).

    Example:
    ```python
    import flet as ft
    import flet_easy as fs

    app = fs.FletEasy(
        route_prefix="/FletEasy",
        route_init="/FletEasy/home",
    )


    @app.page("/home", title="Home", page_clear=True)
    async def index_page(data: fs.Datasy):
        return ft.View(
            data.route_init,
            controls=[ft.Text("Home", size=40)],
        )


    app.run()
    ```
    """

    __self: Optional["FletEasy"] = None

    # ─── Initialization ───────────────────────────────────────────────

    def __init__(
        self,
        route_prefix: Optional[str] = None,
        route_init: str = "/",
        route_login: Optional[str] = None,
        on_resize: bool = False,
        on_keyboard: bool = False,
        secret_key: Optional[SecretKey] = None,
        auto_logout: bool = False,
        path_views: Optional[Path] = None,
        logger: bool = False,
        use_error_boundary: bool = True,
    ) -> None:
        if logger:
            import logging

            LoggingFletEasy.enable(logging.DEBUG)
        self._logger = get_logger("FletEasy")

        self.__route_prefix: str = route_prefix or ""
        self.__route_init: str = route_init
        self.__route_login: Optional[str] = route_login
        self.__path_views: Optional[Union[str, Path]] = path_views
        self.__on_resize: bool = on_resize
        self.__on_keyboard: bool = on_keyboard
        self.__secret_key: Optional[SecretKey] = secret_key
        self.__auto_logout: bool = auto_logout
        self.__use_error_boundary: bool = use_error_boundary

        self.__page_404: Optional[Pagesy] = None
        self.__middlewares: Optional[deque[MiddlewareItem]] = None
        self.__middlewares_after: Optional[deque[MiddlewareItem]] = None

        self.__pages: deque[Pagesy] = deque()
        self.__view_data: Optional[Callable[[Datasy], Viewsy]] = None
        self.__config_login: Optional[Callable[[Datasy], bool]] = None
        self.__view_config: Optional[Callable[[Page], None]] = None
        self.__config_event: Optional[Callable[[Datasy], None]] = None

        FletEasy.__self = self
        self.__fsx: Optional[FletEasyX] = None
        self.__pagesys = automatic_routing(str(self.__path_views)) if self.__path_views else None

    # ─── App Lifecycle ────────────────────────────────────────────────

    def __pre_config(self, page: Page) -> None:
        """Configure and start the routing engine."""

        # Add automatic routing pages before initializing FletEasyX
        # so they are included in the exact_routes_map
        if self.__pagesys:
            self.add_pages(self.__pagesys)
            self.__pagesys = None

        fsx = FletEasyX(
            page=page,
            route_prefix=self.__route_prefix,
            route_init=self.__route_init,
            route_login=self.__route_login,
            page_404=self.__page_404,
            pages=self.__pages,
            view_data=self.__view_data,
            config_login=self.__config_login,
            view_config=self.__view_config,
            config_event=self.__config_event,
            middlewares=self.__middlewares,
            middlewares_after=self.__middlewares_after,
            on_resize=self.__on_resize,
            on_keyboard=self.__on_keyboard,
            secret_key=self.__secret_key,
            auto_logout=self.__auto_logout,
            use_error_boundary=self.__use_error_boundary,
        )

        self.__fsx = fsx

        fsx.run()

    def start(self, page: Page) -> None:
        """Start the app in the main function."""
        self._logger.debug("enabling connection with flet app")
        self.__pre_config(page)

    def get_app(self) -> Callable[[Page], None]:
        """Return the app function main."""
        self._logger.debug("getting app from fletEasy to export")

        def main(page: Page) -> None:
            self.__pre_config(page)

        return main

    def run(
        self,
        name: str = "",
        host: Optional[str] = None,
        port: int = 0,
        view: Optional[AppView] = AppView.FLET_APP,
        assets_dir: str = "assets",
        upload_dir: Optional[str] = None,
        web_renderer: WebRenderer = WebRenderer.CANVAS_KIT,
        route_url_strategy: Union[RouteUrlStrategy, str] = RouteUrlStrategy.PATH,
        export_asgi_app: bool = False,
        fastapi: bool = False,
        **kwargs: Any,
    ) -> Any:
        """Execute the app. Supports async, fastapi, and export_asgi_app."""
        main = self.get_app()

        if fastapi:
            warn(
                "Avoid using the 'fastapi' parameter in the 'run()' method, "
                "instead use the 'get_app()' method.",
                category=DeprecationWarning,
                stacklevel=2,
            )
            return main

        try:
            self._logger.debug("running app from fletEasy with flet")
            app_kwargs: dict[str, Any] = {
                "name": name,
                "host": host,
                "port": port,
                "view": view,
                "assets_dir": assets_dir,
                "upload_dir": upload_dir,
                "web_renderer": web_renderer,
                "export_asgi_app": export_asgi_app,
                **kwargs,
            }
            if route_url_strategy is not None:
                app_kwargs["route_url_strategy"] = route_url_strategy

            return app(
                main,
                **app_kwargs,
            )
        except RuntimeError:
            raise FletEasyError(
                "If you are using fastapi from flet, set the 'fastapi = True' "
                "parameter of the run() method."
            )

    # ─── Route Registration ───────────────────────────────────────────

    @classmethod
    def page(
        cls,
        route: str,
        title: Optional[str] = None,
        index: Optional[int] = None,
        page_clear: bool = False,
        share_data: bool = False,
        protected_route: bool = False,
        custom_params: Optional[dict[str, Any]] = None,
        middleware: Middleware = None,
        cache: bool = False,
    ) -> Callable:
        """Decorator to add a new page to the app.

        Args:
            route: URL path, e.g. `'/home'`.
            title: Page title (optional).
            index: Page index for NavigationBar (optional).
            page_clear: Remove previous views (optional).
            share_data: Share data between pages (optional).
            protected_route: Protect with login (optional).
            custom_params: Custom URL parameter validators (optional).
            middleware: Page-level middleware (optional).
            cache: Preserve page state when navigating (optional).
        """
        self = cls.__self
        if self is None:
            raise ConfigurationError("FletEasy instance not initialized.")

        def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
            pagesy = Pagesy(
                route=normalize_route(self.__route_prefix, route),
                view=func,
                title=title,
                index=index,
                clear=page_clear,
                share_data=share_data,
                protected_route=protected_route,
                custom_params=custom_params,
                middleware=middleware,
                cache=cache,
            )
            self.__pages.append(pagesy)

            # Back-reference for reverse decorator order (@ft.component on top)
            setattr(func, "__flet_easy_pagesy__", pagesy)  # noqa: B010

            self._logger.debug("Adding page: %s", self.__pages[-1])
            return func

        return decorator

    def page_404(
        self,
        route: Optional[str] = None,
        title: Optional[str] = None,
        page_clear: bool = False,
    ) -> Callable:
        """Decorator to add a custom 404 page.

        Args:
            route: URL path for the 404 page (optional).
            title: Page title (default: 'Flet-Easy 404').
            page_clear: Remove previous views (optional).
        """

        def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
            self.__page_404 = Pagesy(
                normalize_route(self.__route_prefix, route or ""),
                func,
                title or "Flet-Easy 404",
                clear=page_clear,
            )
            self._logger.debug("Adding page 404: %s", self.__page_404)
            return func

        return decorator

    def add_pages(self, group_pages: Union[list[AddPagesy], AddPagesy]) -> None:
        """Add pages from other files.

        Example:
        ```python
        app.add_pages([index, test, contador, login, task])
        ```
        """
        group_pages = group_pages if isinstance(group_pages, list) else [group_pages]

        try:
            for page in group_pages:
                if self.__route_prefix:
                    self.__pages.extend(page._add_pages(self.__route_prefix))
                else:
                    self.__pages.extend(page._add_pages())

                self._logger.debug("Adding group of pages: %d: %s", len(group_pages), page)
        except Exception as e:
            raise AddPagesError("Add pages error in route: ", e)

    def add_routes(self, add_views: list[Pagesy]) -> None:
        """Add routes without the use of decorators.

        Example:
        ```python
        app.add_routes(
            add_views=[
                fs.Pagesy("/hi", index_page, True),
                fs.Pagesy("/counter", counter_page),
            ]
        )
        ```
        """
        if not add_views:
            raise ConfigurationError("add view (add_view) in 'add_routes'.")

        for page in add_views:
            if self.__route_prefix:
                page.route = normalize_route(self.__route_prefix, page.route)

            self.__pages.append(page)
            self._logger.debug("Add routes: %s", page)

    # ─── Configuration Decorators ─────────────────────────────────────

    def view(self, func: Callable[[Datasy], Viewsy]) -> Callable[[Datasy], Viewsy]:
        """Decorator to add custom view controls (appbar, navigation, etc).

        The decorated function receives `data:fs.Datasy` and returns `fs.Viewsy`.
        """
        self.__view_data = func
        self._logger.debug("Adding view: %s", self.__view_data)
        return func

    def config(self, func: Callable[[Page], None]) -> Callable[[Page], None]:
        """Decorator to add custom page configuration (theme, etc).

        The decorated function receives `page:ft.Page` and returns nothing.
        """
        self.__view_config = func
        self._logger.debug("Adding config: %s", self.__view_config)
        return func

    def login(self, func: Callable[[Datasy], bool]) -> Callable[[Datasy], bool]:
        """Decorator to add login configuration for protected routes.

        The decorated function receives `data:fs.Datasy` and must return a boolean.
        """
        self.__config_login = func
        self._logger.debug("Adding login: %s", self.__config_login)
        return func

    def config_event_handler(self, func: Callable[[Datasy], None]) -> Callable[[Datasy], None]:
        """Decorator to add page event handler settings."""
        self.__config_event = func
        self._logger.debug("Adding config event: %s", self.__config_event)
        return func

    # ─── Middleware ────────────────────────────────────────────────────

    def add_middleware(
        self,
        *middleware: MiddlewareItem,
    ) -> None:
        """Add global middleware.

        Accepts classes inheriting from `fs.MiddlewareRequest` or functions
        that receive `data:fs.Datasy`. Can be added individually or as a list.

        **More info:** https://daxexs.github.io/flet-easy/latest/middleware/#general-application
        """
        if not middleware:
            raise MiddlewareError(
                "No middleware provided to 'add_middleware'. "
                "Pass at least one middleware function or MiddlewareRequest class."
            )

        items = middleware[0] if isinstance(middleware[0], list) else list(middleware)

        self.__middlewares = deque()
        self.__middlewares_after = deque()

        for m in items:
            if isinstance(m, type) and issubclass(m, MiddlewareRequest):
                self.__middlewares.append(m)
                self.__middlewares_after.append(m)
            elif callable(m):
                self.__middlewares.append(cast(MiddlewareItem, m))
            else:
                raise MiddlewareError(
                    f"Middleware '{m}' must be a class inheriting from "
                    f"MiddlewareRequest or a callable function."
                )

        self._logger.debug("Add middlewares in method 'add_middleware': %s", items)

class Datasy(AuthMixin):
    """Core data object passed to route handlers in Flet-Easy.

    Provides access to the Flet `Page` instance, URL parameters, routing state,
    client storage, and authentication utilities.

    Attributes:
    * `page` : The active Flet `Page` instance.
    * `url_params` : A dictionary of parsed parameters from the current URL.
    * `view` : The `View` object configured by the `@app.view` decorator.
    * `route_prefix` : The configured application route prefix.
    * `route_init` : The initial application route.
    * `route_login` : The configured login route for protected endpoints.
    * `share` : Interface for storing and retrieving values in the client session.
    * `on_keyboard_event` : Contains keyboard event data if enabled.
    * `on_resize` : Contains window resize event data if enabled.
    * `logout` : Closes the active session in client storage.
    * `login` : Creates a new session in client storage.
    * `go` / `go_route`: Navigates to a new application route.
    * `go_back` : Navigates back to the previous route.
    * `go_navigation_bar` : Handles navigation bar index updates.
    * `history_routes` : History of visited routes in the current session.
    * `route` : The current application route.
    * `redirect` : Returns a `Redirect` object to bypass the current view (useful in middleware).
    * `page_reload` : Reloads the current route.
    * `dynamic_control` : Registers a dynamically updatable control for the current route.
    * `confirm_pop` : Triggers the `ViewPopEvent` manually.
    """

    __slots__ = (
        "__page",
        "__url_params",
        "__view",
        "__route_prefix",
        "__route_init",
        "__route_login",
        "__share",
        "__on_keyboard_event",
        "__on_resize",
        "__route",
        "_run_go",
        "__history_routes",
        "_dynamic_control",
        "__secret_key",
        "__auto_logout",
        "_sleep_auth",
        "_key_login",
        "_login_done",
        "_shared_preferences",
        "_use_client_storage",
    )

    def __init__(
        self,
        page: Page,
        route_prefix: str,
        route_init: str,
        route_login: Optional[str],
        secret_key: Optional[SecretKey],
        auto_logout: bool,
        page_on_keyboard: Keyboardsy,
        page_on_resize: Resizesy,
        go: Callable[..., Awaitable[None]],
    ) -> None:
        self.__page = page
        self.__url_params: dict[str, Any] = {}
        self.__view: Optional[Union[Viewsy, View]] = None
        self.__route_prefix = route_prefix
        self.__route_init = route_init
        self.__route_login = route_login
        if NEW_FLET_VERSION:
            self.__share = SharedPreferencesEdit(prefix="fs-share:")
            self._shared_preferences = SharedPreferencesEdit()
        else:
            self.__share = SessionStorageEdit(page)
            self._shared_preferences = SessionStorageEdit(page)

        self.__on_keyboard_event = page_on_keyboard
        self.__on_resize: Resizesy = page_on_resize
        self.__route: Optional[str] = None
        self._run_go = go
        self.__history_routes: deque[tuple[str, Optional[int]]] = deque()
        self._dynamic_control: dict[str, list[tuple[Control, Callable[[Control], None]]]] = {}

        self.__secret_key = secret_key
        self.__auto_logout: bool = auto_logout
        self._sleep_auth: int = 1
        self._key_login: Optional[str] = None
        self._login_done: bool = False
        # Cached once per session — storage API never changes at runtime
        self._use_client_storage: bool = hasattr(page, "client_storage")

        _logger.debug(
            "Using SharedPreferences (Flet >= 0.80)"
            if NEW_FLET_VERSION
            else "Using SessionStorage (Flet < 0.80)"
        )

    @property
    def page(self) -> Page:
        return self.__page

    @page.setter
    def page(self, page: Page):
        self.__page = page

    @property
    def history_routes(self) -> deque[tuple[str, Optional[int]]]:
        return self.__history_routes

    @property
    def url_params(self) -> dict[str, Any]:
        return self.__url_params

    @url_params.setter
    def url_params(self, url_params: dict[str, Any]):
        self.__url_params = url_params

    @property
    def view(self) -> Optional[Union[Viewsy, View]]:
        return self.__view

    @view.setter
    def view(self, view: Union[Viewsy, View]):
        self.__view = view

    @property
    def route_prefix(self) -> str:
        return self.__route_prefix

    @route_prefix.setter
    def route_prefix(self, route_prefix: str):
        self.__route_prefix = route_prefix

    @property
    def route_init(self) -> str:
        return self.__route_init

    @route_init.setter
    def route_init(self, route_init: str):
        self.__route_init = route_init

    @property
    def route_login(self) -> Optional[str]:
        return self.__route_login

    @route_login.setter
    def route_login(self, route_login: str):
        self.__route_login = route_login

    @property
    def share(self) -> Union[SessionStorageEdit, SharedPreferencesEdit]:
        return self.__share

    # events
    @property
    def on_keyboard_event(self) -> Keyboardsy:
        return self.__on_keyboard_event

    @on_keyboard_event.setter
    def on_keyboard_event(self, on_keyboard_event: Keyboardsy):
        self.__on_keyboard_event = on_keyboard_event

    @property
    def on_resize(self) -> Resizesy:
        return self.__on_resize

    @on_resize.setter
    def on_resize(self, on_resize: Resizesy):
        self.__on_resize = on_resize

    @property
    def key_login(self) -> Optional[str]:
        return self._key_login

    @property
    def auto_logout(self) -> bool:
        return self.__auto_logout

    @property
    def secret_key(self) -> Optional[SecretKey]:
        return self.__secret_key

    @property
    def route(self) -> Optional[str]:
        return self.__route

    @route.setter
    def route(self, route: str):
        self.__route = route

    """ Page go  """

    def go(self, route: str) -> Callable[[Any], None]:
        """To change the application path, it is important for better validation to avoid using `page.go()`."""

        return lambda _=None: self.go_route(route)

    def go_route(self, route: Union[str, int]) -> None:
        """To change the application path, it is important for better validation to avoid using `page.go()`."""
        self.page.run_task(self._run_go, route)

    def go_navigation_bar(self, e: ControlEvent) -> None:
        """Handles navigation bar changes. Use this method in the on_change event of
        'ft.NavigationBar' or 'ft.CupertinoNavigationBar' controls."""
        index = getattr(e.control, "selected_index", None)
        if index is not None:
            self.page.run_task(self._run_go, index)

    def redirect(self, route: str) -> Redirect:
        """Useful if you do not want to access a route that has already been sent."""
        return Redirect(route)

    def go_back(self, e: Optional[ControlEvent] = None) -> None:
        """Go back to the previous route."""

        if len(self.history_routes) > 1:
            self.history_routes.pop()
            route, index = self.history_routes.pop()

            if index is not None and self.view and self.view.navigation_bar:
                self.view.navigation_bar.selected_index = index

            self.page.run_task(self._run_go, route)
        else:
            _logger.warning("go_back: called with no navigation history to go back to.")

    def page_reload(self) -> None:
        """Use this method to reload the page, restores the default values of the page"""
        self.page.run_task(self._run_go, self.page.route, page_reload=True)

    def dynamic_control(self, control: Control, func_update: Callable[[Control], None]) -> None:
        """Adds dynamic control to the page, allowing real-time updates when caching is enabled on the page."""
        self._dynamic_control.setdefault(self.page.route, []).append((control, func_update))

    def confirm_pop(self, e: ViewPopEvent) -> None:
        """Confirm pop view"""
        self.go_back()
        if hasattr(e.view, "confirm_pop"):
            _ = getattr(e.view, "confirm_pop")(False)  # noqa: B009