durabletask 0.4.0__tar.gz → 0.5.0__tar.gz

durabletask-0.5.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: durabletask
+Version: 0.5.0
+Summary: A Durable Task Client SDK for Python
+License:     MIT License
+        
+            Copyright (c) Microsoft Corporation.
+        
+            Permission is hereby granted, free of charge, to any person obtaining a copy
+            of this software and associated documentation files (the "Software"), to deal
+            in the Software without restriction, including without limitation the rights
+            to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+            copies of the Software, and to permit persons to whom the Software is
+            furnished to do so, subject to the following conditions:
+        
+            The above copyright notice and this permission notice shall be included in all
+            copies or substantial portions of the Software.
+        
+            THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+            IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+            FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+            AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+            LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+            OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+            SOFTWARE
+        
+Project-URL: repository, https://github.com/microsoft/durabletask-python
+Project-URL: changelog, https://github.com/microsoft/durabletask-python/blob/main/CHANGELOG.md
+Keywords: durable,task,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: grpcio
+Requires-Dist: protobuf
+Requires-Dist: asyncio
+Requires-Dist: packaging
+Dynamic: license-file
+
+# Durable Task SDK for Python
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Build Validation](https://github.com/microsoft/durabletask-python/actions/workflows/pr-validation.yml/badge.svg)](https://github.com/microsoft/durabletask-python/actions/workflows/pr-validation.yml)
+[![PyPI version](https://badge.fury.io/py/durabletask.svg)](https://badge.fury.io/py/durabletask)
+
+This repo contains a Python SDK for use with the [Azure Durable Task Scheduler](https://github.com/Azure/Durable-Task-Scheduler). With this SDK, you can define, schedule, and manage durable orchestrations using ordinary Python code.
+
+> Note that this SDK is **not** currently compatible with [Azure Durable Functions](https://learn.microsoft.com/azure/azure-functions/durable/durable-functions-overview). If you are looking for a Python SDK for Azure Durable Functions, please see [this repo](https://github.com/Azure/azure-functions-durable-python).
+
+# References
+- [Supported Patterns](./docs/supported-patterns.md)
+- [Available Features](./docs/features.md)
+- [Getting Started](./docs/getting-started.md)
+- [Development Guide](./docs/development.md) 
+- [Contributing Guide](./CONTRIBUTING.md)
+
+## Trademarks
+This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft 
+trademarks or logos is subject to and must follow 
+[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
+Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
+Any use of third-party trademarks or logos are subject to those third-party's policies.

durabletask-0.5.0/README.md

@@ -0,0 +1,23 @@
+# Durable Task SDK for Python
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Build Validation](https://github.com/microsoft/durabletask-python/actions/workflows/pr-validation.yml/badge.svg)](https://github.com/microsoft/durabletask-python/actions/workflows/pr-validation.yml)
+[![PyPI version](https://badge.fury.io/py/durabletask.svg)](https://badge.fury.io/py/durabletask)
+
+This repo contains a Python SDK for use with the [Azure Durable Task Scheduler](https://github.com/Azure/Durable-Task-Scheduler). With this SDK, you can define, schedule, and manage durable orchestrations using ordinary Python code.
+
+> Note that this SDK is **not** currently compatible with [Azure Durable Functions](https://learn.microsoft.com/azure/azure-functions/durable/durable-functions-overview). If you are looking for a Python SDK for Azure Durable Functions, please see [this repo](https://github.com/Azure/azure-functions-durable-python).
+
+# References
+- [Supported Patterns](./docs/supported-patterns.md)
+- [Available Features](./docs/features.md)
+- [Getting Started](./docs/getting-started.md)
+- [Development Guide](./docs/development.md) 
+- [Contributing Guide](./CONTRIBUTING.md)
+
+## Trademarks
+This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft 
+trademarks or logos is subject to and must follow 
+[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
+Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
+Any use of third-party trademarks or logos are subject to those third-party's policies.

{durabletask-0.4.0 → durabletask-0.5.0}/durabletask/client.py

@@ -4,13 +4,14 @@
 import logging
 import uuid
 from dataclasses import dataclass
-from datetime import datetime
+from datetime import datetime, timezone
 from enum import Enum
 from typing import Any, Optional, Sequence, TypeVar, Union
 
 import grpc
 from google.protobuf import wrappers_pb2
 
+from durabletask.entities import EntityInstanceId
 import durabletask.internal.helpers as helpers
 import durabletask.internal.orchestrator_service_pb2 as pb
 import durabletask.internal.orchestrator_service_pb2_grpc as stubs
@@ -227,3 +228,16 @@ class TaskHubGrpcClient:
         req = pb.PurgeInstancesRequest(instanceId=instance_id, recursive=recursive)
         self._logger.info(f"Purging instance '{instance_id}'.")
         self._stub.PurgeInstances(req)
+
+    def signal_entity(self, entity_instance_id: EntityInstanceId, operation_name: str, input: Optional[Any] = None):
+        req = pb.SignalEntityRequest(
+            instanceId=str(entity_instance_id),
+            name=operation_name,
+            input=wrappers_pb2.StringValue(value=shared.to_json(input)) if input else None,
+            requestId=str(uuid.uuid4()),
+            scheduledTime=None,
+            parentTraceContext=None,
+            requestTime=helpers.new_timestamp(datetime.now(timezone.utc))
+        )
+        self._logger.info(f"Signaling entity '{entity_instance_id}' operation '{operation_name}'.")
+        self._stub.SignalEntity(req, None)  # TODO: Cancellation timeout?

durabletask-0.5.0/durabletask/entities/__init__.py

@@ -0,0 +1,13 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+
+"""Durable Task SDK for Python entities component"""
+
+from durabletask.entities.entity_instance_id import EntityInstanceId
+from durabletask.entities.durable_entity import DurableEntity
+from durabletask.entities.entity_lock import EntityLock
+from durabletask.entities.entity_context import EntityContext
+
+__all__ = ["EntityInstanceId", "DurableEntity", "EntityLock", "EntityContext"]
+
+PACKAGE_NAME = "durabletask.entities"

durabletask-0.5.0/durabletask/entities/durable_entity.py

@@ -0,0 +1,93 @@
+from typing import Any, Optional, Type, TypeVar, Union, overload
+
+from durabletask.entities.entity_context import EntityContext
+from durabletask.entities.entity_instance_id import EntityInstanceId
+
+TState = TypeVar("TState")
+
+
+class DurableEntity:
+    def _initialize_entity_context(self, context: EntityContext):
+        self.entity_context = context
+
+    @overload
+    def get_state(self, intended_type: Type[TState], default: TState) -> TState:
+        ...
+
+    @overload
+    def get_state(self, intended_type: Type[TState]) -> Optional[TState]:
+        ...
+
+    @overload
+    def get_state(self, intended_type: None = None, default: Any = None) -> Any:
+        ...
+
+    def get_state(self, intended_type: Optional[Type[TState]] = None, default: Optional[TState] = None) -> Union[None, TState, Any]:
+        """Get the current state of the entity, optionally converting it to a specified type.
+
+        Parameters
+        ----------
+        intended_type : Type[TState] | None, optional
+            The type to which the state should be converted. If None, the state is returned as-is.
+        default : TState, optional
+            The default value to return if the state is not found or cannot be converted.
+
+        Returns
+        -------
+        TState | Any
+            The current state of the entity, optionally converted to the specified type.
+        """
+        return self.entity_context.get_state(intended_type, default)
+
+    def set_state(self, state: Any):
+        """Set the state of the entity to a new value.
+
+        Parameters
+        ----------
+        new_state : Any
+            The new state to set for the entity.
+        """
+        self.entity_context.set_state(state)
+
+    def signal_entity(self, entity_instance_id: EntityInstanceId, operation: str, input: Optional[Any] = None) -> None:
+        """Signal another entity to perform an operation.
+
+        Parameters
+        ----------
+        entity_instance_id : EntityInstanceId
+            The ID of the entity instance to signal.
+        operation : str
+            The operation to perform on the entity.
+        input : Any, optional
+            The input to provide to the entity for the operation.
+        """
+        self.entity_context.signal_entity(entity_instance_id, operation, input)
+
+    def schedule_new_orchestration(self, orchestration_name: str, input: Optional[Any] = None, instance_id: Optional[str] = None) -> str:
+        """Schedule a new orchestration instance.
+
+        Parameters
+        ----------
+        orchestration_name : str
+            The name of the orchestration to schedule.
+        input : Any, optional
+            The input to provide to the new orchestration.
+        instance_id : str, optional
+            The instance ID to assign to the new orchestration. If None, a new ID will be generated.
+
+        Returns
+        -------
+        str
+            The instance ID of the scheduled orchestration.
+        """
+        return self.entity_context.schedule_new_orchestration(orchestration_name, input, instance_id=instance_id)
+
+    def delete(self, input: Any = None) -> None:
+        """Delete the entity instance.
+
+        Parameters
+        ----------
+        input : Any, optional
+            Unused: The input for the entity "delete" operation.
+        """
+        self.set_state(None)

durabletask-0.5.0/durabletask/entities/entity_context.py

@@ -0,0 +1,154 @@
+
+from typing import Any, Optional, Type, TypeVar, Union, overload
+import uuid
+from durabletask.entities.entity_instance_id import EntityInstanceId
+from durabletask.internal import helpers, shared
+from durabletask.internal.entity_state_shim import StateShim
+import durabletask.internal.orchestrator_service_pb2 as pb
+
+TState = TypeVar("TState")
+
+
+class EntityContext:
+    def __init__(self, orchestration_id: str, operation: str, state: StateShim, entity_id: EntityInstanceId):
+        self._orchestration_id = orchestration_id
+        self._operation = operation
+        self._state = state
+        self._entity_id = entity_id
+
+    @property
+    def orchestration_id(self) -> str:
+        """Get the ID of the orchestration instance that scheduled this entity.
+
+        Returns
+        -------
+        str
+            The ID of the current orchestration instance.
+        """
+        return self._orchestration_id
+
+    @property
+    def operation(self) -> str:
+        """Get the operation associated with this entity invocation.
+
+        The operation is a string that identifies the specific action being
+        performed on the entity. It can be used to distinguish between
+        multiple operations that are part of the same entity invocation.
+
+        Returns
+        -------
+        str
+            The operation associated with this entity invocation.
+        """
+        return self._operation
+
+    @overload
+    def get_state(self, intended_type: Type[TState], default: TState) -> TState:
+        ...
+
+    @overload
+    def get_state(self, intended_type: Type[TState]) -> Optional[TState]:
+        ...
+
+    @overload
+    def get_state(self, intended_type: None = None, default: Any = None) -> Any:
+        ...
+
+    def get_state(self, intended_type: Optional[Type[TState]] = None, default: Optional[TState] = None) -> Union[None, TState, Any]:
+        """Get the current state of the entity, optionally converting it to a specified type.
+
+        Parameters
+        ----------
+        intended_type : Type[TState] | None, optional
+            The type to which the state should be converted. If None, the state is returned as-is.
+        default : TState, optional
+            The default value to return if the state is not found or cannot be converted.
+
+        Returns
+        -------
+        TState | Any
+            The current state of the entity, optionally converted to the specified type.
+        """
+        return self._state.get_state(intended_type, default)
+
+    def set_state(self, new_state: Any):
+        """Set the state of the entity to a new value.
+
+        Parameters
+        ----------
+        new_state : Any
+            The new state to set for the entity.
+        """
+        self._state.set_state(new_state)
+
+    def signal_entity(self, entity_instance_id: EntityInstanceId, operation: str, input: Optional[Any] = None) -> None:
+        """Signal another entity to perform an operation.
+
+        Parameters
+        ----------
+        entity_instance_id : EntityInstanceId
+            The ID of the entity instance to signal.
+        operation : str
+            The operation to perform on the entity.
+        input : Any, optional
+            The input to provide to the entity for the operation.
+        """
+        encoded_input = shared.to_json(input) if input is not None else None
+        self._state.add_operation_action(
+            pb.OperationAction(
+                sendSignal=pb.SendSignalAction(
+                    instanceId=str(entity_instance_id),
+                    name=operation,
+                    input=helpers.get_string_value(encoded_input),
+                    scheduledTime=None,
+                    requestTime=None,
+                    parentTraceContext=None,
+                )
+            )
+        )
+
+    def schedule_new_orchestration(self, orchestration_name: str, input: Optional[Any] = None, instance_id: Optional[str] = None) -> str:
+        """Schedule a new orchestration instance.
+
+        Parameters
+        ----------
+        orchestration_name : str
+            The name of the orchestration to schedule.
+        input : Any, optional
+            The input to provide to the new orchestration.
+        instance_id : str, optional
+            The instance ID to assign to the new orchestration. If None, a new ID will be generated.
+
+        Returns
+        -------
+        str
+            The instance ID of the scheduled orchestration.
+        """
+        encoded_input = shared.to_json(input) if input is not None else None
+        if not instance_id:
+            instance_id = uuid.uuid4().hex
+        self._state.add_operation_action(
+            pb.OperationAction(
+                startNewOrchestration=pb.StartNewOrchestrationAction(
+                    instanceId=instance_id,
+                    name=orchestration_name,
+                    input=helpers.get_string_value(encoded_input),
+                    version=None,
+                    scheduledTime=None,
+                    requestTime=None,
+                    parentTraceContext=None
+                )
+            )
+        )
+        return instance_id
+
+    @property
+    def entity_id(self) -> EntityInstanceId:
+        """Get the ID of the entity instance.
+
+        Returns
+        -------
+        str
+            The ID of the current entity instance.
+        """
+        return self._entity_id

durabletask-0.5.0/durabletask/entities/entity_instance_id.py

@@ -0,0 +1,40 @@
+from typing import Optional
+
+
+class EntityInstanceId:
+    def __init__(self, entity: str, key: str):
+        self.entity = entity
+        self.key = key
+
+    def __str__(self) -> str:
+        return f"@{self.entity}@{self.key}"
+
+    def __eq__(self, other):
+        if not isinstance(other, EntityInstanceId):
+            return False
+        return self.entity == other.entity and self.key == other.key
+
+    def __lt__(self, other):
+        if not isinstance(other, EntityInstanceId):
+            return self < other
+        return str(self) < str(other)
+
+    @staticmethod
+    def parse(entity_id: str) -> Optional["EntityInstanceId"]:
+        """Parse a string representation of an entity ID into an EntityInstanceId object.
+
+        Parameters
+        ----------
+        entity_id : str
+            The string representation of the entity ID, in the format '@entity@key'.
+
+        Returns
+        -------
+        Optional[EntityInstanceId]
+            The parsed EntityInstanceId object, or None if the input is None.
+        """
+        try:
+            _, entity, key = entity_id.split("@", 2)
+            return EntityInstanceId(entity=entity, key=key)
+        except ValueError as ex:
+            raise ValueError("Invalid entity ID format", ex)

durabletask-0.5.0/durabletask/entities/entity_lock.py

@@ -0,0 +1,17 @@
+from typing import TYPE_CHECKING
+
+
+if TYPE_CHECKING:
+    from durabletask.task import OrchestrationContext
+
+
+class EntityLock:
+    # Note: This should
+    def __init__(self, context: 'OrchestrationContext'):
+        self._context = context
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self._context._exit_critical_section()

durabletask-0.5.0/durabletask/internal/entity_state_shim.py

@@ -0,0 +1,66 @@
+from typing import Any, TypeVar, Union
+from typing import Optional, Type, overload
+
+import durabletask.internal.orchestrator_service_pb2 as pb
+
+TState = TypeVar("TState")
+
+
+class StateShim:
+    def __init__(self, start_state):
+        self._current_state: Any = start_state
+        self._checkpoint_state: Any = start_state
+        self._operation_actions: list[pb.OperationAction] = []
+        self._actions_checkpoint_state: int = 0
+
+    @overload
+    def get_state(self, intended_type: Type[TState], default: TState) -> TState:
+        ...
+
+    @overload
+    def get_state(self, intended_type: Type[TState]) -> Optional[TState]:
+        ...
+
+    @overload
+    def get_state(self, intended_type: None = None, default: Any = None) -> Any:
+        ...
+
+    def get_state(self, intended_type: Optional[Type[TState]] = None, default: Optional[TState] = None) -> Union[None, TState, Any]:
+        if self._current_state is None and default is not None:
+            return default
+
+        if intended_type is None:
+            return self._current_state
+
+        if isinstance(self._current_state, intended_type):
+            return self._current_state
+
+        try:
+            return intended_type(self._current_state)  # type: ignore[call-arg]
+        except Exception as ex:
+            raise TypeError(
+                f"Could not convert state of type '{type(self._current_state).__name__}' to '{intended_type.__name__}'"
+            ) from ex
+
+    def set_state(self, state):
+        self._current_state = state
+
+    def add_operation_action(self, action: pb.OperationAction):
+        self._operation_actions.append(action)
+
+    def get_operation_actions(self) -> list[pb.OperationAction]:
+        return self._operation_actions[:self._actions_checkpoint_state]
+
+    def commit(self):
+        self._checkpoint_state = self._current_state
+        self._actions_checkpoint_state = len(self._operation_actions)
+
+    def rollback(self):
+        self._current_state = self._checkpoint_state
+        self._operation_actions = self._operation_actions[:self._actions_checkpoint_state]
+
+    def reset(self):
+        self._current_state = None
+        self._checkpoint_state = None
+        self._operation_actions = []
+        self._actions_checkpoint_state = 0

durabletask-0.5.0/durabletask/internal/exceptions.py

@@ -0,0 +1,11 @@
+import durabletask.internal.orchestrator_service_pb2 as pb
+
+
+class VersionFailureException(Exception):
+    def __init__(self, error_details: pb.TaskFailureDetails) -> None:
+        super().__init__()
+        self.error_details = error_details
+
+
+class AbandonOrchestrationError(Exception):
+    pass

{durabletask-0.4.0 → durabletask-0.5.0}/durabletask/internal/helpers.py

@@ -7,6 +7,7 @@ from typing import Optional
 
 from google.protobuf import timestamp_pb2, wrappers_pb2
 
+from durabletask.entities import EntityInstanceId
 import durabletask.internal.orchestrator_service_pb2 as pb
 
 # TODO: The new_xxx_event methods are only used by test code and should be moved elsewhere
@@ -159,6 +160,12 @@ def get_string_value(val: Optional[str]) -> Optional[wrappers_pb2.StringValue]:
         return wrappers_pb2.StringValue(value=val)
 
 
+def get_string_value_or_empty(val: Optional[str]) -> wrappers_pb2.StringValue:
+    if val is None:
+        return wrappers_pb2.StringValue(value="")
+    return wrappers_pb2.StringValue(value=val)
+
+
 def new_complete_orchestration_action(
         id: int,
         status: pb.OrchestrationStatus,
@@ -189,6 +196,57 @@ def new_schedule_task_action(id: int, name: str, encoded_input: Optional[str],
     ))
 
 
+def new_call_entity_action(id: int, parent_instance_id: str, entity_id: EntityInstanceId, operation: str, encoded_input: Optional[str]):
+    return pb.OrchestratorAction(id=id, sendEntityMessage=pb.SendEntityMessageAction(entityOperationCalled=pb.EntityOperationCalledEvent(
+        requestId=f"{parent_instance_id}:{id}",
+        operation=operation,
+        scheduledTime=None,
+        input=get_string_value(encoded_input),
+        parentInstanceId=get_string_value(parent_instance_id),
+        parentExecutionId=None,
+        targetInstanceId=get_string_value(str(entity_id)),
+    )))
+
+
+def new_signal_entity_action(id: int, entity_id: EntityInstanceId, operation: str, encoded_input: Optional[str]):
+    return pb.OrchestratorAction(id=id, sendEntityMessage=pb.SendEntityMessageAction(entityOperationSignaled=pb.EntityOperationSignaledEvent(
+        requestId=f"{entity_id}:{id}",
+        operation=operation,
+        scheduledTime=None,
+        input=get_string_value(encoded_input),
+        targetInstanceId=get_string_value(str(entity_id)),
+    )))
+
+
+def new_lock_entities_action(id: int, entity_message: pb.SendEntityMessageAction):
+    return pb.OrchestratorAction(id=id, sendEntityMessage=entity_message)
+
+
+def convert_to_entity_batch_request(req: pb.EntityRequest) -> tuple[pb.EntityBatchRequest, list[pb.OperationInfo]]:
+    batch_request = pb.EntityBatchRequest(entityState=req.entityState, instanceId=req.instanceId, operations=[])
+
+    operation_infos: list[pb.OperationInfo] = []
+
+    for op in req.operationRequests:
+        if op.HasField("entityOperationSignaled"):
+            batch_request.operations.append(pb.OperationRequest(requestId=op.entityOperationSignaled.requestId,
+                                                                operation=op.entityOperationSignaled.operation,
+                                                                input=op.entityOperationSignaled.input))
+            operation_infos.append(pb.OperationInfo(requestId=op.entityOperationSignaled.requestId,
+                                                    responseDestination=None))
+        elif op.HasField("entityOperationCalled"):
+            batch_request.operations.append(pb.OperationRequest(requestId=op.entityOperationCalled.requestId,
+                                                                operation=op.entityOperationCalled.operation,
+                                                                input=op.entityOperationCalled.input))
+            operation_infos.append(pb.OperationInfo(requestId=op.entityOperationCalled.requestId,
+                                                    responseDestination=pb.OrchestrationInstance(
+                                                        instanceId=op.entityOperationCalled.parentInstanceId.value,
+                                                        executionId=op.entityOperationCalled.parentExecutionId
+                                                    )))
+
+    return batch_request, operation_infos
+
+
 def new_timestamp(dt: datetime) -> timestamp_pb2.Timestamp:
     ts = timestamp_pb2.Timestamp()
     ts.FromDatetime(dt)