dara-core 1.16.20a1__py3-none-any.whl → 1.16.22__py3-none-any.whl

dara/core/__init__.py

@@ -34,6 +34,7 @@ __version__ = version('dara-core')
 
 __all__ = [
     'action',
+    'ActionCtx',
     'ConfigurationBuilder',
     'DerivedVariable',
     'DerivedDataVariable',

dara/core/interactivity/__init__.py

@@ -20,6 +20,7 @@ from __future__ import annotations
 from pydantic import BaseModel
 
 from dara.core.interactivity.actions import (
+    ActionCtx,
     DownloadContent,
     DownloadContentImpl,
     DownloadVariable,
@@ -45,6 +46,7 @@ from dara.core.interactivity.url_variable import UrlVariable
 
 __all__ = [
     'action',
+    'ActionCtx',
     'AnyVariable',
     'AnyDataVariable',
     'DataVariable',

dara/core/interactivity/actions.py

@@ -52,6 +52,7 @@ from dara.core.base_definitions import (
     AnnotatedAction,
 )
 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.internal.download import generate_download_code
 from dara.core.internal.registry_lookup import RegistryLookup
@@ -1192,6 +1193,70 @@ class ActionCtx:
         """
         return await DownloadVariable(variable=variable, file_name=file_name, type=type).execute(self)
 
+    async def run_task(
+        self,
+        func: Callable,
+        args: Union[List[Any], None] = None,
+        kwargs: Union[Dict[str, Any], None] = None,
+        on_progress: Optional[Callable[[TaskProgressUpdate], Union[None, Awaitable[None]]]] = None,
+    ):
+        """
+        Run a calculation as a task in a separate process. Recommended for CPU intensive tasks.
+        Returns the result of the task function.
+
+        Note that the function must be defined in a separate module as configured in `task_module` field of the
+        configuration builder. This is because Dara spawns separate worker processes only designed to run
+        functions from that designated module.
+
+        ```python
+        from dara.core import ConfigurationBuilder, TaskProgressUpdate, action, ActionCtx, Variable
+        from dara.components import Text, Stack, Button
+        from .my_module import my_task_function
+
+        config = ConfigurationBuilder()
+        config.task_module = 'my_module'
+
+        status = Variable('Not started')
+
+        @action
+        async def my_task(ctx: ActionCtx):
+            async def on_progress(update: TaskProgressUpdate):
+                await ctx.update(status, f'Progress: {update.progress}% - {update.message}')
+
+            try:
+                result = await ctx.run_task(my_task_function, args=[1, 10], on_progress=on_progress)
+                await ctx.update(status, f'Result: {result}')
+            except Exception as e:
+                await ctx.update(status, f'Error: {e}')
+
+        def task_page():
+            return Stack(Text('Status display:'), Text(text=status), Button('Run', onclick=my_task()))
+
+        config.add_page(name='task', content=task_page())
+        ```
+
+        :param func: the function to run as a task
+        :param args: the arguments to pass to the function
+        :param kwargs: the keyword arguments to pass to the function
+        :param on_progress: a callback to receive progress updates
+        """
+        from dara.core.internal.registries import utils_registry
+        from dara.core.internal.tasks import Task, TaskManager
+
+        task_mgr: TaskManager = utils_registry.get('TaskManager')
+
+        task = Task(func=func, args=args, kwargs=kwargs, on_progress=on_progress)
+        pending_task = await task_mgr.run_task(task)
+
+        # Run until completion
+        await pending_task.event.wait()
+
+        # Raise exception if there was one
+        if pending_task.error:
+            raise pending_task.error
+
+        return pending_task.result
+
     async def execute_action(self, action: ActionImpl):
         """
         Execute a given action.

dara/core/interactivity/derived_variable.py

@@ -90,7 +90,7 @@ class DerivedVariable(NonDataVariable, Generic[VariableType]):
 
     def __init__(
         self,
-        func: Callable[..., VariableType],
+        func: Callable[..., VariableType] | Callable[..., Awaitable[VariableType]],
         variables: List[AnyVariable],
         cache: Optional[CacheArgType] = Cache.Type.GLOBAL,
         run_as_task: bool = False,

dara/core/interactivity/loop_variable.py

@@ -8,7 +8,7 @@ from .non_data_variable import NonDataVariable
 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()` method.
+    It should be constructed using a parent Variable's `.list_item` property.
     It should only be used in conjunction with the `For` component.
 
     By default, the entire value is used as the item and the index in the list is used as the unique key.

dara/core/internal/routing.py

@@ -501,7 +501,7 @@ def create_router(config: Configuration):
         async def _write(store_uid: str, value: Any):
             WS_CHANNEL.set(ws_channel)
             store_entry: BackendStoreEntry = await registry_mgr.get(backend_store_registry, store_uid)
-            result = store_entry.store.write(value)
+            result = store_entry.store.write(value, ignore_channel=ws_channel)
 
             # Backend implementation could return a coroutine
             if inspect.iscoroutine(result):

dara/core/internal/tasks.py

@@ -17,7 +17,7 @@ limitations under the License.
 
 import inspect
 import math
-from typing import Any, Callable, Dict, List, Optional, Union
+from typing import Any, Awaitable, Callable, Dict, List, Optional, Union, overload
 
 from anyio import (
     CancelScope,
@@ -70,6 +70,7 @@ class Task(BaseTask):
         notify_channels: Optional[List[str]] = None,
         cache_key: Optional[str] = None,
         task_id: Optional[str] = None,
+        on_progress: Optional[Callable[[TaskProgressUpdate], Union[None, Awaitable[None]]]] = None,
     ):
         """
         :param func: The function to execute within the process
@@ -87,6 +88,7 @@ class Task(BaseTask):
         self.notify_channels = notify_channels if notify_channels is not None else []
         self.cache_key = cache_key
         self.reg_entry = reg_entry
+        self.on_progress = on_progress
 
         super().__init__(task_id)
 
@@ -359,6 +361,14 @@ class TaskManager:
         self.ws_manager = ws_manager
         self.store = store
 
+    @overload
+    async def run_task(self, task: PendingTask, ws_channel: Optional[str] = None) -> Any:
+        ...
+
+    @overload
+    async def run_task(self, task: BaseTask, ws_channel: Optional[str] = None) -> PendingTask:
+        ...
+
     async def run_task(self, task: BaseTask, ws_channel: Optional[str] = None):
         """
         Run a task and store it in the tasks dict
@@ -504,6 +514,8 @@ class TaskManager:
                                     'message': message.message,
                                 }
                             )
+                            if isinstance(task, Task) and task.on_progress:
+                                await run_user_handler(task.on_progress, args=(message,))
                         elif isinstance(message, TaskResult):
                             # Resolve the pending task related to the result
                             if message.task_id in self.tasks:

dara/core/persistence.py

@@ -29,7 +29,6 @@ from pydantic import (
 
 from dara.core.auth.definitions import USER
 from dara.core.internal.utils import run_user_handler
-from dara.core.internal.websocket import WS_CHANNEL
 from dara.core.logging import dev_logger
 
 if TYPE_CHECKING:
@@ -318,7 +317,11 @@ class BackendStore(PersistenceStore):
         if not payload or len(payload) != 1:
             raise ValueError("Exactly one of 'value' or 'patches' must be provided")
 
-        return {'store_uid': self.uid, 'sequence_number': self.sequence_number.get(scope_key, 0), **payload}
+        return {
+            'store_uid': self.uid,
+            'sequence_number': self.sequence_number.get(scope_key, 0),
+            **payload,
+        }
 
     def _get_next_sequence_number(self, key: str) -> int:
         """
@@ -330,39 +333,40 @@ class BackendStore(PersistenceStore):
         self.sequence_number[key] = current + 1
         return self.sequence_number[key]
 
-    async def _notify_user(self, user_identifier: str, ignore_current_channel: bool = True, **payload):
+    async def _notify_user(self, user_identifier: str, ignore_channel: Optional[str] = None, **payload):
         """
         Notify a given user about updates to this store.
         :param user_identifier: user to notify
-        :param ignore_current_channel: if True, ignore the current websocket channel
+        :param ignore_channel: if specified, ignore the specified channel
         :param payload: either value=... or patches=...
         """
         return await self.ws_mgr.send_message_to_user(
             user_identifier,
             self._create_msg(user_identifier, **payload),
-            ignore_channel=WS_CHANNEL.get() if ignore_current_channel else None,
+            ignore_channel=ignore_channel,
         )
 
-    async def _notify_global(self, ignore_current_channel: bool = True, **payload):
+    async def _notify_global(self, ignore_channel: Optional[str] = None, **payload):
         """
         Notify all users about updates to this store.
-        :param ignore_current_channel: if True, ignore the current websocket channel
+        :param ignore_channel: if specified, ignore the specified channel
         :param payload: either value=... or patches=...
         """
         return await self.ws_mgr.broadcast(
             self._create_msg('global', **payload),
-            ignore_channel=WS_CHANNEL.get() if ignore_current_channel else None,
+            ignore_channel=ignore_channel,
         )
 
-    async def _notify_value(self, value: Any):
+    async def _notify_value(self, value: Any, ignore_channel: Optional[str] = None):
         """
         Notify all clients about the new value for this store.
         Broadcasts to all users if scope is global or sends to the current user if scope is user.
 
         :param value: value to notify about
+        :param ignore_channel: if passed, ignore the specified channel when broadcasting
         """
         if self.scope == 'global':
-            return await self._notify_global(value=value)
+            return await self._notify_global(value=value, ignore_channel=ignore_channel)
 
         # For user scope, we need to find channels for the user and notify them
         user = USER.get()
@@ -371,7 +375,7 @@ class BackendStore(PersistenceStore):
             return
 
         user_identifier = user.identity_id or user.identity_name
-        return await self._notify_user(user_identifier, value=value)
+        return await self._notify_user(user_identifier, value=value, ignore_channel=ignore_channel)
 
     async def _notify_patches(self, patches: List[Dict[str, Any]]):
         """
@@ -406,8 +410,8 @@ class BackendStore(PersistenceStore):
             async def _on_value(key: str, value: Any):
                 # here we explicitly DON'T ignore the current channel, in case we created this variable inside e.g. a py_component we want to notify its creator as well
                 if user := self._get_user(key):
-                    return await self._notify_user(user, ignore_current_channel=False, value=value)
-                return await self._notify_global(ignore_current_channel=False, value=value)
+                    return await self._notify_user(user, value=value)
+                return await self._notify_global(value=value)
 
             await self.backend.subscribe(_on_value)
 
@@ -466,7 +470,7 @@ class BackendStore(PersistenceStore):
 
         return updated_value
 
-    async def write(self, value: Any, notify=True):
+    async def write(self, value: Any, notify=True, ignore_channel: Optional[str] = None):
         """
         Persist a value to the store.
 
@@ -475,6 +479,7 @@ class BackendStore(PersistenceStore):
 
         :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
         """
         if self.readonly:
             raise ValueError('Cannot write to a read-only store')
@@ -486,7 +491,7 @@ class BackendStore(PersistenceStore):
         self._get_next_sequence_number(key)
 
         if notify:
-            await self._notify_value(value)
+            await self._notify_value(value, ignore_channel=ignore_channel)
 
         return res