dara-core 1.20.3__py3-none-any.whl → 1.21.1__py3-none-any.whl

dara/core/main.py

@@ -16,8 +16,10 @@ limitations under the License.
 """
 
 import asyncio
+import json
 import os
 import sys
+import traceback
 from concurrent.futures import ThreadPoolExecutor
 from contextlib import asynccontextmanager
 from importlib.util import find_spec
@@ -27,10 +29,10 @@ from typing import Optional
 
 from anyio import create_task_group
 from fastapi import FastAPI, HTTPException, Request
-from fastapi.encoders import ENCODERS_BY_TYPE
-from fastapi.responses import HTMLResponse
+from fastapi.encoders import ENCODERS_BY_TYPE, jsonable_encoder
 from fastapi.staticfiles import StaticFiles
 from prometheus_client import start_http_server
+from starlette.responses import FileResponse
 from starlette.templating import Jinja2Templates, _TemplateResponse
 
 from dara.core.auth import auth_router
@@ -55,12 +57,11 @@ from dara.core.internal.registries import (
     custom_ws_handlers_registry,
     latest_value_registry,
     sessions_registry,
-    template_registry,
     utils_registry,
     websocket_registry,
 )
 from dara.core.internal.registry_lookup import RegistryLookup
-from dara.core.internal.routing import create_router, error_decorator
+from dara.core.internal.routing import core_api_router, create_loader_route, error_decorator
 from dara.core.internal.settings import get_settings
 from dara.core.internal.tasks import TaskManager
 from dara.core.internal.utils import enforce_sso, import_config
@@ -72,6 +73,16 @@ from dara.core.js_tooling.js_utils import (
     rebuild_js,
 )
 from dara.core.logging import LoggingMiddleware, dev_logger, eng_logger, http_logger
+from dara.core.router import convert_template_to_router
+
+
+class CacheStaticFiles(StaticFiles):
+    async def get_response(self, path, scope):
+        response = await super().get_response(path, scope)
+        # add 1 year cache for static assets
+        if isinstance(response, FileResponse) and path.endswith('.css') or path.endswith('.umd.js'):
+            response.headers['Cache-Control'] = 'public, max-age=31536000'
+        return response
 
 
 def _start_application(config: Configuration):
@@ -94,18 +105,9 @@ def _start_application(config: Configuration):
     import fastapi_vite_dara
     import fastapi_vite_dara.config
 
-    if len(config.pages) > 0:
-        BASE_DIR = Path(__file__).parent
-        jinja_templates = Jinja2Templates(directory=str(Path(BASE_DIR, 'jinja')))
-        jinja_templates.env.globals['vite_hmr_client'] = fastapi_vite_dara.vite_hmr_client
-        jinja_templates.env.globals['vite_asset'] = fastapi_vite_dara.vite_asset
-        jinja_templates.env.globals['static_url'] = fastapi_vite_dara.config.settings.static_url
-        jinja_templates.env.globals['base_url'] = os.getenv('DARA_BASE_URL', '')
-        jinja_templates.env.globals['entry'] = '_entry.tsx'
-
-        # If --enable-hmr or --reload enabled, set live reload to true
-        if os.environ.get('DARA_HMR_MODE') == 'TRUE' or os.environ.get('DARA_LIVE_RELOAD') == 'TRUE':
-            config.live_reload = True
+    # If --enable-hmr or --reload enabled, set live reload to true
+    if os.environ.get('DARA_HMR_MODE') == 'TRUE' or os.environ.get('DARA_LIVE_RELOAD') == 'TRUE':
+        config.live_reload = True
 
     # Configure the default executor for threads run via the async loop
     loop = asyncio.get_event_loop()
@@ -259,26 +261,6 @@ def _start_application(config: Configuration):
     for key, value in encoder_registry.items():
         ENCODERS_BY_TYPE[key] = value['serialize']
 
-    # Generate a new build_cache
-    try:
-        build_cache = BuildCache.from_config(config)
-        build_diff = build_cache.get_diff()
-
-        # Only build if there's pages to build, otherwise assume Dara is only used for API
-        if len(config.pages) > 0:
-            dev_logger.debug(
-                'Building JS...',
-                extra={
-                    'New build cache': build_cache.model_dump(),
-                    'Difference from last cache': build_diff.model_dump(),
-                },
-            )
-            rebuild_js(build_cache, build_diff)
-
-    except Exception as e:
-        dev_logger.error('Error building JS', error=e)
-        sys.exit(1)
-
     # Loop over registered components and add to the registry
     eng_logger.info(f'Registering components [{", ".join([c.name for c in config.components])}]')
     for component in config.components:
@@ -292,37 +274,64 @@ def _start_application(config: Configuration):
     dev_logger.info(f'Using {config.auth_config.__class__.__name__} auth configuration')
     auth_registry.register('auth_config', config.auth_config)
 
+    # Handle pages/router compatibility
+    if len(config.pages) > 0:
+        if len(config.router.children) > 0:
+            raise ValueError(
+                'ConfigurationBuilder.add_page is not compatible with the ConfigurationBuilder.router, `add_page` is supported for backwards compatibility but the recommended API going forward is using `config.router` directly.'
+            )
+
+        try:
+            eng_logger.info('Registering template')
+
+            # Add the default templates
+            if config.template == 'default':
+                eng_logger.info('Registering template "default"')
+                config.router = convert_template_to_router(default_template(config))
+            elif config.template == 'blank':
+                eng_logger.info('Registering template "blank"')
+                config.router = convert_template_to_router(blank_template(config))
+            elif config.template == 'top':
+                eng_logger.info('Registering template "top"')
+                config.router = convert_template_to_router(top_template(config))
+            elif config.template == 'top-menu':
+                eng_logger.info('Registering template "top-menu"')
+                config.router = convert_template_to_router(top_menu_template(config))
+            else:
+                # Loop over user defined templates and add to the registry
+                for name, renderer in config.template_renderers.items():
+                    if name == config.template:
+                        eng_logger.info(f'Registering custom template "{name}"')
+                        config.router = convert_template_to_router(renderer(config))
+                        break
+                else:
+                    raise ValueError(f'Unknown template renderer: {config.template}')
+        except Exception as e:
+            traceback.print_exc()
+            dev_logger.error(
+                'Something went wrong when building application template, there is most likely an issue in the application logic',
+                e,
+            )
+            sys.exit(1)
+
+    # Generate a new build_cache
     try:
-        eng_logger.info('Registering template')
-
-        # Add the default templates
-        if config.template == 'default':
-            eng_logger.info('Registering template "default"')
-            template_registry.register('default', default_template(config))
-        elif config.template == 'blank':
-            eng_logger.info('Registering template "blank"')
-            template_registry.register('blank', blank_template(config))
-        elif config.template == 'top':
-            eng_logger.info('Registering template "top"')
-            template_registry.register('top', top_template(config))
-        elif config.template == 'top-menu':
-            eng_logger.info('Registering template "top-menu"')
-            template_registry.register('top-menu', top_menu_template(config))
-        else:
-            # Loop over user defined templates and add to the registry
-            for name, renderer in config.template_renderers.items():
-                if name == config.template:
-                    eng_logger.info(f'Registering custom template "{name}"')
-                    template_registry.register(name, renderer(config))
+        build_cache = BuildCache.from_config(config)
+        build_diff = build_cache.get_diff()
 
+        # Only build if there's pages to build, otherwise assume Dara is only used for API
+        if len(config.router.children) > 0:
+            dev_logger.debug(
+                'Building JS...',
+                extra={
+                    'New build cache': build_cache.model_dump(),
+                    'Difference from last cache': build_diff.model_dump(),
+                },
+            )
+            rebuild_js(build_cache, build_diff)
     except Exception as e:
-        import traceback
-
         traceback.print_exc()
-        dev_logger.error(
-            'Something went wrong when building application template, there is most likely an issue in the application logic',
-            e,
-        )
+        dev_logger.error('Error building JS', error=e)
         sys.exit(1)
 
     # Root routes
@@ -334,9 +343,6 @@ def _start_application(config: Configuration):
         """
         return {'status': 'ok'}
 
-    # Register the core routes of the application
-    core_api_router = create_router(config)
-
     # Start metrics server in a daemon thread
     if os.environ.get('DARA_DISABLE_METRICS') != 'TRUE' and os.environ.get('DARA_TEST_FLAG', None) is None:
         port = int(os.environ.get('DARA_METRICS_PORT', '10000'))
@@ -352,42 +358,84 @@ def _start_application(config: Configuration):
         start_pprof_server(port=profiling_port)
 
     # Serve statics, only if we have any pages defined
-    if len(config.pages) > 0:
-        app.mount('/static', StaticFiles(directory=config.static_files_dir), name='static')
+    if len(config.router.children) > 0:
+        app.mount('/static', CacheStaticFiles(directory=config.static_files_dir), name='static')
 
     # Mount Routers
     app.include_router(auth_router, prefix='/api/auth')
     app.include_router(core_api_router, prefix='/api/core')
 
-    @app.get('/api/{rest_of_path:path}')
-    async def not_found():
-        raise HTTPException(status_code=404, detail='API endpoint not found')
+    if len(config.router.children) > 0:
+        BASE_DIR = Path(__file__).parent
+        jinja_templates = Jinja2Templates(directory=str(Path(BASE_DIR, 'jinja')))
+        jinja_templates.env.globals['vite_hmr_client'] = fastapi_vite_dara.vite_hmr_client
+        jinja_templates.env.globals['vite_asset'] = fastapi_vite_dara.vite_asset
+        jinja_templates.env.globals['static_url'] = fastapi_vite_dara.config.settings.static_url
+        jinja_templates.env.globals['base_url'] = os.getenv('DARA_BASE_URL', '')
+        jinja_templates.env.globals['entry'] = '_entry.tsx'
+
+        # Compile the router, executing all page functions etc
+        try:
+            config.router.compile()
+        except Exception as e:
+            traceback.print_exc()
+            dev_logger.error('Error compiling router', error=e)
+            sys.exit(1)
+
+        dev_logger.info('Registering pages:')
+        # TODO: convert this to use the logger?
+        config.router.print_route_tree()
+
+        # Add the page data loader route
+        create_loader_route(config, app)
+
+        # Catch-all, must add after adding the last api route
+        @app.get('/api/{rest_of_path:path}')
+        async def not_found():
+            raise HTTPException(status_code=404, detail='API endpoint not found')
+
+        # Prepare static template data
+        template_data = {
+            'auth_components': config.auth_config.component_config.model_dump(),
+            'actions': action_def_registry.get_all().items(),
+            'components': {k: comp.model_dump(exclude={'func'}) for k, comp in component_registry.get_all().items()},
+            'application_name': get_settings().project_name,
+            'enable_devtools': config.enable_devtools,
+            'live_reload': config.live_reload,
+            # TODO: this will become some backendstore-variable instead, prepopulated in here
+            'theme': config.theme,
+            'title': config.title,
+            'context_components': config.context_components,
+            # For backwards compatibility
+            'powered_by_causalens': config.powered_by_causalens,
+            'router': config.router,
+            'build_mode': build_cache.build_config.mode,
+            'build_dev': build_cache.build_config.dev,
+        }
+        json_template_data = json.dumps(jsonable_encoder(template_data))
 
-    if len(config.pages) > 0:
-        dev_logger.info(f'Registering pages: [{", ".join(list(config.pages.keys()))}]')
         # For any unmatched route then serve the app to the user if we have any pages to serve
         # (Required for the chosen routing system in the UI)
 
+        context = {
+            'dara_data': json_template_data,
+        }
+        template_name = 'index.html'
+
         # Auto-js mode - serve the built template with UMDs
         if build_cache.build_config.mode == BuildMode.AUTO_JS:
-            # Load template
-            template_path = os.path.join(Path(BASE_DIR, 'jinja'), 'index_autojs.html')  # type: ignore
-            with open(template_path, encoding='utf-8') as fp:
-                template = fp.read()
-
-            # Generate tags for the template
-            template = build_autojs_template(template, build_cache, config)
+            template_name = 'index_autojs.html'
+            context.update(build_autojs_template(build_cache, config))
 
-            @app.get('/{full_path:path}', include_in_schema=False, response_class=HTMLResponse)
-            async def serve_app(request: Request):  # pyright: ignore[reportRedeclaration]
-                return HTMLResponse(template)
+        @app.get('/{full_path:path}', include_in_schema=False, response_class=_TemplateResponse)
+        async def serve_app(request: Request):
+            return jinja_templates.TemplateResponse(request, template_name, context=context)
 
-        else:
-            # Otherwise serve the Vite template
-
-            @app.get('/{full_path:path}', include_in_schema=False, response_class=_TemplateResponse)
-            async def serve_app(request: Request):  # pyright: ignore[reportRedeclaration]
-                return jinja_templates.TemplateResponse(request, 'index.html')  # type: ignore
+    else:
+        # Catch-all, must be at the very end
+        @app.get('/api/{rest_of_path:path}')
+        async def not_found():
+            raise HTTPException(status_code=404, detail='API endpoint not found')
 
     return app
 

dara/core/persistence.py

@@ -415,7 +415,7 @@ class BackendStore(PersistenceStore):
 
             await self.backend.subscribe(_on_value)
 
-    async def write_partial(self, data: Union[List[Dict[str, Any]], Any], notify: bool = True):
+    async def write_partial(self, data: Union[List[Dict[str, Any]], Any], notify: bool = True, in_place: bool = False):
         """
         Apply partial updates to the store using JSON Patch operations or automatic diffing.
 
@@ -424,6 +424,10 @@ class BackendStore(PersistenceStore):
 
         :param data: Either a list of JSON patch operations (RFC 6902) or a full object to diff against current value
         :param notify: whether to broadcast the patches to clients
+        :param in_place: whether to apply the patches in-place or return a new value.
+        When set to True, the value will be mutated when applying the patches rather than deep-cloned.
+        This is recommended when the updated value is large and deep-cloning it can be expensive; however, users should exercise
+        caution when using the option as previous results retrieved from `store.read()` will potentially be mutated, depending on the backend used.
         """
         if self.readonly:
             raise ValueError('Cannot write to a read-only store')
@@ -451,7 +455,7 @@ class BackendStore(PersistenceStore):
 
             # Apply patches to current value
             try:
-                updated_value = jsonpatch.apply_patch(current_value, patches)
+                updated_value = jsonpatch.apply_patch(current_value, patches, in_place=in_place)
             except (jsonpatch.InvalidJsonPatch, jsonpatch.JsonPatchException) as e:
                 raise ValueError(f'Invalid JSON patch operation: {e}') from e
         else:

dara/core/router/__init__.py

@@ -0,0 +1,5 @@
+# ruff: noqa: F403
+from .compat import *
+from .components import *
+from .dependency_graph import *
+from .router import *

dara/core/router/compat.py

@@ -0,0 +1,77 @@
+from typing import List
+
+from dara.core.definitions import ComponentInstance
+
+from .components import Outlet
+from .router import Router
+
+
+def convert_template_to_router(template):
+    """
+    Convert old template system to new Router structure.
+
+    The conversion maps:
+    - Template.layout becomes the content of a root LayoutRoute, but with transformations:
+      - RouterContent components are replaced with Outlet components
+      - RouterContent.routes are extracted and become PageRoute/IndexRoute children
+    - Routes with route='/' become IndexRoute, others become PageRoute
+    - Route paths are normalized (leading slashes removed)
+
+    :param template: Template object with layout component containing RouterContent
+    :return: Router instance with converted structure
+    """
+    from dara.core.definitions import TemplateRouterContent
+    from dara.core.visual.components.router_content import RouterContent
+
+    router = Router()
+    extracted_routes: List[TemplateRouterContent] = []
+
+    # Transform the layout: replace RouterContent with Outlet and extract routes
+    def transform_component(component):
+        """Recursively transform components, replacing RouterContent with Outlet"""
+        # For other components, recursively transform their children/content
+        if isinstance(component, ComponentInstance):
+            if isinstance(component, RouterContent):
+                extracted_routes.extend(component.routes)
+                return Outlet()
+
+            for attr in component.model_fields_set:
+                value = getattr(component, attr, None)
+                if isinstance(value, ComponentInstance):
+                    setattr(component, attr, transform_component(value))
+                elif isinstance(value, list) and len(value) > 0 and isinstance(value[0], ComponentInstance):
+                    setattr(component, attr, [transform_component(item) for item in value])
+
+        return component
+
+    # Create root layout route using transformed template layout
+    root_layout = router.add_layout(content=transform_component(template.layout))
+
+    # Convert extracted routes to appropriate route types
+    for route_content in extracted_routes:
+        # Normalize route path: remove leading slash and handle root
+        route_path = route_content.route
+        if route_path.startswith('/'):
+            route_path = route_path[1:]
+
+        # NOTE: here it's safe to use the name as the id, as in the old api the name was unique
+        # but use 'index' for empty strings
+
+        # Root path becomes index route
+        if route_path in {'', '/'}:
+            root_layout.add_index(
+                content=route_content.content,
+                name=route_content.name,
+                id=route_content.name or 'index',
+                on_load=route_content.on_load,
+            )
+        else:
+            root_layout.add_page(
+                path=route_path,
+                content=route_content.content,
+                name=route_content.name,
+                id=route_content.name or 'index',
+                on_load=route_content.on_load,
+            )
+
+    return router

dara/core/router/components.py

@@ -0,0 +1,143 @@
+from typing import Annotated, Any, Literal, Optional, Union
+
+from pydantic import BaseModel, BeforeValidator
+
+from dara.core.definitions import ComponentInstance, JsComponentDef, StyledComponentInstance, transform_raw_css
+
+
+class RouterPath(BaseModel):
+    path: str
+    """
+    A URL pathname, beginning with '/'.
+    """
+
+    search: Optional[str] = None
+    """
+    A URL search string, beginning with '?'.
+    """
+
+    hash: Optional[str] = None
+    """
+    A URL hash string, beginning with '#'.
+    """
+
+
+OutletDef = JsComponentDef(name='Outlet', js_module='@darajs/core', py_module='dara.core')
+
+
+class Outlet(ComponentInstance):
+    """
+    Outlet component is a placeholder for the content of the current route.
+    """
+
+
+LinkDef = JsComponentDef(name='Link', js_module='@darajs/core', py_module='dara.core')
+
+
+class Link(StyledComponentInstance):
+    """
+    Link component is a wrapper around the NavLink component that displays a link to the specified route.
+    """
+
+    case_sensitive: bool = False
+
+    end: bool = True
+    """
+    Changes the matching logic for the 'active' state to only match the end of the 'to' prop.
+    If the URL is longer, it will not be considered active. Defaults to True.
+
+    For example, NavLink(to='/tasks') while on '/tasks/123' will:
+    - with `end=False`, be considered active because of the partial match of the `/tasks` part
+    - with `end=True`, be considered inactive because of the missing '123' part
+    """
+
+    # TODO: consider making it True by default in Dara v2
+    prefetch: bool = False
+    """
+    Whether to prefetch the navigation data when user intends to navigate to the link.
+    When set to True, whenever the user hovers or focuses the link, the navigation data will be prefetched
+    and cached for a short period of time to speed up navigation.
+    Defaults to False.
+    """
+
+    relative: Literal['route', 'path'] = 'route'
+    """
+    Defines the relative path behavior for the link.
+
+    ```python
+    Link(to='..') # default, relative='route'
+    Link(to='..', relative='path')
+    ```
+
+    Consider a route hierarchy where a parent route pattern is "blog" and a child route pattern is "blog/:slug/edit".
+    - route — default, resolves the link relative to the route pattern. In the example above, a relative link of "..." will remove both :slug/edit segments back to "/blog".
+    - path — relative to the path so "..." will only remove one URL segment up to "/blog/:slug"
+    Note that index routes and layout routes do not have paths so they are not included in the relative path calculation.
+    """
+
+    replace: bool = False
+    """
+    Replaces the current entry in the history stack instead of pushing a new one.
+
+    ```
+    # with a history stack like this
+    A -> B
+
+    # normal link click pushes a new entry
+    A -> B -> C
+
+    # but with `replace`, B is replaced by C
+    A -> C
+    ```
+    """
+
+    to: Union[str, RouterPath]
+    """
+    Can be a string or RouterPath object
+    """
+
+    active_css: Annotated[Optional[Any], BeforeValidator(transform_raw_css)] = None
+    inactive_css: Annotated[Optional[Any], BeforeValidator(transform_raw_css)] = None
+
+    # TODO: add scroll restoration if it works?
+
+    def __init__(self, *children: ComponentInstance, **kwargs):
+        components = list(children)
+        if 'children' not in kwargs:
+            kwargs['children'] = components
+        super().__init__(**kwargs)
+
+
+MenuLinkDef = JsComponentDef(name='MenuLink', js_module='@darajs/core', py_module='dara.core')
+
+
+class MenuLink(Link):
+    """
+    Styled version of Link component, ready to be used with e.g. the built-in SideBarFrame component.
+    Accepts all the same props as the Link component, can be used as a drop-in replacement.
+
+    ```python
+    from dara.core.visual.components import MenuLink, SideBarFrame
+    from dara.core.router import Router, Outlet
+
+    router = Router()
+
+    def RootLayout():
+        routes = router.get_navigable_routes()
+
+        return SideBarFrame(
+            side_bar=Stack(
+                *[MenuLink(Text(path['name']), to=path['path']) for path in routes],
+            ),
+            content=Outlet(),
+        )
+
+    root = router.add_layout(content=RootLayout)
+    ```
+    """
+
+    def __init__(self, *children: ComponentInstance, **kwargs):
+        els = list(children)
+        if 'children' not in kwargs:
+            kwargs['children'] = els
+        super().__init__(**kwargs)

dara/core/router/dependency_graph.py

@@ -0,0 +1,62 @@
+from typing import Dict
+
+from pydantic import BaseModel, Field, SerializeAsAny
+
+from dara.core.definitions import ComponentInstance
+from dara.core.interactivity.derived_variable import DerivedVariable
+from dara.core.visual.dynamic_component import PyComponentInstance
+
+
+class DependencyGraph(BaseModel):
+    """
+    Data structure representing dependencies for derived state on a page
+    """
+
+    derived_variables: SerializeAsAny[Dict[str, DerivedVariable]] = Field(default_factory=dict)
+    """
+    Map of DerivedVariable instances
+    """
+
+    py_components: SerializeAsAny[Dict[str, PyComponentInstance]] = Field(default_factory=dict)
+    """
+    Map of PyComponentInstance instances
+    """
+
+    @staticmethod
+    def from_component(component: ComponentInstance) -> 'DependencyGraph':
+        """
+        Create a DependencyGraph from a ComponentInstance
+        """
+        graph = DependencyGraph()
+        _analyze_component_dependencies(component, graph)
+        return graph
+
+
+def _analyze_component_dependencies(component: ComponentInstance, graph: DependencyGraph) -> None:
+    """
+    Recursively analyze a component tree to build a dependency graph of DerivedVariables and PyComponentInstances.
+    """
+    # The component itself is a PyComponentInstance
+    if isinstance(component, PyComponentInstance):
+        if component.uid not in graph.py_components:
+            graph.py_components[component.uid] = component
+        return
+
+    # otherwise check each field
+    for attr in component.model_fields_set:
+        value = getattr(component, attr, None)
+
+        # Handle encountered variables and py_components
+        if isinstance(value, DerivedVariable) and value.uid not in graph.derived_variables:
+            graph.derived_variables[value.uid] = value
+        elif isinstance(value, PyComponentInstance) and value.uid not in graph.py_components:
+            graph.py_components[value.uid] = value
+        # Recursion cases:
+        # component instances
+        elif isinstance(value, ComponentInstance):
+            _analyze_component_dependencies(value, graph)
+        # component lists
+        elif isinstance(value, list):
+            for item in value:
+                if isinstance(item, ComponentInstance):
+                    _analyze_component_dependencies(item, graph)