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

dara/core/__init__.py

@@ -16,61 +16,27 @@ limitations under the License.
 """
 # ruff: noqa: F403, F405
 
+import inspect
 from importlib.metadata import version
 
 from pydantic import BaseModel
 
 from dara.core.base_definitions import *
-from dara.core.configuration import ConfigurationBuilder
-from dara.core.css import CSSProperties, get_icon
+from dara.core.configuration import *
+from dara.core.css import *
 from dara.core.definitions import *
 from dara.core.interactivity import *
-from dara.core.visual.components import Fallback
-from dara.core.visual.dynamic_component import py_component
-from dara.core.visual.progress_updater import ProgressUpdater, track_progress
+from dara.core.router import *
+from dara.core.visual.components import *
+from dara.core.visual.dynamic_component import *
+from dara.core.visual.progress_updater import *
 
 __version__ = version('dara-core')
 
 
-# Top-level imports for most commonly used APIs for ease of use
-
-__all__ = [
-    'action',
-    'ActionCtx',
-    'ConfigurationBuilder',
-    'DerivedVariable',
-    'DerivedDataVariable',
-    'DataVariable',
-    'ServerVariable',
-    'UrlVariable',
-    'Cache',
-    'CacheType',
-    'Variable',
-    'py_component',
-    'DownloadVariable',
-    'DownloadContent',
-    'NavigateTo',
-    'Notify',
-    'ResetVariables',
-    'SideEffect',
-    'TriggerVariable',
-    'UpdateVariable',
-    'get_icon',
-    'CSSProperties',
-    'ProgressUpdater',
-    'track_progress',
-    'ComponentInstance',
-    'StyledComponentInstance',
-    'ErrorHandlingConfig',
-    'Fallback',
-    'UpdateVariableImpl',
-    'DownloadContentImpl',
-    'NavigateToImpl',
-]
-
 for symbol in list(globals().values()):
     try:
-        if issubclass(symbol, BaseModel) and symbol is not BaseModel:
+        if inspect.isclass(symbol) and issubclass(symbol, BaseModel) and symbol is not BaseModel:
             symbol.model_rebuild()
     except Exception as e:
         from dara.core.logging import dev_logger

dara/core/configuration.py

@@ -36,6 +36,7 @@ from typing import (
 from fastapi.middleware import Middleware
 from pydantic import ConfigDict
 from starlette.middleware.base import BaseHTTPMiddleware
+from typing_extensions import deprecated
 
 from dara.core.auth.base import BaseAuthConfig
 from dara.core.auth.basic import DefaultAuthConfig
@@ -63,6 +64,7 @@ from dara.core.internal.import_discovery import (
 from dara.core.internal.registry_lookup import CustomRegistryLookup
 from dara.core.internal.scheduler import ScheduledJob, ScheduledJobFactory
 from dara.core.logging import dev_logger
+from dara.core.router import Router
 from dara.core.visual.components import RawString
 from dara.core.visual.themes import BaseTheme, ThemeDef
 
@@ -80,6 +82,7 @@ class Configuration(BaseModel):
     module_dependencies: Dict[str, str]
     live_reload: bool
     powered_by_causalens: bool
+    router: Router
     pages: Dict[str, Page]
     routes: Set[ApiRoute]
     scheduled_jobs: List[Tuple[Union[ScheduledJob, ScheduledJobFactory], Callable, Optional[List[Any]]]] = []
@@ -157,12 +160,13 @@ class ConfigurationBuilder:
     _custom_encoders: Dict[Type[Any], Encoder]
     _middlewares: List[Middleware]
     routes: Set[ApiRoute]
+    router: Router
     static_files_dir: str
     scheduled_jobs: List[Tuple[Union[ScheduledJob, ScheduledJobFactory], Callable, Optional[List[Any]]]] = []
     startup_functions: List[Callable]
     context_components: List[ComponentInstance]
     task_module: Optional[str]
-    template: str
+    _template: str
     theme: BaseTheme
     title: str
 
@@ -175,13 +179,14 @@ class ConfigurationBuilder:
         self._errors = []
         self.enable_devtools = False
         self.live_reload = False
-        self.powered_by_causalens = False
+        self._powered_by_causalens = False
         self._package_tags_processors = []
         self._template_extra_js = ''
         self._pages = {}
         self._template_renderers = {}
         self._endpoint_configurations = []
         self.routes = set()
+        self.router = Router()
         self.static_files_dir = os.path.join(pathlib.Path().parent.parent.absolute(), 'dist')
         self._static_folders = []
         self._middlewares = []
@@ -193,10 +198,31 @@ class ConfigurationBuilder:
         self._custom_ws_handlers = {}
         self._custom_encoders = {}
 
-        self.template = 'default'
+        self._template = 'default'
         self.theme = BaseTheme(main='light')
         self.title = 'decisionApp'
 
+    @property
+    @deprecated('Use `config.router` instead and set a root layout route.')
+    def template(self):
+        return self._template
+
+    @template.setter
+    @deprecated('Use `config.router` instead and set a root layout route.')
+    def template(self, value):
+        self._template = value
+
+    @property
+    def powered_by_causalens(self):
+        return self._powered_by_causalens
+
+    @powered_by_causalens.setter
+    @deprecated(
+        'Pass `powered_by_causalens=` kwarg to SideBarFrame directly, or use the `dara.core.visual.components.PoweredByCausalens` component'
+    )
+    def powered_by_causalens(self, value):
+        self._powered_by_causalens = value
+
     def add_action(self, action: Type[ActionImpl], local: bool = False):
         """
         Register an Action with the application.
@@ -380,6 +406,7 @@ class ConfigurationBuilder:
         """
         self._package_tags_processors.append(processor)
 
+    @deprecated('Use `config.router.add_page` instead.')
     def add_page(
         self,
         name: str,
@@ -436,6 +463,7 @@ class ConfigurationBuilder:
         self._pages[name] = page
         return page
 
+    @deprecated('Use `config.router.add_layout` and set a root layout route instead.')
     def add_template_renderer(self, name: str, template_renderer: Callable[..., Template]) -> str:
         """
         Add a new template renderer that can be selected by name as part of the configuration. By default calling this
@@ -570,10 +598,11 @@ class ConfigurationBuilder:
             enable_devtools=self.enable_devtools,
             module_dependencies=self._module_dependencies,
             live_reload=self.live_reload,
+            pages=self._pages,
             powered_by_causalens=self.powered_by_causalens,
             package_tag_processors=self._package_tags_processors,
-            pages=self._pages,
             routes=self.routes,
+            router=self.router,
             static_files_dir=self.static_files_dir,
             scheduled_jobs=self.scheduled_jobs,
             startup_functions=self.startup_functions,

dara/core/defaults.py

@@ -34,6 +34,7 @@ from dara.core.interactivity.actions import (
     UpdateVariableDef,
 )
 from dara.core.internal.cache_store import CacheStore
+from dara.core.router import Link, LinkDef, Outlet, OutletDef
 from dara.core.visual.components import (
     DefaultFallbackDef,
     DynamicComponent,
@@ -43,6 +44,10 @@ from dara.core.visual.components import (
     ForDef,
     Menu,
     MenuDef,
+    MenuLink,
+    MenuLinkDef,
+    PoweredByCausalens,
+    PoweredByCausalensDef,
     ProgressTracker,
     ProgressTrackerDef,
     RouterContent,
@@ -74,6 +79,7 @@ INITIAL_CORE_INTERNALS = {'Store': _store}
 CORE_COMPONENTS: Dict[str, ComponentTypeAnnotation] = {
     DynamicComponent.__name__: DynamicComponentDef,
     Menu.__name__: MenuDef,
+    MenuLink.__name__: MenuLinkDef,
     ProgressTracker.__name__: ProgressTrackerDef,
     RouterContent.__name__: RouterContentDef,
     SideBarFrame.__name__: SideBarFrameDef,
@@ -82,6 +88,9 @@ CORE_COMPONENTS: Dict[str, ComponentTypeAnnotation] = {
     cast(str, Fallback.Row.py_component): RowFallbackDef,
     cast(str, Fallback.Custom.py_component): CustomFallbackDef,
     For.__name__: ForDef,
+    Link.__name__: LinkDef,
+    Outlet.__name__: OutletDef,
+    PoweredByCausalens.__name__: PoweredByCausalensDef,
 }
 
 # These actions are provided by the core JS of this module

dara/core/definitions.py

@@ -38,12 +38,14 @@ from typing import (
 from fastapi.encoders import jsonable_encoder
 from fastapi.params import Depends
 from pydantic import (
+    BeforeValidator,
     ConfigDict,
     Field,
     SerializerFunctionWrapHandler,
     field_validator,
     model_serializer,
 )
+from typing_extensions import Annotated
 
 from dara.core.base_definitions import Action, ComponentType
 from dara.core.base_definitions import DaraBaseModel as BaseModel
@@ -74,6 +76,22 @@ def _kebab_to_camel(string: str):
     return chunks[0] + ''.join([chunk[0].upper() + chunk[1:].lower() for chunk in chunks[1:]])
 
 
+def transform_raw_css(value: Any):
+    """
+    Transform and validate a raw_css value.
+    """
+    from dara.core.interactivity.client_variable import ClientVariable
+
+    if value is None:
+        return None
+    if isinstance(value, (str, ClientVariable, CSSProperties)):
+        return value
+    if isinstance(value, dict):
+        return {_kebab_to_camel(k): v for k, v in value.items()}
+
+    raise ValueError(f'raw_css must be a CSSProperties, dict, str, None or ClientVariable, got {type(value)}')
+
+
 class ErrorHandlingConfig(BaseModel):
     title: str = DEFAULT_ERROR_TITLE
     """Title to display in the error boundary"""
@@ -81,26 +99,12 @@ class ErrorHandlingConfig(BaseModel):
     description: str = DEFAULT_ERROR_DESCRIPTION
     """Description to display in the error boundary"""
 
-    raw_css: Optional[Any] = None
+    raw_css: Annotated[Optional[Any], BeforeValidator(transform_raw_css)] = None
     """
     Raw styling to apply to the displayed error boundary.
     Accepts a CSSProperties, dict, str, or ClientVariable.
     """
 
-    @field_validator('raw_css', mode='before')
-    @classmethod
-    def validate_raw_css(cls, value):
-        from dara.core.interactivity.client_variable import ClientVariable
-
-        if value is None:
-            return None
-        if isinstance(value, (str, ClientVariable, CSSProperties)):
-            return value
-        if isinstance(value, dict):
-            return {_kebab_to_camel(k): v for k, v in value.items()}
-
-        raise ValueError(f'raw_css must be a CSSProperties, dict, str, None or ClientVariable, got {type(value)}')
-
     def model_dump(self, *args, **kwargs):
         result = super().model_dump(*args, **kwargs)
 
@@ -141,7 +145,7 @@ class ComponentInstance(BaseModel):
     required_routes: ClassVar[List[ApiRoute]] = []
     """List of routes the component depends on. Will be implicitly added to the app if this component is used"""
 
-    raw_css: Optional[Any] = None
+    raw_css: Annotated[Optional[Any], BeforeValidator(transform_raw_css)] = None
     """
     Raw styling to apply to the component.
     Can be an dict/CSSProperties instance representing the `styles` tag, a string injected directly into the CSS of the wrapping component,
@@ -183,7 +187,7 @@ class ComponentInstance(BaseModel):
     """
     An optional unique identifier for the component, defaults to None
 
-    This has no runtime effect and are intended to help identify components with human-readable names in the serialized trees, not in the DOM
+    This is intended to help identify components with human-readable names in the serialized trees, and is also set as the `id` attribute of the DOM element
     """
 
     for_: Optional[str] = None
@@ -213,23 +217,6 @@ class ComponentInstance(BaseModel):
 
         raise ValueError(f'fallback must be a BaseFallback or ComponentInstance, got {type(fallback)}')
 
-    @field_validator('raw_css', mode='before')
-    @classmethod
-    def parse_css(cls, css: Optional[Any]):
-        from dara.core.interactivity.client_variable import ClientVariable
-
-        if css is None:
-            return None
-
-        # If it's a plain dict, change kebab case to camel case
-        if isinstance(css, dict):
-            return {_kebab_to_camel(k): v for k, v in css.items()}
-
-        if isinstance(css, (ClientVariable, CSSProperties, str)):
-            return css
-
-        raise ValueError(f'raw_css must be a CSSProperties, dict, str, None or ClientVariable, got {type(css)}')
-
     @classmethod
     def isinstance(cls, obj: Any) -> bool:
         return isinstance(obj, cls)

dara/core/interactivity/actions.py

@@ -325,7 +325,7 @@ class TriggerVariable(ActionImpl):
         )
 
 
-    config.add_page(name='Trigger Variable', content=test_page())
+    config.router.add_page(path='trigger', content=test_page)
 
     ```
     """
@@ -364,8 +364,8 @@ class NavigateToImpl(ActionImpl):
         )
 
 
-    config.add_page(name='Test Page', content=test_page())
-    config.add_page(name='Another Page', content=another_page())
+    config.router.add_page(path='test-page', content=test_page)
+    config.router.add_page(path='another-page', content=another_page)
 
     ```
     """
@@ -373,7 +373,7 @@ class NavigateToImpl(ActionImpl):
     py_name = 'NavigateTo'
 
     url: Optional[str] = None
-    new_tab: bool
+    new_tab: bool = False
 
 
 @deprecated('Use @action or `NavigateToImpl` for simple cases')
@@ -417,8 +417,8 @@ def NavigateTo(
         )
 
 
-    config.add_page(name='Test Page', content=test_page(), icon=get_icon('shield-dog'))
-    config.add_page(name='Another Page', content=another_page(), icon=get_icon('shield-cat'))
+    config.router.add_page(path='test-page', content=test_page)
+    config.router.add_page(path='another-page', content=another_page)
 
     ```
     """
@@ -473,7 +473,7 @@ def Logout():
         return Stack(Button('Logout', onclick=Logout()))
 
 
-    config.add_page(name='Logout Page', content=test_page())
+    config.router.add_page(path='logout-page', content=test_page)
 
     ```
     """
@@ -511,7 +511,7 @@ class ResetVariables(ActionImpl):
         )
 
 
-    config.add_page(name='ResetVariable', content=test_page(), icon=get_icon('shrimp'))
+    config.router.add_page(path='reset-variable', content=test_page)
 
     ```
 
@@ -565,7 +565,7 @@ class Notify(ActionImpl):
         )
 
 
-    config.add_page(name='Notify Example', content=test_page())
+    config.router.add_page(path='notify-example', content=test_page)
 
     ```
     """
@@ -600,7 +600,7 @@ class DownloadContentImpl(ActionImpl):
         )
 
 
-    config.add_page(name='Download Content', content=test_page)
+    config.router.add_page(path='download-content', content=test_page)
 
     ```
     """
@@ -650,14 +650,14 @@ def DownloadContent(
 
 
     def test_page():
-        return Stack(
-            Button(
-                'Download File', onclick=DownloadContent(resolver=return_csv, extras=[my_var], cleanup_file=False)
-            ),
-        )
+         return Stack(
+             Button(
+                 'Download File', onclick=DownloadContent(resolver=return_csv, extras=[my_var], cleanup_file=False)
+             ),
+         )
 
 
-    config.add_page(name='Download Content', content=test_page)
+    config.router.add_page(path='download-content', content=test_page)
 
     ```
     """
@@ -715,9 +715,9 @@ class DownloadVariable(ActionImpl):
         )
 
 
-    config.add_page(name='Download Variable', content=test_page())
+    config.router.add_page(path='download-variable', content=test_page)
 
-     ```
+    ```
     """
 
     variable: AnyVariable
@@ -764,7 +764,8 @@ def SideEffect(
         return Stack(Select(value=Variable(3), items=[3, 4, 5], onchange=SideEffect(side_effect, extras=[x, y, z])))
 
 
-    config.add_page(name='SideEffect', content=test_page(), icon=get_icon('kiwi-bird'))
+    config.router.add_page(path='side-effect', content=test_page)
+
     ```
     """
 
@@ -937,7 +938,7 @@ class ActionCtx:
             )
 
 
-        config.add_page(name='Trigger Variable', content=test_page())
+        config.router.add_page(path='trigger-variable', content=test_page)
 
         ```
 
@@ -983,8 +984,8 @@ class ActionCtx:
             )
 
 
-        config.add_page(name='Test Page', content=test_page())
-        config.add_page(name='Another Page', content=another_page())
+        config.router.add_page(path='test-page', content=test_page)
+        config.router.add_page(path='another-page', content=another_page)
 
         ```
 
@@ -1014,7 +1015,7 @@ class ActionCtx:
             return Stack(Button('Logout', onclick=logout()))
 
 
-        config.add_page(name='Logout Page', content=test_page())
+        config.router.add_page(path='logout-page', content=test_page)
 
         ```
         """
@@ -1052,7 +1053,7 @@ class ActionCtx:
             )
 
 
-        config.add_page(name='Notify Example', content=test_page())
+        config.router.add_page(path='notify-example', content=test_page)
 
         ```
 
@@ -1097,7 +1098,7 @@ class ActionCtx:
             )
 
 
-        config.add_page(name='ResetVariable', content=test_page(), icon=get_icon('shrimp'))
+        config.router.add_page(path='reset-variable', content=test_page)
 
         ```
 
@@ -1141,7 +1142,7 @@ class ActionCtx:
             )
 
 
-        config.add_page(name='Download Content', content=test_page)
+        config.router.add_page(path='download-content', content=test_page)
 
         ```
 
@@ -1180,7 +1181,7 @@ class ActionCtx:
             )
 
 
-        config.add_page(name='Download Variable', content=test_page())
+        config.router.add_page(path='download-variable', content=test_page)
 
         ```
 
@@ -1229,7 +1230,7 @@ class ActionCtx:
         def task_page():
             return Stack(Text('Status display:'), Text(text=status), Button('Run', onclick=my_task()))
 
-        config.add_page(name='task', content=task_page())
+        config.router.add_page(path='task', content=task_page)
         ```
 
         :param func: the function to run as a task

dara/core/interactivity/switch_variable.py

@@ -67,7 +67,7 @@ class SwitchVariable(ClientVariable):
             title='Admin Panel Demo'
         )
 
-        config.add_page('Admin Demo', content=page_content)
+        config.router.add_page(path='admin', content=page_content)
         ```
 
         Value mapping with defaults:
@@ -109,7 +109,7 @@ class SwitchVariable(ClientVariable):
             title='Role Permissions'
         )
 
-        config.add_page('Permissions Demo', content=page_content)
+        config.router.add_page(path='permissions', content=page_content)
         ```
 
         Complex conditions:

dara/core/internal/execute_action.py

@@ -20,7 +20,8 @@ from __future__ import annotations
 import asyncio
 from collections.abc import Mapping
 from contextvars import ContextVar
-from typing import Any, Callable, Optional, Union
+from functools import partial
+from typing import Any, Callable, Literal, Optional, Union
 
 import anyio
 
@@ -42,13 +43,16 @@ from dara.core.logging import dev_logger
 CURRENT_ACTION_ID = ContextVar('current_action_id', default='')
 
 
-async def _execute_action(handler: Callable, ctx: ActionCtx, values: Mapping[str, Any]):
+async def _execute_action(
+    handler: Callable, ctx: ActionCtx, values: Mapping[str, Any], _on_error: Literal['raise', 'notify'] = 'notify'
+):
     """
     Execute the action handler within the given action context, handling any exceptions that occur.
 
     :param handler: the action handler to execute
     :param ctx: the action context to use
     :param values: the resolved values to pass to the handler
+    :param _on_error: whether to raise or notify on errors
     """
     bound_arg = None
     kwarg_names = list(values.keys())
@@ -71,13 +75,18 @@ async def _execute_action(handler: Callable, ctx: ActionCtx, values: Mapping[str
     try:
         return await run_user_handler(handler, args=args, kwargs=parsed_values)
     except Exception as e:
-        dev_logger.error('Error executing action', e)
-        await ctx.notify('An error occurred while executing the action', 'Error', 'ERROR')
+        if _on_error == 'raise':
+            raise
+        elif _on_error == 'notify':
+            dev_logger.error('Error executing action', e)
+            await ctx.notify('An error occurred while executing the action', 'Error', 'ERROR')
     finally:
         await ctx._end_execution()
 
 
-async def _stream_action(handler: Callable, ctx: ActionCtx, **values: Mapping[str, Any]):
+async def _stream_action(
+    handler: Callable, ctx: ActionCtx, _on_error: Literal['raise', 'notify'] = 'notify', **values: Mapping[str, Any]
+):
     """
     Run the action handler and stream the results to the frontend.
     Executes two tasks in parallel:
@@ -91,13 +100,73 @@ async def _stream_action(handler: Callable, ctx: ActionCtx, **values: Mapping[st
     try:
         async with anyio.create_task_group() as tg:
             # Execute the handler and a stream consumer in parallel
-            tg.start_soon(_execute_action, handler, ctx, values)
+            tg.start_soon(partial(_execute_action, _on_error=_on_error), handler, ctx, values)
             tg.start_soon(ctx._handle_results)
     finally:
         # None is treated as a sentinel value to stop waiting for new actions to come in on the client
         await ctx._on_action(None)
 
 
+async def execute_action_sync(
+    action_def: ActionResolverDef,
+    inp: Any,
+    values: Mapping[str, Any],
+    static_kwargs: Mapping[str, Any],
+    store: CacheStore,
+    task_mgr: TaskManager,
+):
+    """
+    Execute an action until completion.
+    Used for executing `on_load` route actions.
+
+    :param action_def: resolver definition
+    :param inp: input to the action
+    :param values: values from the frontend
+    :param static_kwargs: mapping of var names to current values for static arguments
+    :param store: store instance
+    :param task_mgr: task manager instance - task are not supported here but passed for compat
+    """
+    action = action_def.resolver
+    assert action is not None, 'Action resolver must be defined'
+
+    results = []
+
+    # Construct a context which handles action messages by accumulating them in an array
+    async def handle_action(act_impl: Optional[ActionImpl]):
+        if act_impl is not None:
+            results.append(act_impl)
+
+    ctx = ActionCtx(inp, handle_action)
+    ACTION_CONTEXT.set(ctx)
+
+    resolved_kwargs = {}
+
+    if values is not None:
+        annotations = action.__annotations__
+
+        async def _resolve_kwarg(val: Any, key: str):
+            typ = annotations.get(key)
+            val = await resolve_dependency(val, store, task_mgr)
+            resolved_kwargs[key] = deserialize(val, typ)
+
+        async with anyio.create_task_group() as tg:
+            for key, value in values.items():
+                tg.start_soon(_resolve_kwarg, value, key)
+
+    # Merge resolved dynamic kwargs with static kwargs received
+    resolved_kwargs = {**resolved_kwargs, **static_kwargs}
+
+    # Disallow tasks here
+    has_tasks = any(isinstance(extra, BaseTask) for extra in resolved_kwargs.values())
+    if has_tasks:
+        raise ValueError('This action does not support tasks')
+
+    # Run until completion, raising on errors
+    await _stream_action(action, ctx, _on_error='raise', **resolved_kwargs)
+
+    return results
+
+
 async def execute_action(
     action_def: ActionResolverDef,
     inp: Any,