dara-core 1.20.3__py3-none-any.whl → 1.21.1__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, MenuLink, MenuLinkDef, Outlet, OutletDef
 from dara.core.visual.components import (
     DefaultFallbackDef,
     DynamicComponent,
@@ -43,6 +44,8 @@ from dara.core.visual.components import (
     ForDef,
     Menu,
     MenuDef,
+    PoweredByCausalens,
+    PoweredByCausalensDef,
     ProgressTracker,
     ProgressTrackerDef,
     RouterContent,
@@ -74,6 +77,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 +86,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)
 
@@ -119,7 +123,7 @@ class ComponentInstance(BaseModel):
     Definition of a Component Instance
     """
 
-    uid: Optional[str] = Field(default_factory=lambda: str(uuid.uuid4()))
+    uid: str = Field(default_factory=lambda: str(uuid.uuid4()))
 
     js_module: ClassVar[Optional[str]] = None
     """
@@ -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/plain_variable.py

@@ -284,7 +284,7 @@ class Variable(ClientVariable, Generic[VariableType]):
         assert isinstance(self.store, BackendStore), 'This method can only be used with a BackendStore'
         return await self.store.write(value, notify=notify, ignore_channel=ignore_channel)
 
-    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 variable's BackendStore using JSON Patch operations or automatic diffing.
         Raises an error if the variable does not have a BackendStore attached.
@@ -294,9 +294,13 @@ class Variable(ClientVariable, Generic[VariableType]):
 
         :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 `variable.read()` will potentially be mutated, depending on the backend used.
         """
         assert isinstance(self.store, BackendStore), 'This method can only be used with a BackendStore'
-        return await self.store.write_partial(data, notify=notify)
+        return await self.store.write_partial(data, notify=notify, in_place=in_place)
 
     async def read(self):
         """

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: