dara-core 1.20.1a1__py3-none-any.whl → 1.20.1a3__py3-none-any.whl

dara/core/definitions.py

@@ -19,15 +19,14 @@ from __future__ import annotations
 
 import json
 import uuid
+from collections.abc import Awaitable, Mapping
 from enum import Enum
 from typing import (
     Any,
-    Awaitable,
     Callable,
     ClassVar,
     List,
     Literal,
-    Mapping,
     Optional,
     Protocol,
     Type,
@@ -85,22 +84,22 @@ class ErrorHandlingConfig(BaseModel):
     raw_css: Optional[Any] = None
     """
     Raw styling to apply to the displayed error boundary.
-    Accepts a CSSProperties, dict, str, or NonDataVariable.
+    Accepts a CSSProperties, dict, str, or ClientVariable.
     """
 
     @field_validator('raw_css', mode='before')
     @classmethod
     def validate_raw_css(cls, value):
-        from dara.core.interactivity.non_data_variable import NonDataVariable
+        from dara.core.interactivity.client_variable import ClientVariable
 
         if value is None:
             return None
-        if isinstance(value, (str, NonDataVariable, CSSProperties)):
+        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 NonDataVariable, got {type(value)}')
+        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)
@@ -146,7 +145,7 @@ class ComponentInstance(BaseModel):
     """
     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,
-    or a NonDataVariable resoling to either of the above.
+    or a ClientVariable resoling to either of the above.
 
     ```python
 
@@ -175,7 +174,7 @@ class ComponentInstance(BaseModel):
     error_handler: Optional[ErrorHandlingConfig] = None
     """Configure the error handling for the component"""
 
-    fallback: Optional[BaseFallback] = None
+    fallback: Optional[Union[BaseFallback, ComponentInstance]] = None
     """
     Fallback component to render in place of the actual UI if it has not finished loading
     """
@@ -197,10 +196,27 @@ class ComponentInstance(BaseModel):
     def __repr__(self):
         return '__dara__' + json.dumps(jsonable_encoder(self))
 
+    @field_validator('fallback', mode='before')
+    @classmethod
+    def validate_fallback(cls, fallback):
+        if fallback is None:
+            return None
+
+        if isinstance(fallback, BaseFallback):
+            return fallback
+
+        # wrap custom component in fallback.custom
+        if isinstance(fallback, ComponentInstance):
+            from dara.core.visual.components.fallback import Fallback
+
+            return Fallback.Custom(component=fallback)
+
+        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.non_data_variable import NonDataVariable
+        from dara.core.interactivity.client_variable import ClientVariable
 
         if css is None:
             return None
@@ -209,10 +225,10 @@ class ComponentInstance(BaseModel):
         if isinstance(css, dict):
             return {_kebab_to_camel(k): v for k, v in css.items()}
 
-        if isinstance(css, (NonDataVariable, CSSProperties, str)):
+        if isinstance(css, (ClientVariable, CSSProperties, str)):
             return css
 
-        raise ValueError(f'raw_css must be a CSSProperties, dict, str, None or NonDataVariable, got {type(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:
@@ -264,8 +280,7 @@ class CallableClassComponent(Protocol):
     Callable class component protocol. Describes any class with a __call__ instance method returning a component instance.
     """
 
-    def __call__(self) -> ComponentInstance:
-        ...
+    def __call__(self) -> ComponentInstance: ...
 
 
 DiscoverTarget = Union[Callable[..., ComponentInstance], ComponentInstance, Type[CallableClassComponent]]
@@ -279,7 +294,7 @@ def discover(outer_obj: DiscoverT) -> DiscoverT:
     Will make sure to statically register all encountered dependencies of marked functional component or component class.
     Should not be necessary in most cases, mainly useful when creating component libraries.
     """
-    outer_obj.__wrapped_by__ = discover   # type: ignore
+    outer_obj.__wrapped_by__ = discover  # type: ignore
     return outer_obj
 
 
@@ -419,9 +434,8 @@ class BaseFallback(StyledComponentInstance):
     @field_validator('suspend_render')
     @classmethod
     def validate_suspend_render(cls, value):
-        if isinstance(value, int):
-            if value < 0:
-                raise ValueError('suspend_render must be a positive integer')
+        if isinstance(value, int) and value < 0:
+            raise ValueError('suspend_render must be a positive integer')
 
         return value
 
@@ -461,13 +475,30 @@ class PyComponentDef(BaseModel):
     func: Optional[Callable[..., Any]] = None
     name: str
     dynamic_kwargs: Optional[Mapping[str, AnyVariable]] = None
-    fallback: Optional[BaseFallback] = None
+    fallback: Optional[Union[BaseFallback, ComponentInstance]] = None
     polling_interval: Optional[int] = None
     render_component: Callable[..., Awaitable[Any]]
     """Handler to render the component. Defaults to dara.core.visual.dynamic_component.render_component"""
 
     type: Literal[ComponentType.PY] = ComponentType.PY
 
+    @field_validator('fallback', mode='before')
+    @classmethod
+    def validate_fallback(cls, fallback):
+        if fallback is None:
+            return None
+
+        if isinstance(fallback, BaseFallback):
+            return fallback
+
+        # wrap custom component in fallback.custom
+        if isinstance(fallback, ComponentInstance):
+            from dara.core.visual.components.fallback import Fallback
+
+            return Fallback.Custom(component=fallback)
+
+        raise ValueError(f'fallback must be a BaseFallback or ComponentInstance, got {type(fallback)}')
+
 
 # Helper type annotation for working with components
 ComponentTypeAnnotation = Union[PyComponentDef, JsComponentDef]
@@ -505,7 +536,7 @@ class Page(BaseModel):
     icon: Optional[str] = None
     content: ComponentInstanceType
     name: str
-    sub_pages: Optional[List['Page']] = []
+    sub_pages: Optional[List[Page]] = []
     url_safe_name: str
     include_in_menu: Optional[bool] = None
     on_load: Optional[Action] = None

dara/core/http.py

@@ -18,7 +18,7 @@ limitations under the License.
 import inspect
 from collections import OrderedDict
 from functools import wraps
-from typing import Callable, Dict, List, Type
+from typing import Callable, Dict, List, Type, Union
 
 from fastapi import Depends
 from fastapi.params import Depends as DependsType
@@ -54,7 +54,10 @@ def _get_config_instances(annotations: Dict[str, type]) -> Dict[str, EndpointCon
 def _method_decorator(method: HttpMethod):
     """Create a decorator for a given HTTP method"""
 
-    def _decorator(url: str, dependencies: List[DependsType] = [], authenticated: bool = True):
+    def _decorator(url: str, dependencies: Union[List[DependsType], None] = None, authenticated: bool = True):
+        if dependencies is None:
+            dependencies = []
+
         def _inner(func: Callable):
             # Make sure we're using a copy of the dependencies list
             final_dependencies = dependencies[:]
@@ -104,7 +107,8 @@ def _method_decorator(method: HttpMethod):
 
             new_handler.__annotations__ = new_annotations
             new_handler.__signature__ = inspect.Signature(  # type: ignore
-                parameters=list(params.values()), return_annotation=sig.return_annotation  # type: ignore
+                parameters=list(params.values()),
+                return_annotation=sig.return_annotation,  # type: ignore
             )
 
             return ApiRoute(

dara/core/interactivity/__init__.py

@@ -36,12 +36,15 @@ from dara.core.interactivity.actions import (
 )
 from dara.core.interactivity.any_data_variable import AnyDataVariable
 from dara.core.interactivity.any_variable import AnyVariable
+from dara.core.interactivity.client_variable import ClientVariable
 from dara.core.interactivity.condition import Condition, Operator
 from dara.core.interactivity.data_variable import DataVariable
 from dara.core.interactivity.derived_data_variable import DerivedDataVariable
 from dara.core.interactivity.derived_variable import DerivedVariable
 from dara.core.interactivity.non_data_variable import NonDataVariable
 from dara.core.interactivity.plain_variable import Variable
+from dara.core.interactivity.server_variable import ServerVariable
+from dara.core.interactivity.state_variable import StateVariable
 from dara.core.interactivity.switch_variable import SwitchVariable
 from dara.core.interactivity.url_variable import UrlVariable
 
@@ -50,9 +53,11 @@ __all__ = [
     'ActionCtx',
     'AnyVariable',
     'AnyDataVariable',
+    'ClientVariable',
     'DataVariable',
     'NonDataVariable',
     'Variable',
+    'StateVariable',
     'SwitchVariable',
     'DerivedVariable',
     'DerivedDataVariable',
@@ -67,6 +72,7 @@ __all__ = [
     'TriggerVariable',
     'UpdateVariable',
     'UpdateVariableImpl',
+    'ServerVariable',
     'SideEffect',
     'Condition',
     'Operator',

dara/core/interactivity/actions.py

@@ -17,16 +17,17 @@ limitations under the License.
 
 from __future__ import annotations
 
+import contextlib
 import inspect
 import math
 import uuid
+from collections.abc import Awaitable
 from contextvars import ContextVar
 from enum import Enum
 from functools import partial, update_wrapper
 from typing import (
     TYPE_CHECKING,
     Any,
-    Awaitable,
     Callable,
     ClassVar,
     Dict,
@@ -43,17 +44,18 @@ import anyio
 from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
 from pandas import DataFrame
 from pydantic import ConfigDict
-from typing_extensions import deprecated
+from typing_extensions import TypeAlias, deprecated
 
 from dara.core.base_definitions import (
     ActionDef,
     ActionImpl,
     ActionResolverDef,
     AnnotatedAction,
+    TaskProgressUpdate,
 )
 from dara.core.base_definitions import DaraBaseModel as BaseModel
-from dara.core.base_definitions import TaskProgressUpdate
-from dara.core.interactivity.data_variable import DataVariable
+from dara.core.interactivity.server_variable import ServerVariable
+from dara.core.interactivity.state_variable import StateVariable
 from dara.core.internal.download import generate_download_code
 from dara.core.internal.registry_lookup import RegistryLookup
 from dara.core.internal.utils import run_user_handler
@@ -63,10 +65,8 @@ if TYPE_CHECKING:
     from dara.core.interactivity import (
         AnyVariable,
         DerivedVariable,
-        UrlVariable,
         Variable,
     )
-    from dara.core.internal.cache_store import CacheStore
 
 
 class ActionInputs(BaseModel):
@@ -97,7 +97,7 @@ class ComponentActionContext(ActionContext):
     ActionContext for actions that only require component value
     """
 
-    inputs: ComponentActionInputs   # type: ignore
+    inputs: ComponentActionInputs  # type: ignore
 
 
 class UpdateVariableImpl(ActionImpl):
@@ -124,7 +124,7 @@ class UpdateVariableImpl(ActionImpl):
 
     py_name = 'UpdateVariable'
 
-    variable: Union[Variable, UrlVariable, DataVariable]
+    variable: Union[Variable, ServerVariable]
     value: Any
 
     INPUT: ClassVar[str] = '__dara_input__'
@@ -134,19 +134,18 @@ class UpdateVariableImpl(ActionImpl):
     """Special value for `value` that will toggle the variable value"""
 
     async def execute(self, ctx: ActionCtx) -> Any:
-        if isinstance(self.variable, DataVariable):
+        if isinstance(self.variable, ServerVariable):
             # Update on the backend
             from dara.core.internal.registries import (
-                data_variable_registry,
+                server_variable_registry,
                 utils_registry,
             )
 
-            store: CacheStore = utils_registry.get('Store')
             registry_mgr: RegistryLookup = utils_registry.get('RegistryLookup')
 
-            var_entry = await registry_mgr.get(data_variable_registry, self.variable.uid)
-            DataVariable.update_value(var_entry, store, self.value)
-            # Don't notify frontend explicitly, all clients will be notified by update_value above
+            var_entry = await registry_mgr.get(server_variable_registry, self.variable.uid)
+            await ServerVariable.write_value(var_entry, self.value)
+            # Don't notify frontend explicitly, all clients will be notified by write_value above
             return None
 
         # for non-data variables just ping frontend with the new value
@@ -162,7 +161,7 @@ class UpdateVariableInputs(ActionInputs):
 
 
 class UpdateVariableContext(ActionContext):
-    inputs: UpdateVariableInputs   # type: ignore
+    inputs: UpdateVariableInputs  # type: ignore
 
 
 @deprecated('Use @action or `UpdateVariableImpl` for simple cases')
@@ -171,7 +170,7 @@ class UpdateVariable(AnnotatedAction):
     @deprecated: Passing in resolvers is deprecated, use `ctx.update` in an `@action` or `UpdateVariableImpl` instead.
     `UpdateVariableImpl` will be renamed to `UpdateVariable` in Dara 2.0.
 
-    The UpdateVariable action can be passed to any `ComponentInstance` prop accepting an action and trigger the update of a Variable, UrlVariable or DataVariable.
+    The UpdateVariable action can be passed to any `ComponentInstance` prop accepting an action and trigger the update of a Variable or ServerVariable.
     The resolver function takes a Context param which will feed the `inputs`: `old` and `new` as well as any `extras` passed through.
 
     Below an example of how a resolver might look:
@@ -239,13 +238,13 @@ class UpdateVariable(AnnotatedAction):
 
     Ctx: ClassVar[type[UpdateVariableContext]] = UpdateVariableContext
 
-    variable: Union[Variable, DataVariable, UrlVariable]
+    variable: Union[Variable, ServerVariable]
     extras: Optional[List[AnyVariable]]
 
     def __init__(
         self,
         resolver: Callable[[UpdateVariableContext], Any],
-        variable: Union[Variable, DataVariable, UrlVariable],
+        variable: Union[Variable, ServerVariable],
         extras: Optional[List[AnyVariable]] = None,
     ):
         """
@@ -254,8 +253,8 @@ class UpdateVariable(AnnotatedAction):
         :param extras: any extra variables to resolve and pass to the resolution function context
         """
 
-        async def _update(ctx: action.Ctx, **kwargs):   # type: ignore
-            ctx = cast(ActionCtx, ctx)   # type: ignore
+        async def _update(ctx: action.Ctx, **kwargs):  # type: ignore
+            ctx = cast(ActionCtx, ctx)  # type: ignore
             old = kwargs.pop('old')
             extras = [kwargs[f'kwarg_{idx}'] for idx in range(len(kwargs))]
             old_ctx = UpdateVariableContext(inputs=UpdateVariableInputs(old=old, new=ctx.input), extras=extras)
@@ -271,7 +270,7 @@ class UpdateVariable(AnnotatedAction):
                 for idx in range(len(extras or []))
             ],
         ]
-        _update.__signature__ = inspect.Signature(params)   # type: ignore
+        _update.__signature__ = inspect.Signature(params)  # type: ignore
 
         # Pass in variable and extras as kwargs
         kwargs = {f'kwarg_{idx}': value for idx, value in enumerate(extras or [])}
@@ -428,11 +427,11 @@ def NavigateTo(
         return NavigateToImpl(url=url, new_tab=new_tab)
 
     # Otherwise create a new @action with the provided resolver
-    async def _navigate(ctx: action.Ctx, **kwargs):   # type: ignore
-        ctx = cast(ActionCtx, ctx)   # type: ignore
+    async def _navigate(ctx: action.Ctx, **kwargs):  # type: ignore
+        ctx = cast(ActionCtx, ctx)  # type: ignore
         extras = [kwargs[f'kwarg_{idx}'] for idx in range(len(kwargs))]
         old_ctx = ComponentActionContext(inputs=ComponentActionInputs(value=ctx.input), extras=extras)
-        result = await run_user_handler(url, args=(old_ctx,))   # type: ignore
+        result = await run_user_handler(url, args=(old_ctx,))  # type: ignore
         # Navigate to resulting url
         await ctx.navigate(result, new_tab)
 
@@ -444,14 +443,14 @@ def NavigateTo(
             for idx in range(len(extras or []))
         ],
     ]
-    _navigate.__signature__ = inspect.Signature(params)   # type: ignore
+    _navigate.__signature__ = inspect.Signature(params)  # type: ignore
 
     # Pass in variable and extras as kwargs
     kwargs = {f'kwarg_{idx}': value for idx, value in enumerate(extras or [])}
     return action(_navigate)(**kwargs)
 
 
-NavigateTo.Ctx = ComponentActionContext   # type: ignore
+NavigateTo.Ctx = ComponentActionContext  # type: ignore
 
 
 def Logout():
@@ -627,13 +626,13 @@ def DownloadContent(
 
     ```python
 
-    from dara.core import action, ConfigurationBuilder, DataVariable, DownloadContent
+    from dara.core import action, ConfigurationBuilder, ServerVariable, DownloadContent
     from dara.components.components import Button, Stack
 
 
     # generate data, alternatively you could load it from a file
     df = pandas.DataFrame(data={'x': [1, 2, 3], 'y':[4, 5, 6]})
-    my_var = DataVariable(df)
+    my_var = ServerVariable(df)
 
     config = ConfigurationBuilder()
 
@@ -663,8 +662,8 @@ def DownloadContent(
     ```
     """
 
-    async def _download(ctx: action.Ctx, **kwargs):   # type: ignore
-        ctx = cast(ActionCtx, ctx)   # type: ignore
+    async def _download(ctx: action.Ctx, **kwargs):  # type: ignore
+        ctx = cast(ActionCtx, ctx)  # type: ignore
         extras = [kwargs[f'kwarg_{idx}'] for idx in range(len(kwargs))]
         old_ctx = ComponentActionContext(inputs=ComponentActionInputs(value=ctx.input), extras=extras)
         result = await run_user_handler(resolver, args=(old_ctx,))
@@ -678,7 +677,7 @@ def DownloadContent(
             for idx in range(len(extras or []))
         ],
     ]
-    _download.__signature__ = inspect.Signature(params)   # type: ignore
+    _download.__signature__ = inspect.Signature(params)  # type: ignore
 
     # Pass in extras as kwargs
     kwargs = {f'kwarg_{idx}': value for idx, value in enumerate(extras or [])}
@@ -686,7 +685,7 @@ def DownloadContent(
     return action(_download)(**kwargs)
 
 
-DownloadContent.Ctx = ComponentActionContext   # type: ignore
+DownloadContent.Ctx = ComponentActionContext  # type: ignore
 """@deprecated retained for backwards compatibility, to be removed in 2.0"""
 
 DownloadVariableDef = ActionDef(name='DownloadVariable', js_module='@darajs/core', py_module='dara.core')
@@ -769,8 +768,8 @@ def SideEffect(
     ```
     """
 
-    async def _effect(ctx: action.Ctx, **kwargs):   # type: ignore
-        ctx = cast(ActionCtx, ctx)   # type: ignore
+    async def _effect(ctx: action.Ctx, **kwargs):  # type: ignore
+        ctx = cast(ActionCtx, ctx)  # type: ignore
         extras = [kwargs[f'kwarg_{idx}'] for idx in range(len(kwargs))]
         old_ctx = ComponentActionContext(inputs=ComponentActionInputs(value=ctx.input), extras=extras)
         # Simply run the user handler
@@ -784,7 +783,7 @@ def SideEffect(
             for idx in range(len(extras or []))
         ],
     ]
-    _effect.__signature__ = inspect.Signature(params)   # type: ignore
+    _effect.__signature__ = inspect.Signature(params)  # type: ignore
 
     # Pass in extras as kwargs
     kwargs = {f'kwarg_{idx}': value for idx, value in enumerate(extras or [])}
@@ -792,7 +791,7 @@ def SideEffect(
     return action(_effect)(**kwargs)
 
 
-SideEffect.Ctx = ComponentActionContext   # type: ignore
+SideEffect.Ctx = ComponentActionContext  # type: ignore
 """@deprecated retained for backwards compatibility, to be removed in 2.0"""
 
 VariableT = TypeVar('VariableT')
@@ -825,14 +824,12 @@ class ActionCtx:
         self._on_action = _on_action
 
     @overload
-    async def update(self, variable: DataVariable, value: Optional[DataFrame]):
-        ...
+    async def update(self, variable: ServerVariable, value: Optional[DataFrame]): ...
 
     @overload
-    async def update(self, variable: Union[Variable[VariableT], UrlVariable[VariableT]], value: VariableT):
-        ...
+    async def update(self, variable: Variable[VariableT], value: VariableT): ...
 
-    async def update(self, variable: Union[Variable, UrlVariable, DataVariable], value: Any):
+    async def update(self, variable: Union[Variable, ServerVariable], value: Any):
         """
         Update a given variable to provided value.
 
@@ -1115,12 +1112,12 @@ class ActionCtx:
 
         ```python
 
-        from dara.core import action, ConfigurationBuilder, DataVariable
+        from dara.core import action, ConfigurationBuilder, ServerVariable
         from dara.components.components import Button, Stack
 
         # generate data, alternatively you could load it from a file
         df = pandas.DataFrame(data={'x': [1, 2, 3], 'y':[4, 5, 6]})
-        my_var = DataVariable(df)
+        my_var = ServerVariable(df)
 
         config = ConfigurationBuilder()
 
@@ -1246,6 +1243,7 @@ class ActionCtx:
         task_mgr: TaskManager = utils_registry.get('TaskManager')
 
         task = Task(func=func, args=args, kwargs=kwargs, on_progress=on_progress)
+        task_mgr.register_task(task)
         pending_task = await task_mgr.run_task(task)
         return await pending_task.value()
 
@@ -1330,7 +1328,7 @@ class action:
     ```
     """
 
-    Ctx: ClassVar[type[ActionCtx]] = ActionCtx
+    Ctx: TypeAlias = ActionCtx
 
     def __init__(self, func: Callable[..., Any]):
         from dara.core.internal.execute_action import execute_action
@@ -1389,11 +1387,10 @@ class action:
         return bound_f
 
     @overload
-    def __call__(self, ctx: ActionCtx, *args: Any, **kwargs: Any) -> Any:
-        ...
+    def __call__(self, ctx: ActionCtx, *args: Any, **kwargs: Any) -> Any: ...
 
     @overload
-    def __call__(self, *args: Any, **kwargs: Any) -> AnnotatedAction:   # type: ignore
+    def __call__(self, *args: Any, **kwargs: Any) -> AnnotatedAction:  # type: ignore
         ...
 
     def __call__(self, *args, **kwargs) -> Union[AnnotatedAction, Any]:
@@ -1444,10 +1441,10 @@ class action:
         for key, value in all_kwargs.items():
             if key in self.func.__annotations__:
                 valid_value = True
-                try:
+                # The type is either not set or something tricky to verify, e.g. union
+                with contextlib.suppress(Exception):
                     valid_value = isinstance(value, (self.func.__annotations__[key], AnyVariable))
-                except Exception:
-                    pass  # The type is either not set or something tricky to verify, e.g. union
+
                 if not valid_value:
                     raise TypeError(
                         f'Argument: {key} was passed as a {type(value)}, but it should be '
@@ -1458,6 +1455,11 @@ class action:
         dynamic_kwargs: Dict[str, AnyVariable] = {}
         static_kwargs: Dict[str, Any] = {}
         for key, kwarg in all_kwargs.items():
+            if isinstance(kwarg, StateVariable):
+                raise ValueError(
+                    'StateVariable cannot be used as input to actions. '
+                    "StateVariables are internal variables for tracking DerivedVariable ephemeral client state shouldn't be used as action payloads."
+                )
             if isinstance(kwarg, AnyVariable):
                 dynamic_kwargs[key] = kwarg
             else: