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

dara/core/interactivity/server_variable.py

@@ -0,0 +1,325 @@
+import abc
+from collections import defaultdict
+from typing import Any, DefaultDict, Dict, Literal, Optional, Tuple, Union
+
+from pandas import DataFrame
+from pydantic import BaseModel, ConfigDict, Field, SerializerFunctionWrapHandler, model_serializer
+
+from dara.core.auth.definitions import USER
+from dara.core.base_definitions import CachedRegistryEntry, NonTabularDataError
+from dara.core.interactivity.filtering import FilterQuery, Pagination, apply_filters, coerce_to_filter_query
+from dara.core.internal.pandas_utils import DataResponse, append_index, build_data_response
+from dara.core.internal.utils import call_async
+from dara.core.internal.websocket import ServerMessagePayload, WebsocketManager
+
+from .any_variable import AnyVariable
+
+
+class ServerVariableMessage(ServerMessagePayload):
+    typ: Literal['ServerVariable'] = Field(alias='__type', default='ServerVariable')
+    uid: str
+    sequence_number: int
+
+
+class ServerBackend(BaseModel, abc.ABC):
+    scope: Literal['global', 'user']
+
+    @abc.abstractmethod
+    async def write(self, key: str, value: Any):
+        """
+        Persist a value
+        """
+
+    @abc.abstractmethod
+    async def read(self, key: str) -> Any:
+        """
+        Read a value
+        """
+
+    @abc.abstractmethod
+    async def read_filtered(
+        self, key: str, filters: Optional[Union[FilterQuery, dict]] = None, pagination: Optional[Pagination] = None
+    ) -> Tuple[Optional[DataFrame], int]:
+        """
+        Read a value
+        :param filters: filters to apply
+        :param pagination: pagination to apply
+        """
+
+    @abc.abstractmethod
+    async def get_sequence_number(self, key: str) -> int:
+        """
+        Get the sequence number for a given key
+        """
+
+
+class MemoryBackend(ServerBackend):
+    data: Dict[str, Any] = Field(default_factory=dict)
+    sequence_number: DefaultDict[str, int] = Field(default_factory=lambda: defaultdict(int))
+
+    def __init__(self, scope: Literal['user', 'global'] = 'user'):
+        super().__init__(scope=scope)
+
+    async def write(self, key: str, value: Any):
+        self.data[key] = value
+        self.sequence_number[key] += 1
+        return value
+
+    async def read(self, key: str) -> Any:
+        return self.data.get(key)
+
+    async def read_filtered(
+        self, key: str, filters: Optional[Union[FilterQuery, dict]] = None, pagination: Optional[Pagination] = None
+    ) -> Tuple[Optional[DataFrame], int]:
+        dataset = self.data.get(key)
+
+        # print user-friendly error message if the data is not a DataFrame
+        # most likely due to user passing a non-tabular server variable to e.g. a Table
+        if dataset is not None and not isinstance(dataset, DataFrame):
+            raise NonTabularDataError(
+                f'Failed to retrieve ServerVariable tabular data, expected pandas.DataFrame, got {type(dataset)}'
+            )
+
+        dataset = append_index(dataset)
+        return apply_filters(dataset, coerce_to_filter_query(filters), pagination)
+
+    async def get_sequence_number(self, key: str) -> int:
+        return self.sequence_number[key]
+
+
+class ServerVariable(AnyVariable):
+    """
+    A ServerVariable represents server-side data that is synchronized with the client.
+
+    Unlike Variables with BackendStore (which are client state persisted on server),
+    ServerVariable holds data that originates and is managed on the server, with
+    clients receiving reactive updates when the data changes.
+
+    ServerVariable can store any Python object, including non-serializable data like
+    database connections, ML models, or complex objects.
+
+    However, when used with components expecting tabular data (like Table), the data must be
+    serializable or a NonTabularDataError will be raised. The default backend implementation
+    expects the tabular data to be a pandas DataFrame. To support other data types, you can
+    implement a custom backend that translates the data into a filtered DataFrame in the
+    `read_filtered` method.
+
+    ```python
+    import pandas as pd
+    from dara.core import ServerVariable, action
+    from dara.core.interactivity.server_variable import ServerBackend
+    from sklearn.ensemble import RandomForestClassifier
+
+    # Basic usage with DataFrame
+    data = ServerVariable(pd.DataFrame({'a': [1, 2, 3]}))
+
+    # Non-serializable data (ML model)
+    model = ServerVariable(trained_sklearn_model, scope='global')
+
+    # Custom backend
+    class DatabaseBackend(ServerBackend):
+        # ... implements all the methods as DB operations
+
+    data = ServerVariable(backend=DatabaseBackend(...))
+
+    # User-specific data
+    user_prefs = ServerVariable(scope='user')
+
+    @action
+    async def on_click(ctx):
+        # write to the data for the user who initiated the action
+        await user_prefs.write('dark')
+    ```
+
+    :param default: Initial value for the variable (global scope only)
+    :param backend: Custom backend for data storage and retrieval
+    :param scope: 'global' (shared across all users) or 'user' (per-user data)
+    """
+
+    backend: ServerBackend = Field(exclude=True)
+    scope: Literal['user', 'global']
+
+    def __init__(
+        self,
+        default: Optional[Any] = None,
+        backend: Optional[ServerBackend] = None,
+        scope: Literal['user', 'global'] = 'global',
+        uid: Optional[str] = None,
+        **kwargs,
+    ) -> None:
+        from dara.core.internal.registries import server_variable_registry
+
+        if backend is None:
+            backend = MemoryBackend(scope=scope)
+
+        if default is not None:
+            assert scope == 'global', (
+                'ServerVariable can only be used with global scope, cannot initialize user-specific values'
+            )
+            call_async(backend.write, 'global', default)
+
+        super().__init__(uid=uid, backend=backend, scope=scope, **kwargs)
+
+        var_entry = ServerVariableRegistryEntry(uid=str(self.uid), backend=backend)
+        server_variable_registry.register(str(self.uid), var_entry)
+
+    @classmethod
+    async def get_value(cls, entry: 'ServerVariableRegistryEntry'):
+        """
+        Internal method to get the value of a server variable based in its registry entry.
+        """
+        key = cls.get_key(entry.backend.scope)
+        return await entry.backend.read(key)
+
+    @classmethod
+    async def write_value(cls, entry: 'ServerVariableRegistryEntry', value: Any):
+        """
+        Internal method to write the value of a server variable based in its registry entry.
+        """
+        key = cls.get_key(entry.backend.scope)
+        await entry.backend.write(key, value)
+        await cls._notify(entry.uid, key, entry.backend)
+
+    @classmethod
+    async def get_sequence_number(cls, entry: 'ServerVariableRegistryEntry'):
+        """
+        Internal method to get the sequence number of a server variable based in its registry entry.
+        """
+        key = cls.get_key(entry.backend.scope)
+        return await entry.backend.get_sequence_number(key)
+
+    @classmethod
+    async def get_tabular_data(
+        cls,
+        entry: 'ServerVariableRegistryEntry',
+        filters: Optional[FilterQuery] = None,
+        pagination: Optional[Pagination] = None,
+    ) -> DataResponse:
+        """
+        Internal method to get tabular data from the backend
+        """
+        key = cls.get_key(entry.backend.scope)
+        data, count = await entry.backend.read_filtered(key, filters, pagination)
+        if data is None:
+            return DataResponse(data=None, count=0, schema=None)
+        return build_data_response(data, count)
+
+    @classmethod
+    def get_key(cls, scope: Literal['global', 'user']):
+        """
+        Resolve the key for the given scope
+
+        :param scope: the scope to resolve the key for
+        """
+        if scope == 'global':
+            return 'global'
+
+        user = USER.get()
+
+        if user:
+            return user.identity_id
+
+        raise ValueError('User not found when trying to compute the key for a user-scoped store')
+
+    @property
+    def key(self):
+        """
+        Current key for the backend
+        """
+        return self.get_key(self.scope)
+
+    @classmethod
+    async def _notify(cls, uid: str, key: str, backend: ServerBackend):
+        """
+        Internal method to notify clients of a change in the value
+
+        :param uid: the uid of the variable
+        :param key: the key for the backend
+        :param backend: the backend instance
+        """
+        from dara.core.internal.registries import utils_registry
+
+        ws_mgr: WebsocketManager = utils_registry.get('WebsocketManager')
+
+        message = ServerVariableMessage(uid=uid, sequence_number=await backend.get_sequence_number(key))
+
+        if backend.scope == 'global':
+            return await ws_mgr.broadcast(message)
+
+        user = USER.get()
+        assert user is not None, 'User not found when trying to send notification'
+        user_id = user.identity_id
+        return await ws_mgr.send_message_to_user(user_id, message)
+
+    def update(self, value: Any):
+        """
+        Create an action to update the value of this Variable to a provided value.
+
+        ```python
+        import pandas as pd
+        from dara.core import ServerVariable
+        from dara.components import Button
+
+        data = ServerVariable(pd.DataFrame({'a': [1, 2, 3]}))
+
+        Button(
+            'Empty Data',
+            onclick=data.update(None),
+        )
+
+        ```
+        """
+        from dara.core.interactivity.actions import UpdateVariableImpl
+
+        return UpdateVariableImpl(variable=self, value=value)
+
+    def reset(self):
+        raise NotImplementedError('ServerVariable does not support reset')
+
+    async def read(self):
+        """
+        Read the current value from the backend.
+        Depending on the scope, the value will be global or user-specific.
+        """
+        return await self.backend.read(self.key)
+
+    async def write(self, value: Any):
+        """
+        Write a new value to the backend.
+        Depending on the scope, the value will be global or user-specific.
+
+        :param value: the new value to write
+        """
+        value = await self.backend.write(self.key, value)
+        await self._notify(self.uid, self.key, self.backend)
+        return value
+
+    async def read_filtered(
+        self, filters: Optional[Union[FilterQuery, dict]] = None, pagination: Optional[Pagination] = None
+    ):
+        """
+        Read a filtered value from the backend.
+        Depending on the scope, the value will be global or user-specific.
+
+        :param filters: the filters to apply
+        :param pagination: the pagination to apply
+        """
+        return await self.backend.read_filtered(self.key, filters, pagination)
+
+    @model_serializer(mode='wrap')
+    def ser_model(self, nxt: SerializerFunctionWrapHandler) -> dict:
+        parent_dict = nxt(self)
+        return {**parent_dict, '__typename': 'ServerVariable', 'uid': str(parent_dict['uid'])}
+
+
+class ServerVariableRegistryEntry(CachedRegistryEntry):
+    """
+    Registry entry for ServerVariable.
+    """
+
+    backend: ServerBackend
+    """
+    Backend instance
+    """
+
+    model_config = ConfigDict(extra='forbid', arbitrary_types_allowed=True)

dara/core/interactivity/state_variable.py

@@ -0,0 +1,69 @@
+"""
+Copyright 2023 Impulse Innovations Limited
+
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional
+
+from pydantic import SerializerFunctionWrapHandler, model_serializer
+from typing_extensions import Literal
+
+from dara.core.interactivity.client_variable import ClientVariable
+
+if TYPE_CHECKING:
+    from dara.core.interactivity.derived_variable import DerivedVariable
+
+
+class StateVariable(ClientVariable):
+    """
+    A StateVariable is an internal variable type used to track client-side state of other variables.
+    It is not meant to be created directly by users, but rather returned by properties like
+    DerivedVariable.is_loading, DerivedVariable.has_error, etc.
+
+    This variable tracks the state of a parent DerivedVariable and maps to specific properties
+    like loading state, error state, etc.
+    """
+
+    parent_variable: 'DerivedVariable'
+    property_name: Literal['loading', 'error', 'hasValue']
+
+    def __init__(
+        self,
+        parent_variable: 'DerivedVariable',
+        property_name: Literal['loading', 'error', 'hasValue'],
+        uid: Optional[str] = None,
+        **kwargs,
+    ):
+        """
+        Initialize a StateVariable.
+
+        :param parent_variable: The DerivedVariable this StateVariable tracks
+        :param property_name: The property name this StateVariable represents ('loading', 'error', etc.)
+        :param uid: Optional unique identifier; if not provided, one is generated
+        """
+        super().__init__(uid=uid, parent_variable=parent_variable, property_name=property_name, **kwargs)
+
+    @model_serializer(mode='wrap')
+    def ser_model(self, nxt: SerializerFunctionWrapHandler) -> dict:
+        parent_dict = nxt(self)
+        return {
+            **parent_dict,
+            '__typename': 'StateVariable',
+            'uid': str(parent_dict['uid']),
+            'parent_variable': self.parent_variable,
+            'property_name': self.property_name,
+        }

dara/core/interactivity/switch_variable.py

@@ -21,11 +21,11 @@ from typing import Any, Dict, Optional, Union
 
 from pydantic import SerializerFunctionWrapHandler, field_validator, model_serializer
 
+from dara.core.interactivity.client_variable import ClientVariable
 from dara.core.interactivity.condition import Condition
-from dara.core.interactivity.non_data_variable import NonDataVariable
 
 
-class SwitchVariable(NonDataVariable):
+class SwitchVariable(ClientVariable):
     """
     A SwitchVariable represents a conditional value that switches between
     different values based on a condition or variable value.
@@ -216,21 +216,21 @@ class SwitchVariable(NonDataVariable):
     Key Serialization:
         When using mappings with SwitchVariable, be aware that JavaScript object keys
         are always strings. The system automatically converts lookup keys to strings:
-        - Python: {True: 'admin', False: 'user'}
-        - JavaScript: {"true": "admin", "false": "user"}
+        - Python: `{True: 'admin', False: 'user'}`
+        - JavaScript: `{"true": "admin", "false": "user"}`
         - Boolean values are converted to lowercase strings ("true"/"false")
         - Other values use standard string conversion to match JavaScript's String() behavior
     """
 
-    value: Optional[Union[Condition, NonDataVariable, Any]] = None
+    value: Optional[Union[Condition, ClientVariable, Any]] = None
     # must be typed as any, otherwise pydantic is trying to instantiate the variables incorrectly
     value_map: Optional[Any] = None
     default: Optional[Any] = None
 
     def __init__(
         self,
-        value: Union[Condition, NonDataVariable, Any],
-        value_map: Dict[Any, Any] | NonDataVariable,
+        value: Union[Condition, ClientVariable, Any],
+        value_map: Dict[Any, Any] | ClientVariable,
         default: Optional[Any] = None,
         uid: Optional[str] = None,
     ):
@@ -253,28 +253,28 @@ class SwitchVariable(NonDataVariable):
     @classmethod
     def validate_value_map(cls, v):
         """
-        Validate that value_map is either a dict or a NonDataVariable.
+        Validate that value_map is either a dict or a ClientVariable.
 
         :param v: The value to validate
         :return: The validated value
-        :raises ValueError: If value_map is not a dict or NonDataVariable
+        :raises ValueError: If value_map is not a dict or ClientVariable
         """
         if v is None:
             return v
         if isinstance(v, dict):
             return v
-        if isinstance(v, NonDataVariable):
+        if isinstance(v, ClientVariable):
             return v
-        raise ValueError(f'value_map must be a dict or NonDataVariable, got {type(v)}')
+        raise ValueError(f'value_map must be a dict or ClientVariable, got {type(v)}')
 
     @classmethod
     def when(
         cls,
-        condition: Union[Condition, NonDataVariable, Any],
-        true_value: Union[Any, NonDataVariable],
-        false_value: Union[Any, NonDataVariable],
+        condition: Union[Condition, ClientVariable, Any],
+        true_value: Union[Any, ClientVariable],
+        false_value: Union[Any, ClientVariable],
         uid: Optional[str] = None,
-    ) -> 'SwitchVariable':
+    ) -> SwitchVariable:
         """
         Create a SwitchVariable for boolean conditions.
 
@@ -346,11 +346,11 @@ class SwitchVariable(NonDataVariable):
     @classmethod
     def match(
         cls,
-        value: Union[NonDataVariable, Any],
-        mapping: Union[Dict[Any, Any], NonDataVariable],
-        default: Optional[Union[Any, NonDataVariable]] = None,
+        value: Union[ClientVariable, Any],
+        mapping: Union[Dict[Any, Any], ClientVariable],
+        default: Optional[Union[Any, ClientVariable]] = None,
         uid: Optional[str] = None,
-    ) -> 'SwitchVariable':
+    ) -> SwitchVariable:
         """
         Create a SwitchVariable with a custom mapping.
 

dara/core/interactivity/tabular_variable.py

@@ -0,0 +1,94 @@
+"""
+Copyright 2023 Impulse Innovations Limited
+
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+import io
+import os
+from typing import Literal, Optional, TypedDict, Union, cast
+
+import pandas
+from fastapi import UploadFile
+
+from dara.core.base_definitions import UploadResolverDef
+from dara.core.internal.registry_lookup import RegistryLookup
+from dara.core.internal.utils import run_user_handler
+
+
+class FieldType(TypedDict):
+    name: Union[str, tuple[str, ...]]
+    type: Literal['integer', 'number', 'boolean', 'datetime', 'duration', 'any', 'str']
+
+
+class DataFrameSchema(TypedDict):
+    fields: list[FieldType]
+    primaryKey: list[str]
+
+
+async def upload(data: UploadFile, data_uid: Optional[str] = None, resolver_id: Optional[str] = None):
+    """
+    Handler for uploading data.
+
+    :param data: the file to upload
+    :param data_uid: optional uid of the data variable to upload to
+    :param resolver_id: optional id of the upload resolver to use, falls back to default handlers for csv/xlsx
+    """
+    from dara.core.interactivity.server_variable import ServerVariable
+    from dara.core.internal.registries import (
+        server_variable_registry,
+        upload_resolver_registry,
+        utils_registry,
+    )
+
+    registry_mgr: RegistryLookup = utils_registry.get('RegistryLookup')
+
+    if data.filename is None:
+        raise ValueError('Filename not provided')
+
+    variable_entry = None
+
+    _name, file_type = os.path.splitext(data.filename)
+
+    if data_uid is not None:
+        try:
+            variable_entry = await registry_mgr.get(server_variable_registry, data_uid)
+        except KeyError as e:
+            raise ValueError(f'Data Variable {data_uid} does not exist') from e
+
+    content = cast(bytes, await data.read())
+
+    resolver = None
+
+    # If Id is provided, lookup the definition from registry
+    if resolver_id is not None:
+        resolver_def: UploadResolverDef = await registry_mgr.get(upload_resolver_registry, resolver_id)
+        resolver = resolver_def.resolver
+
+    if resolver:
+        content = await run_user_handler(handler=resolver, args=(content, data.filename))
+    # If resolver is not provided, follow roughly the cl_dataset_parser logic
+    elif file_type == '.xlsx':
+        file_object_xlsx = io.BytesIO(content)
+        content = pandas.read_excel(file_object_xlsx, index_col=None)
+        content.columns = content.columns.str.replace('Unnamed: *', 'column_', regex=True)  # type: ignore
+    else:
+        # default to csv
+        file_object_csv = io.StringIO(content.decode('utf-8'))
+        content = pandas.read_csv(file_object_csv, index_col=0)
+        content.columns = content.columns.str.replace('Unnamed: *', 'column_', regex=True)  # type: ignore
+
+    # If a server variable is provided, update it with the new content
+    if variable_entry:
+        await ServerVariable.write_value(variable_entry, content)