flet_navigator

 88class RouteContext:
 89    """Route context class used for transferring data between routes and providing Navigator shortcuts."""
 90
 91    page: Page = None
 92    """The current page instance."""
 93
 94    navigator: Union['PublicFletNavigator', 'VirtualFletNavigator'] = None
 95    """The navigator that created this RouteContext instance."""
 96
 97    arguments: Arguments = None
 98    """Arguments passed from the previous page for context."""
 99
100    parameters: 'RouteParameters' = None
101    """URL parameters associated with the current route."""
102
103    route_id: tuple[int, str] = None
104    """The unique identifier for this page."""
105
106    def __init__(self, page: Page, navigator: Union['PublicFletNavigator', 'VirtualFletNavigator'], arguments: Arguments, parameters: 'RouteParameters', route_id: tuple[int, str]) -> None:
107        """Initialize a RouteContext instance."""
108        self.page = page
109
110        self.navigator = navigator
111
112        self.arguments = arguments
113
114        self.parameters = parameters
115
116        self.route_id = route_id
117
118    def add(self, *controls: Control) -> None:
119        """Add one or more controls to the current page."""
120        self.page.add(*controls)
121
122    def navigate(self, route: str, args: Arguments=(), **parameters: RouteParameters) -> None:
123        """Navigate to a specific route. If the navigator is virtual, parameters are not used."""
124        if self.navigator.is_virtual():
125            self.navigator.navigate(route, self.page, args)
126
127        else:
128            self.navigator.navigate(route, self.page, args, parameters)
129
130    def navigate_homepage(self, args: Arguments=(), **parameters: RouteParameters) -> None:
131        """Navigate to the homepage. If the navigator is virtual, parameters are not used."""
132        if self.navigator.is_virtual():
133            self.navigator.navigate_homepage(self.page, args)
134
135        else:
136            self.navigator.navigate_homepage(self.page, args, parameters)
137
138    def navigate_back(self, args: Arguments=(), **parameters: RouteParameters) -> None:
139        """Navigate back to the previous route. If the navigator is virtual, parameters are not used."""
140        if self.navigator.is_virtual():
141            self.navigator.navigate_back(self.page, args)
142
143        else:
144            self.navigator.navigate_back(self.page, args, parameters)
145
146    def set_homepage(self, homepage: str) -> None:
147        """Update navigator's homepage address."""
148        self.navigator.set_homepage(homepage)
149
150    def spec_cpage_props(self, **props: dict[str, Any]) -> None:
151        """Specify current page properties."""
152        self.navigator.props_map[self.route_id] = props
153
154        AbstractFletNavigator.proc_page_props(self.page, props, ())
155
156        self.page.update()
157
158    def current_route(self) -> str:
159        """Get the navigator's current route state."""
160        return self.navigator.route
161
162    def __repr__(self) -> str:
163        """Represent the RouteContext instance as a string for debugging purposes."""
164        return f'{self.previous_page} -> {self.navigator.route} [{"NO-ARGUMENTS" if not self.arguments else self.arguments}, {"NO-PARAMETERS" if len(self.parameters) <= 0 else self.parameters}] ({self.route_id}) (NAVIGATOR-OBJECT {self.navigator})'

334class PublicFletNavigator:
335    """The Public Flet Navigator. It's just like the virtual one, but with URL parameters and visible routes."""
336
337    page: Page = None
338    """Page object representing the current page."""
339
340    route: str = '/'
341    """The current active route."""
342
343    routes: Routes = {}
344    """A map of all registered routes in the application."""
345
346    previous_routes: list[str] = []
347    """A list of all previously visited routes."""
348
349    homepage: str = '/'
350    """The homepage route."""
351
352    props_map: RouteProperties = {}
353    """A page properties map for each page ID."""
354
355    route_change_callback: RouteChangeCallback = None
356    """A callback function that is triggered when the route changes."""
357
358    _nav_temp_args: Arguments = None
359
360    def __init__(self, page: Page, routes: Routes={}, route_change_callback: RouteChangeCallback=None) -> None:
361        """Initialize the public navigator."""
362        AbstractFletNavigator.init_nav(self, page, routes, route_change_callback)
363
364    def navigate(self, route: str, page: Page, args: Arguments=(), parameters: RouteParameters={}) -> None:
365        """Navigate to a specific route in the application."""
366        AbstractFletNavigator.navigate(self, route, page, args, parameters)
367
368    def navigate_homepage(self, page: Page, args: Arguments=(), parameters: RouteParameters={}) -> None:
369        """Navigate to the homepage route."""
370        AbstractFletNavigator.navigate_homepage(self, page, args, parameters)
371
372    def set_homepage(self, homepage: str) -> None:
373        """Update navigator's homepage address."""
374        AbstractFletNavigator.set_homepage(self, homepage)
375
376    def navigate_back(self, page: Page, args: Arguments=(), parameters: RouteParameters={}) -> None:
377        """Navigate back to the previous route."""
378        AbstractFletNavigator.navigate_back(self, page, args, parameters)
379
380    def process(self, page: Page, args: Arguments=(), route_parameters: RouteParameters={}) -> None:
381        """Process the current route on the provided page."""
382        AbstractFletNavigator.process(self, page, args, route_parameters)
383
384    def is_virtual(self) -> bool:
385        """Check if the navigator is virtual or public."""
386        return AbstractFletNavigator.is_virtual(self)
387
388    def fn_route_change_handler_(self, _) -> None:
389        route: str = self.page.route.replace(' ', _url_fn_space_chr).replace('%20', _url_fn_space_chr).replace('+', _url_fn_space_chr)
390
391        route = route[1:] if route.startswith('/') and len(route) >= 2 else route
392
393        split_url = urlsplit(route)
394
395        base_route, qstr = split_url.path, split_url.query
396
397        parameters = {}
398
399        if self._afn_proute.match(route):
400            _parsed_params = parse_qs(qstr, True)
401
402            for key, values in _parsed_params.items():
403                if not key.isalpha():
404                    self._logger.error(f'Invalid key name: "{key}". The key is expected to be a string.')
405
406                    continue
407
408                value = unquote(values[0]) if values else ''
409
410                if value.isdigit(): parameters[key] = int(value)
411                elif self._afn_floatstr.match(value): parameters[key] = float(value)
412                elif value in ['True', 'False']: parameters[key] = value == 'True'
413                elif value == 'None': parameters[key] = None
414                else: parameters[key] = value.replace(_url_fn_space_chr, ' ')
415
416        self.route = base_route
417
418        if not globals().get('_FNDP404_CLOSED'):
419            setattr(self.page, 'horizontal_alignment', globals().get('_FNDP404_PRE_H_A')),
420            setattr(self.page, 'vertical_alignment', globals().get('_FNDP404_PRE_V_A')),
421
422        self.process(self.page, self._nav_temp_args, parameters)
423
424        self._nav_temp_args = None

427class VirtualFletNavigator:
428    """The Virtual Flet Navigator. It's just like the public one, but without URL parameters and visible routes."""
429
430    route: str = '/'
431    """The current active route."""
432
433    routes: Routes = {}
434    """A map of all registered routes in the application."""
435
436    previous_routes: list[str] = []
437    """A list of all previously visited routes."""
438
439    homepage: str = '/'
440    """The homepage route."""
441
442    props_map: RouteProperties = {}
443    """A page properties map for each page ID."""
444
445    route_change_callback: RouteChangeCallback = None
446    """A callback function that is triggered when the route changes."""
447
448    def __init__(self, routes: Routes={}, route_change_callback: RouteChangeCallback=None) -> None:
449        """Initialize the virtual navigator."""
450        AbstractFletNavigator.init_nav(self, None, routes, route_change_callback)
451
452    def navigate(self, route: str, page: Page, args: Arguments=()) -> None:
453        """Navigate to a specific route in the application."""
454        AbstractFletNavigator.navigate(self, route, page, args)
455
456    def navigate_homepage(self, page: Page, args: Arguments=()) -> None:
457        """Navigate to the homepage route."""
458        AbstractFletNavigator.navigate_homepage(self, page, args)
459
460    def set_homepage(self, homepage: str) -> None:
461        """Update navigator's homepage address."""
462        AbstractFletNavigator.set_homepage(self, homepage)
463
464    def navigate_back(self, page: Page, args: Arguments=()) -> None:
465        """Navigate back to the previous route."""
466        AbstractFletNavigator.navigate_back(self, page, args)
467
468    def process(self, page: Page, args: Arguments=()) -> None:
469        """Process the current route on the provided page."""
470        AbstractFletNavigator.process(self, page, args)
471
472    def is_virtual(self) -> bool:
473        """Check if the navigator is virtual or public."""
474        return AbstractFletNavigator.is_virtual(self)

477def route(route: Union[str, PageDefinition]) -> Any:
478    """Link a route to the last initialized navigator.
479
480    This function registers the route and associates it with a given page definition.
481    The only difference is the name. You can specify the name in the first argument.
482    or this function will fetch the given function name automatically."""
483    if isinstance(route, Callable):
484        _pre_def_routes[route.__name__] = route
485
486    else:
487        def _route_decorator(page_definition: PageDefinition) -> None:
488            _pre_def_routes[route] = page_definition
489
490        return _route_decorator

493def load_page(path: str, name: Optional[str]=None) -> PageDefinition:
494    """Load a page definition from a specified module.
495
496    Let me explain this technically: it replaces all the system path separators with a dot.
497    After loading the module by its path, it loads the page definition function.
498    The function name is determined by the path. If a name is specified, then it loads the specified name.
499    Otherwise, it uses the last name in the path.
500    
501    Can throw `ModuleNotFoundError` and `AttributeError`."""
502    path = path.replace('\\', '.').replace('/', '.')
503
504    page = None
505
506    try:
507        page = getattr(import_module(path), _pd := path.split('.')[-1] if not name else name)
508    except ModuleNotFoundError:
509        raise TypeError(f'Failed to load page definition module: "{path}".')
510    except AttributeError:
511        raise ImportError(f'Failed to load page definition: "{_pd}".')
512
513    return page

516def template(template_definition: Union[str, TemplateDefinition], route_data: RouteContext, arguments: Arguments=()) -> Optional[Any]:
517    """Render a template for the given page data and arguments.
518    
519    If `template_definition` is a string, then it's a global template.
520    The function will try to find the template you defined earlier via `@global_template` in the list of global templates.
521    If `template_definition` is a callable, then it's a local template.
522    The template will be rendered by calling the template function."""
523    if isinstance(template_definition, str):
524        if template_definition in _global_templates:
525            return _global_templates[template_definition](route_data, arguments)
526
527        else:
528            route_data.navigator._logger.error(f'No global template found with the name: "{template_definition}". Ensure the template is registered and its name is correct.')
529
530    else:
531        return template_definition(route_data, arguments)

534def global_template(template_name: Optional[str]=None) -> Any:
535    """Register a global template to the last initialized navigator.
536
537    This function registers the template and associates it with a given template definition.
538    The only difference is the name. You can specify the name in the first argument.
539    or this function will fetch the given template function name automatically."""
540    if isinstance(template_name, Callable):
541        _global_templates[template_name.__name__] = template_name
542
543    else:
544        def _global_template(template: TemplateDefinition) -> None:
545            _global_templates[template.__name__ if not template_name or not isinstance(template_name, str) else template_name] = template
546
547        return _global_template

550def fn_process(start: str='/', virtual: bool=False, routes: Routes={}, route_change_callback: RouteChangeCallback=None, startup_args: Arguments=(), public_startup_parameters: RouteParameters={}) -> Callable[[Page], None]:
551    """Shortcut to skip main function implementation and just calling `fn_process` in Flet's `app` function.
552    
553    The best way to explain this function is to show an example:
554    ```
555    @route('/')
556    def main(rd: RouteContext) -> None:
557        ...
558
559    app(fn_process()) # Instead of: app(lambda page: PublicFletNavigator(page).process(page))
560    ```"""
561    return lambda page: (
562        fn := PublicFletNavigator(page, routes, route_change_callback),
563
564        setattr(fn, 'route', start),
565
566        fn.process(page, startup_args, public_startup_parameters)) \
567     if not virtual else (
568        fn := VirtualFletNavigator(routes, route_change_callback),
569
570        setattr(fn, 'route', start),
571
572        fn.process(page, startup_args)
573    )