dara-core 1.20.0__py3-none-any.whl → 1.20.1a1__py3-none-any.whl

dara/core/interactivity/filtering.py

@@ -20,11 +20,10 @@ from __future__ import annotations
 import re
 from datetime import datetime, timezone
 from enum import Enum
-from typing import Any, List, Optional, Tuple, Union, cast, overload
+from typing import Any, List, Optional, Tuple, Union
 
 import numpy
-from pandas import DataFrame, Series
-from pydantic import field_validator  # noqa: F401
+from pandas import DataFrame, Series  # pylint: disable=unused-import
 
 from dara.core.base_definitions import DaraBaseModel as BaseModel
 from dara.core.logging import dev_logger
@@ -32,13 +31,6 @@ from dara.core.logging import dev_logger
 COLUMN_PREFIX_REGEX = re.compile(r'__(?:col|index)__\d+__')
 
 
-def clean_column_name(col: str) -> str:
-    """
-    Cleans a column name by removing the index or col prefix
-    """
-    return re.sub(COLUMN_PREFIX_REGEX, '', col)
-
-
 class Pagination(BaseModel):
     """
     Model representing pagination to be applied to a dataset.
@@ -52,13 +44,6 @@ class Pagination(BaseModel):
     orderBy: Optional[str] = None
     index: Optional[str] = None
 
-    @field_validator('orderBy', mode='before')
-    @classmethod
-    def clean_order_by(cls, order_by):
-        if order_by is None:
-            return None
-        return clean_column_name(order_by)
-
 
 class QueryCombinator(str, Enum):
     AND = 'AND'
@@ -172,11 +157,11 @@ def infer_column_type(series: Series) -> ColumnType:
         return ColumnType.CATEGORICAL
 
 
-def _filter_to_series(data: DataFrame, column: str, operator: QueryOperator, value: Any) -> Optional[Series]:
+def _filter_to_series(data: DataFrame, column: str, operator: QueryOperator, value: Any) -> Optional['Series[bool]']:
     """
     Convert a single filter to a Series[bool] for filtering
     """
-    series = cast(Series, data[column])
+    series = data[column]
 
     # Contains is a special case, we always treat the column as a string
     if operator == QueryOperator.CONTAINS:
@@ -190,15 +175,19 @@ def _filter_to_series(data: DataFrame, column: str, operator: QueryOperator, val
             return series.isin(value)
         # Converts date passed from frontend to the right format to compare with pandas
         if col_type == ColumnType.DATETIME:
-            value = [parseISO(value[0]), parseISO(value[1])] if isinstance(value, List) else parseISO(value)
+            if isinstance(value, List):
+                value = [parseISO(value[0]), parseISO(value[1])]
+            else:
+                value = parseISO(value)
         elif col_type == ColumnType.CATEGORICAL:
             value = str(value)
-        elif isinstance(value, List):
-            lower_bound = float(value[0]) if '.' in str(value[0]) else int(value[0])
-            upper_bound = float(value[1]) if '.' in str(value[1]) else int(value[1])
-            value = [lower_bound, upper_bound]
         else:
-            value = float(value) if '.' in str(value) else int(value)
+            if isinstance(value, List):
+                lower_bound = float(value[0]) if '.' in str(value[0]) else int(value[0])
+                upper_bound = float(value[1]) if '.' in str(value[1]) else int(value[1])
+                value = [lower_bound, upper_bound]
+            else:
+                value = float(value) if '.' in str(value) else int(value)
 
         if operator == QueryOperator.GT:
             return series > value
@@ -219,14 +208,12 @@ def _filter_to_series(data: DataFrame, column: str, operator: QueryOperator, val
         return None
 
 
-def _resolve_filter_query(data: DataFrame, query: FilterQuery) -> Optional[Series]:
+def _resolve_filter_query(data: DataFrame, query: FilterQuery) -> 'Optional[Series[bool]]':
     """
     Resolve a FilterQuery to a Series[bool] for filtering. Strips the internal column index from the query.
     """
     if isinstance(query, ValueQuery):
-        return _filter_to_series(
-            data, re.sub(COLUMN_PREFIX_REGEX, repl='', string=query.column, count=1), query.operator, query.value
-        )
+        return _filter_to_series(data, re.sub(COLUMN_PREFIX_REGEX, '', query.column, 1), query.operator, query.value)
     elif isinstance(query, ClauseQuery):
         filters = None
 
@@ -235,9 +222,15 @@ def _resolve_filter_query(data: DataFrame, query: FilterQuery) -> Optional[Serie
 
             if resolved_clause is not None:
                 if query.combinator == QueryCombinator.AND:
-                    filters = resolved_clause if filters is None else filters & resolved_clause
+                    if filters is None:
+                        filters = resolved_clause
+                    else:
+                        filters = filters & resolved_clause
                 elif query.combinator == QueryCombinator.OR:
-                    filters = resolved_clause if filters is None else filters | resolved_clause
+                    if filters is None:
+                        filters = resolved_clause
+                    else:
+                        filters = filters | resolved_clause
                 else:
                     raise ValueError(f'Unknown combinator {query.combinator}')
 
@@ -246,18 +239,6 @@ def _resolve_filter_query(data: DataFrame, query: FilterQuery) -> Optional[Serie
         raise ValueError(f'Unknown query type {type(query)}')
 
 
-@overload
-def apply_filters(
-    data: DataFrame, filters: Optional[FilterQuery] = None, pagination: Optional[Pagination] = None
-) -> Tuple[DataFrame, int]: ...
-
-
-@overload
-def apply_filters(
-    data: None, filters: Optional[FilterQuery] = None, pagination: Optional[Pagination] = None
-) -> Tuple[None, int]: ...
-
-
 def apply_filters(
     data: Optional[DataFrame], filters: Optional[FilterQuery] = None, pagination: Optional[Pagination] = None
 ) -> Tuple[Optional[DataFrame], int]:
@@ -281,7 +262,7 @@ def apply_filters(
     if pagination is not None:
         # ON FETCHING SPECIFIC ROW
         if pagination.index is not None:
-            return cast(DataFrame, data[int(pagination.index) : int(pagination.index) + 1]), total_count
+            return data[int(pagination.index) : int(pagination.index) + 1], total_count
 
         # SORT
         if pagination.orderBy is not None:
@@ -297,7 +278,7 @@ def apply_filters(
             if col == 'index':
                 new_data = new_data.sort_index(ascending=ascending, inplace=False)
             else:
-                new_data = new_data.sort_values(by=col, ascending=ascending, inplace=False)  # type: ignore
+                new_data = new_data.sort_values(by=col, ascending=ascending, inplace=False)
 
         # PAGINATE
         start_index = pagination.offset if pagination.offset is not None else 0
@@ -305,4 +286,4 @@ def apply_filters(
 
         new_data = new_data.iloc[start_index:stop_index]
 
-    return cast(DataFrame, new_data), total_count
+    return new_data, total_count

dara/core/interactivity/loop_variable.py

@@ -2,10 +2,10 @@ from typing import List, Optional
 
 from pydantic import Field, SerializerFunctionWrapHandler, model_serializer
 
-from .client_variable import ClientVariable
+from .non_data_variable import NonDataVariable
 
 
-class LoopVariable(ClientVariable):
+class LoopVariable(NonDataVariable):
     """
     A LoopVariable is a type of variable that represents an item in a list.
     It should be constructed using a parent Variable's `.list_item` property.

dara/core/interactivity/non_data_variable.py

@@ -1,8 +1,71 @@
-from typing_extensions import TypeAlias
+"""
+Copyright 2023 Impulse Innovations Limited
 
-from .client_variable import *  # noqa: F403
 
-NonDataVariable: TypeAlias = ClientVariable  # noqa: F405
-"""
-Deprecated alias for ClientVariable
+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
+
+import abc
+from typing import Optional
+
+from dara.core.interactivity.any_variable import AnyVariable
+
+
+class NonDataVariable(AnyVariable, abc.ABC):
+    """
+    NonDataVariable represents any variable that is not specifically designed to hold datasets (i.e. Variable, DerivedVariable, UrlVariable)
+
+    :param uid: the unique identifier for this variable; if not provided a random one is generated
+    """
+
+    uid: str
+
+    def __init__(self, uid: Optional[str] = None, **kwargs) -> None:
+        super().__init__(uid=uid, **kwargs)
+
+    @property
+    def list_item(self):
+        """
+        Get a LoopVariable that represents the current item in the list.
+        Should only be used in conjunction with the `For` component.
+
+        Note that it is a type of a Variable so it can be used in places where a regular Variable is expected.
+
+        By default, the entire list item is used as the item.
+
+        `LoopVariable` supports nested property access using `get` or index access i.e. `[]`.
+        You can mix and match those two methods to access nested properties as they are equivalent.
+
+        ```python
+        my_list = Variable(['foo', 'bar', 'baz'])
+
+        # Represents the entire item in the list
+        my_list.list_item
+
+        my_list_of_objects = Variable([
+            {'id': 1, 'name': 'John', 'data': {'city': 'London', 'country': 'UK'}},
+            {'id': 2, 'name': 'Jane', 'data': {'city': 'Paris', 'country': 'France'}},
+        ])
+
+        # Represents the item 'name' property
+        my_list_of_objects.list_item['name']
+
+        # Represents the item 'data.country' property
+        my_list_of_objects.list_item.get('data')['country']
+        """
+
+        from .loop_variable import LoopVariable
+
+        return LoopVariable()

dara/core/interactivity/plain_variable.py

@@ -17,10 +17,9 @@ limitations under the License.
 
 from __future__ import annotations
 
-import warnings
 from contextlib import contextmanager
 from contextvars import ContextVar
-from typing import Any, Callable, Dict, Generic, List, Optional, TypeVar, Union
+from typing import Any, Callable, Generic, List, Optional, TypeVar
 
 from fastapi.encoders import jsonable_encoder
 from pydantic import (
@@ -31,25 +30,26 @@ from pydantic import (
     model_serializer,
 )
 
-from dara.core.interactivity.client_variable import ClientVariable
+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.internal.utils import call_async
 from dara.core.logging import dev_logger
-from dara.core.persistence import BackendStore, BrowserStore, PersistenceStore
+from dara.core.persistence import PersistenceStore
 
 VARIABLE_INIT_OVERRIDE = ContextVar[Optional[Callable[[dict], dict]]]('VARIABLE_INIT_OVERRIDE', default=None)
 
 VariableType = TypeVar('VariableType')
 PersistenceStoreType_co = TypeVar('PersistenceStoreType_co', bound=PersistenceStore, covariant=True)
 
-
 # TODO: once Python supports a default value for a generic type properly we can make PersistenceStoreType a second generic param
-class Variable(ClientVariable, Generic[VariableType]):
+class Variable(NonDataVariable, Generic[VariableType]):
     """
     A Variable represents a dynamic value in the system that can be read and written to by components and actions
     """
 
     default: Optional[VariableType] = None
+    persist_value: bool = False
     store: Optional[PersistenceStore] = None
     uid: str
     nested: List[str] = Field(default_factory=list)
@@ -62,7 +62,6 @@ class Variable(ClientVariable, Generic[VariableType]):
         uid: Optional[str] = None,
         store: Optional[PersistenceStoreType_co] = None,
         nested: Optional[List[str]] = None,
-        **kwargs,
     ):
         """
         A Variable represents a dynamic value in the system that can be read and written to by components and actions
@@ -74,32 +73,18 @@ class Variable(ClientVariable, Generic[VariableType]):
         """
         if nested is None:
             nested = []
-        kwargs = {
-            'default': default,
-            'uid': uid,
-            'store': store,
-            'nested': nested,
-            **kwargs,
-        }
+        kwargs = {'default': default, 'persist_value': persist_value, 'uid': uid, 'store': store, 'nested': nested}
 
         # If an override is active, run the kwargs through it
         override = VARIABLE_INIT_OVERRIDE.get()
         if override is not None:
             kwargs = override(kwargs)
 
-        if kwargs.get('store') is not None and persist_value:
+        if kwargs.get('store') is not None and kwargs.get('persist_value'):
             # TODO: this is temporary, persist_value will eventually become a type of store
             raise ValueError('Cannot provide a Variable with both a store and persist_value set to True')
 
-        if persist_value:
-            warnings.warn(
-                '`persist_value` is deprecated and will be removed in a future version. Use `store=dara.core.persistence.BrowserStore(...)` instead.',
-                DeprecationWarning,
-                stacklevel=2,
-            )
-            kwargs['store'] = BrowserStore()
-
-        super().__init__(**kwargs)  # type: ignore
+        super().__init__(**kwargs)   # type: ignore
 
         if self.store:
             call_async(self.store.init, self)
@@ -130,7 +115,7 @@ class Variable(ClientVariable, Generic[VariableType]):
         Override the init function of all Variables created within the context of this function.
 
         ```python
-        with Variable.init_override(lambda kwargs: {**kwargs, 'store': ...}):
+        with Variable.init_override(lambda kwargs: {**kwargs, 'persist_value': True}):
             var = Variable()
         ```
 
@@ -267,71 +252,12 @@ class Variable(ClientVariable, Generic[VariableType]):
 
         :param default: the initial value for the variable, defaults to None
         """
-        return cls(default=other)  # type: ignore
-
-    async def write(self, value: Any, notify=True, ignore_channel: Optional[str] = None):
-        """
-        Persist a value to the variable's BackendStore.
-        Raises an error if the variable does not have a BackendStore attached.
-
-        If scope='user', the value is written for the current user so the method can only
-        be used in authenticated contexts.
-
-        :param value: value to write
-        :param notify: whether to broadcast the new value to clients
-        :param ignore_channel: if passed, ignore the specified websocket channel when broadcasting
-        """
-        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):
-        """
-        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.
-
-        If scope='user', the patches are applied for the current user so the method can only
-        be used in authenticated contexts.
-
-        :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
-        """
-        assert isinstance(self.store, BackendStore), 'This method can only be used with a BackendStore'
-        return await self.store.write_partial(data, notify=notify)
-
-    async def read(self):
-        """
-        Read a value from the variable's BackendStore.
-        Raises an error if the variable does not have a BackendStore attached.
-
-        If scope='user', the value is read for the current user so the method can only
-        be used in authenticated contexts.
-        """
-        assert isinstance(self.store, BackendStore), 'This method can only be used with a BackendStore'
-        return await self.store.read()
-
-    async def delete(self, notify=True):
-        """
-        Delete the persisted value from the variable's BackendStore.
-        Raises an error if the variable does not have a BackendStore attached.
-
-        If scope='user', the value is deleted for the current user so the method can only
-        be used in authenticated contexts.
-
-        :param notify: whether to broadcast that the value was deleted to clients
-        """
-        assert isinstance(self.store, BackendStore), 'This method can only be used with a BackendStore'
-        return await self.store.delete(notify=notify)
-
-    async def get_all(self) -> Dict[str, Any]:
-        """
-        Get all the values from the variable's BackendStore as a dictionary of key-value pairs.
-        Raises an error if the variable does not have a BackendStore attached.
+        if isinstance(other, DerivedDataVariable):
+            raise ValueError(
+                'Cannot create a Variable from a DerivedDataVariable, only standard DerivedVariables are allowed'
+            )
 
-        For global scope, the dictionary contains a single key-value pair `{'global': value}`.
-        For user scope, the dictionary contains a key-value pair for each user `{'user1': value1, 'user2': value2, ...}`.
-        """
-        assert isinstance(self.store, BackendStore), 'This method can only be used with a BackendStore'
-        return await self.store.get_all()
+        return cls(default=other)   # type: ignore
 
     @model_serializer(mode='wrap')
     def ser_model(self, nxt: SerializerFunctionWrapHandler) -> dict:

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(ClientVariable):
+class SwitchVariable(NonDataVariable):
     """
     A SwitchVariable represents a conditional value that switches between
     different values based on a condition or variable value.
@@ -216,21 +216,21 @@ class SwitchVariable(ClientVariable):
     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, ClientVariable, Any]] = None
+    value: Optional[Union[Condition, NonDataVariable, 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, ClientVariable, Any],
-        value_map: Dict[Any, Any] | ClientVariable,
+        value: Union[Condition, NonDataVariable, Any],
+        value_map: Dict[Any, Any] | NonDataVariable,
         default: Optional[Any] = None,
         uid: Optional[str] = None,
     ):
@@ -253,28 +253,28 @@ class SwitchVariable(ClientVariable):
     @classmethod
     def validate_value_map(cls, v):
         """
-        Validate that value_map is either a dict or a ClientVariable.
+        Validate that value_map is either a dict or a NonDataVariable.
 
         :param v: The value to validate
         :return: The validated value
-        :raises ValueError: If value_map is not a dict or ClientVariable
+        :raises ValueError: If value_map is not a dict or NonDataVariable
         """
         if v is None:
             return v
         if isinstance(v, dict):
             return v
-        if isinstance(v, ClientVariable):
+        if isinstance(v, NonDataVariable):
             return v
-        raise ValueError(f'value_map must be a dict or ClientVariable, got {type(v)}')
+        raise ValueError(f'value_map must be a dict or NonDataVariable, got {type(v)}')
 
     @classmethod
     def when(
         cls,
-        condition: Union[Condition, ClientVariable, Any],
-        true_value: Union[Any, ClientVariable],
-        false_value: Union[Any, ClientVariable],
+        condition: Union[Condition, NonDataVariable, Any],
+        true_value: Union[Any, NonDataVariable],
+        false_value: Union[Any, NonDataVariable],
         uid: Optional[str] = None,
-    ) -> SwitchVariable:
+    ) -> 'SwitchVariable':
         """
         Create a SwitchVariable for boolean conditions.
 
@@ -346,11 +346,11 @@ class SwitchVariable(ClientVariable):
     @classmethod
     def match(
         cls,
-        value: Union[ClientVariable, Any],
-        mapping: Union[Dict[Any, Any], ClientVariable],
-        default: Optional[Union[Any, ClientVariable]] = None,
+        value: Union[NonDataVariable, Any],
+        mapping: Union[Dict[Any, Any], NonDataVariable],
+        default: Optional[Union[Any, NonDataVariable]] = None,
         uid: Optional[str] = None,
-    ) -> SwitchVariable:
+    ) -> 'SwitchVariable':
         """
         Create a SwitchVariable with a custom mapping.
 

dara/core/interactivity/url_variable.py

@@ -17,21 +17,16 @@ limitations under the License.
 
 from __future__ import annotations
 
-from typing import Optional, TypeVar
+from typing import Any, Generic, Optional, TypeVar
 
-from pydantic import ConfigDict
-from typing_extensions import deprecated
+from pydantic import ConfigDict, SerializerFunctionWrapHandler, model_serializer
 
-from dara.core.interactivity.plain_variable import Variable
-from dara.core.persistence import QueryParamStore
+from dara.core.interactivity.non_data_variable import NonDataVariable
 
 VariableType = TypeVar('VariableType')
 
 
-@deprecated(
-    'UrlVariable is deprecated and will be removed in a future version. Use dara.core.interactivity.plain_variable.Variable with dara.core.persistence.QueryParamStore instead'
-)
-class UrlVariable(Variable[VariableType]):
+class UrlVariable(NonDataVariable, Generic[VariableType]):
     """
     A UrlVariable is very similar to a normal Variable however rather than it's state being stored in the memory of
     the client it's value is stored in the url of page as a query parameter. This is very useful for parameterizing
@@ -53,4 +48,89 @@ class UrlVariable(Variable[VariableType]):
         :param default: the initial value for the variable, defaults to None
         :param uid: the unique identifier for this variable; if not provided a random one is generated
         """
-        super().__init__(default=default, uid=uid, store=QueryParamStore(query=query), query=query)
+        super().__init__(query=query, default=default, uid=uid)
+
+    def sync(self):
+        """
+        Create an action to synchronise the value of this UrlVariable with input value sent from the component.
+
+        ```python
+
+        from dara.core import UrlVariable
+        from dara.components import Select
+
+        var = UrlVariable('first', query='num')
+        another_var = UrlVariable('second', query='num_two')
+
+        Select(
+            value=var,
+            items=['first', 'second', 'third'],
+            onchange=another_var.sync(),
+        )
+
+        ```
+        """
+        from dara.core.interactivity.actions import (
+            UpdateVariableImpl,
+            assert_no_context,
+        )
+
+        assert_no_context('ctx.update')
+        return UpdateVariableImpl(variable=self, value=UpdateVariableImpl.INPUT)
+
+    def toggle(self):
+        """
+        Create an action to toggle the value of this UrlVariable. Note this only works for boolean variables.
+
+        ```python
+
+        from dara.core import UrlVariable
+        from dara.components import Button
+
+        var = UrlVariable(True, query='show')
+
+        Button(
+            'Toggle',
+            onclick=var.toggle(),
+        )
+
+        ```
+        """
+        from dara.core.interactivity.actions import (
+            UpdateVariableImpl,
+            assert_no_context,
+        )
+
+        assert_no_context('ctx.update')
+        return UpdateVariableImpl(variable=self, value=UpdateVariableImpl.TOGGLE)
+
+    def update(self, value: Any):
+        """
+        Create an action to update the value of this UrlVariable to a provided value.
+
+        ```python
+
+        from dara.core import UrlVariable
+        from dara.components import Button
+
+        show = UrlVariable(True, query='show')
+
+        Button(
+            'Hide',
+            onclick=show.update(False),
+        )
+
+        ```
+        """
+        from dara.core.interactivity.actions import (
+            UpdateVariableImpl,
+            assert_no_context,
+        )
+
+        assert_no_context('ctx.update')
+        return UpdateVariableImpl(variable=self, value=value)
+
+    @model_serializer(mode='wrap')
+    def ser_model(self, nxt: SerializerFunctionWrapHandler) -> dict:
+        parent_dict = nxt(self)
+        return {**parent_dict, '__typename': 'UrlVariable', 'uid': str(parent_dict['uid'])}

dara/core/internal/cache_store/base_impl.py

@@ -19,13 +19,12 @@ class CacheStoreImpl(abc.ABC, Generic[PolicyT]):
         """
 
     @abc.abstractmethod
-    async def get(self, key: str, unpin: bool = False, raise_for_missing: bool = False) -> Any:
+    async def get(self, key: str, unpin: bool = False) -> Any:
         """
         Retrieve an entry from the cache.
 
         :param key: The key of the entry to retrieve.
         :param unpin: If true, the entry will be unpinned if it is pinned.
-        :param raise_for_missing: If true, an exception will be raised if the entry is not found
         """
 
     @abc.abstractmethod