durabletask 0.0.0.dev38__tar.gz → 0.0.0.dev40__tar.gz

{durabletask-0.0.0.dev38 → durabletask-0.0.0.dev40}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: durabletask
-Version: 0.0.0.dev38
+Version: 0.0.0.dev40
 Summary: A Durable Task Client SDK for Python
 License:     MIT License
         

{durabletask-0.0.0.dev38 → durabletask-0.0.0.dev40}/durabletask/client.py

@@ -4,12 +4,12 @@
 import logging
 import uuid
 from dataclasses import dataclass
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 from enum import Enum
-from typing import Any, Optional, Sequence, TypeVar, Union
+from typing import Any, List, Optional, Sequence, TypeVar, Union
 
 import grpc
-from google.protobuf import wrappers_pb2
+from google.protobuf import wrappers_pb2 as pb2
 
 from durabletask.entities import EntityInstanceId
 from durabletask.entities.entity_metadata import EntityMetadata
@@ -57,6 +57,12 @@ class OrchestrationState:
                 self.failure_details)
 
 
+class PurgeInstancesResult:
+    def __init__(self, deleted_instance_count: int, is_complete: bool):
+        self.deleted_instance_count = deleted_instance_count
+        self.is_complete = is_complete
+
+
 class OrchestrationFailedError(Exception):
     def __init__(self, message: str, failure_details: task.FailureDetails):
         super().__init__(message)
@@ -73,6 +79,12 @@ def new_orchestration_state(instance_id: str, res: pb.GetInstanceResponse) -> Op
 
     state = res.orchestrationState
 
+    new_state = parse_orchestration_state(state)
+    new_state.instance_id = instance_id  # Override instance_id with the one from the request, to match old behavior
+    return new_state
+
+
+def parse_orchestration_state(state: pb.OrchestrationState) -> OrchestrationState:
     failure_details = None
     if state.failureDetails.errorMessage != '' or state.failureDetails.errorType != '':
         failure_details = task.FailureDetails(
@@ -81,7 +93,7 @@ def new_orchestration_state(instance_id: str, res: pb.GetInstanceResponse) -> Op
             state.failureDetails.stackTrace.value if not helpers.is_empty(state.failureDetails.stackTrace) else None)
 
     return OrchestrationState(
-        instance_id,
+        state.instanceId,
         state.name,
         OrchestrationStatus(state.orchestrationStatus),
         state.createdTimestamp.ToDatetime(),
@@ -93,7 +105,6 @@ def new_orchestration_state(instance_id: str, res: pb.GetInstanceResponse) -> Op
 
 
 class TaskHubGrpcClient:
-
     def __init__(self, *,
                  host_address: Optional[str] = None,
                  metadata: Optional[list[tuple[str, str]]] = None,
@@ -136,7 +147,7 @@ class TaskHubGrpcClient:
         req = pb.CreateInstanceRequest(
             name=name,
             instanceId=instance_id if instance_id else uuid.uuid4().hex,
-            input=wrappers_pb2.StringValue(value=shared.to_json(input)) if input is not None else None,
+            input=helpers.get_string_value(shared.to_json(input)),
             scheduledStartTimestamp=helpers.new_timestamp(start_at) if start_at else None,
             version=helpers.get_string_value(version if version else self.default_version),
             orchestrationIdReusePolicy=reuse_id_policy,
@@ -152,6 +163,54 @@ class TaskHubGrpcClient:
         res: pb.GetInstanceResponse = self._stub.GetInstance(req)
         return new_orchestration_state(req.instanceId, res)
 
+    def get_all_orchestration_states(self,
+                                     max_instance_count: Optional[int] = None,
+                                     fetch_inputs_and_outputs: bool = False) -> List[OrchestrationState]:
+        return self.get_orchestration_state_by(
+            created_time_from=None,
+            created_time_to=None,
+            runtime_status=None,
+            max_instance_count=max_instance_count,
+            fetch_inputs_and_outputs=fetch_inputs_and_outputs
+        )
+
+    def get_orchestration_state_by(self,
+                                   created_time_from: Optional[datetime] = None,
+                                   created_time_to: Optional[datetime] = None,
+                                   runtime_status: Optional[List[OrchestrationStatus]] = None,
+                                   max_instance_count: Optional[int] = None,
+                                   fetch_inputs_and_outputs: bool = False,
+                                   _continuation_token: Optional[pb2.StringValue] = None
+                                   ) -> List[OrchestrationState]:
+        if max_instance_count is None:
+            # DTS backend does not behave well with max_instance_count = None, so we set to max 32-bit signed value
+            max_instance_count = (1 << 31) - 1
+        req = pb.QueryInstancesRequest(
+            query=pb.InstanceQuery(
+                runtimeStatus=[status.value for status in runtime_status] if runtime_status else None,
+                createdTimeFrom=helpers.new_timestamp(created_time_from) if created_time_from else None,
+                createdTimeTo=helpers.new_timestamp(created_time_to) if created_time_to else None,
+                maxInstanceCount=max_instance_count,
+                fetchInputsAndOutputs=fetch_inputs_and_outputs,
+                continuationToken=_continuation_token
+            )
+        )
+        resp: pb.QueryInstancesResponse = self._stub.QueryInstances(req)
+        states = [parse_orchestration_state(res) for res in resp.orchestrationState]
+        # Check the value for continuationToken - none or "0" indicates that there are no more results.
+        if resp.continuationToken and resp.continuationToken.value and resp.continuationToken.value != "0":
+            self._logger.info(f"Received continuation token with value {resp.continuationToken.value}, fetching next list of instances...")
+            states += self.get_orchestration_state_by(
+                created_time_from,
+                created_time_to,
+                runtime_status,
+                max_instance_count,
+                fetch_inputs_and_outputs,
+                _continuation_token=resp.continuationToken
+            )
+        states = [state for state in states if state is not None]  # Filter out any None values
+        return states
+
     def wait_for_orchestration_start(self, instance_id: str, *,
                                      fetch_payloads: bool = False,
                                      timeout: int = 60) -> Optional[OrchestrationState]:
@@ -199,7 +258,7 @@ class TaskHubGrpcClient:
         req = pb.RaiseEventRequest(
             instanceId=instance_id,
             name=event_name,
-            input=wrappers_pb2.StringValue(value=shared.to_json(data)) if data else None)
+            input=helpers.get_string_value(shared.to_json(data)))
 
         self._logger.info(f"Raising event '{event_name}' for instance '{instance_id}'.")
         self._stub.RaiseEvent(req)
@@ -209,7 +268,7 @@ class TaskHubGrpcClient:
                                 recursive: bool = True):
         req = pb.TerminateRequest(
             instanceId=instance_id,
-            output=wrappers_pb2.StringValue(value=shared.to_json(output)) if output else None,
+            output=helpers.get_string_value(shared.to_json(output)),
             recursive=recursive)
 
         self._logger.info(f"Terminating instance '{instance_id}'.")
@@ -225,30 +284,27 @@ class TaskHubGrpcClient:
         self._logger.info(f"Resuming instance '{instance_id}'.")
         self._stub.ResumeInstance(req)
 
-    def restart_orchestration(self, instance_id: str, *,
-                              restart_with_new_instance_id: bool = False) -> str:
-        """Restarts an existing orchestration instance.
-
-        Args:
-            instance_id: The ID of the orchestration instance to restart.
-            restart_with_new_instance_id: If True, the restarted orchestration will use a new instance ID.
-                If False (default), the restarted orchestration will reuse the same instance ID.
-
-        Returns:
-            The instance ID of the restarted orchestration.
-        """
-        req = pb.RestartInstanceRequest(
-            instanceId=instance_id,
-            restartWithNewInstanceId=restart_with_new_instance_id)
-
-        self._logger.info(f"Restarting instance '{instance_id}'.")
-        res: pb.RestartInstanceResponse = self._stub.RestartInstance(req)
-        return res.instanceId
-
-    def purge_orchestration(self, instance_id: str, recursive: bool = True):
+    def purge_orchestration(self, instance_id: str, recursive: bool = True) -> PurgeInstancesResult:
         req = pb.PurgeInstancesRequest(instanceId=instance_id, recursive=recursive)
         self._logger.info(f"Purging instance '{instance_id}'.")
-        self._stub.PurgeInstances(req)
+        resp: pb.PurgeInstancesResponse = self._stub.PurgeInstances(req)
+        return PurgeInstancesResult(resp.deletedInstanceCount, resp.isComplete.value)
+
+    def purge_orchestrations_by(self,
+                                created_time_from: Optional[datetime] = None,
+                                created_time_to: Optional[datetime] = None,
+                                runtime_status: Optional[List[OrchestrationStatus]] = None,
+                                recursive: bool = False) -> PurgeInstancesResult:
+        resp: pb.PurgeInstancesResponse = self._stub.PurgeInstances(pb.PurgeInstancesRequest(
+            instanceId=None,
+            purgeInstanceFilter=pb.PurgeInstanceFilter(
+                createdTimeFrom=helpers.new_timestamp(created_time_from) if created_time_from else None,
+                createdTimeTo=helpers.new_timestamp(created_time_to) if created_time_to else None,
+                runtimeStatus=[status.value for status in runtime_status] if runtime_status else None
+            ),
+            recursive=recursive
+        ))
+        return PurgeInstancesResult(resp.deletedInstanceCount, resp.isComplete.value)
 
     def signal_entity(self,
                       entity_instance_id: EntityInstanceId,
@@ -257,7 +313,7 @@ class TaskHubGrpcClient:
         req = pb.SignalEntityRequest(
             instanceId=str(entity_instance_id),
             name=operation_name,
-            input=wrappers_pb2.StringValue(value=shared.to_json(input)) if input else None,
+            input=helpers.get_string_value(shared.to_json(input)),
             requestId=str(uuid.uuid4()),
             scheduledTime=None,
             parentTraceContext=None,
@@ -276,4 +332,53 @@ class TaskHubGrpcClient:
         if not res.exists:
             return None
 
-        return EntityMetadata.from_entity_response(res, include_state)
+        return EntityMetadata.from_entity_metadata(res.entity, include_state)
+
+    def get_all_entities(self,
+                         include_state: bool = True,
+                         include_transient: bool = False,
+                         page_size: Optional[int] = None) -> List[EntityMetadata]:
+        return self.get_entities_by(
+            instance_id_starts_with=None,
+            last_modified_from=None,
+            last_modified_to=None,
+            include_state=include_state,
+            include_transient=include_transient,
+            page_size=page_size
+        )
+
+    def get_entities_by(self,
+                        instance_id_starts_with: Optional[str] = None,
+                        last_modified_from: Optional[datetime] = None,
+                        last_modified_to: Optional[datetime] = None,
+                        include_state: bool = True,
+                        include_transient: bool = False,
+                        page_size: Optional[int] = None,
+                        _continuation_token: Optional[pb2.StringValue] = None
+                        ) -> List[EntityMetadata]:
+        self._logger.info(f"Getting entities")
+        query_request = pb.QueryEntitiesRequest(
+            query=pb.EntityQuery(
+                instanceIdStartsWith=helpers.get_string_value(instance_id_starts_with),
+                lastModifiedFrom=helpers.new_timestamp(last_modified_from) if last_modified_from else None,
+                lastModifiedTo=helpers.new_timestamp(last_modified_to) if last_modified_to else None,
+                includeState=include_state,
+                includeTransient=include_transient,
+                pageSize=helpers.get_int_value(page_size),
+                continuationToken=_continuation_token
+            )
+        )
+        resp: pb.QueryEntitiesResponse = self._stub.QueryEntities(query_request)
+        entities = [EntityMetadata.from_entity_metadata(entity, query_request.query.includeState) for entity in resp.entities]
+        if resp.continuationToken and resp.continuationToken.value != "0":
+            self._logger.info(f"Received continuation token with value {resp.continuationToken.value}, fetching next page of entities...")
+            entities += self.get_entities_by(
+                instance_id_starts_with=instance_id_starts_with,
+                last_modified_from=last_modified_from,
+                last_modified_to=last_modified_to,
+                include_state=include_state,
+                include_transient=include_transient,
+                page_size=page_size,
+                _continuation_token=resp.continuationToken
+            )
+        return entities

{durabletask-0.0.0.dev38 → durabletask-0.0.0.dev40}/durabletask/entities/__init__.py

@@ -8,7 +8,9 @@ from durabletask.entities.durable_entity import DurableEntity
 from durabletask.entities.entity_lock import EntityLock
 from durabletask.entities.entity_context import EntityContext
 from durabletask.entities.entity_metadata import EntityMetadata
+from durabletask.entities.entity_operation_failed_exception import EntityOperationFailedException
 
-__all__ = ["EntityInstanceId", "DurableEntity", "EntityLock", "EntityContext", "EntityMetadata"]
+__all__ = ["EntityInstanceId", "DurableEntity", "EntityLock", "EntityContext", "EntityMetadata",
+           "EntityOperationFailedException"]
 
 PACKAGE_NAME = "durabletask.entities"

durabletask-0.0.0.dev40/durabletask/entities/entity_instance_id.py

@@ -0,0 +1,84 @@
+class EntityInstanceId:
+    def __init__(self, entity: str, key: str):
+        EntityInstanceId.validate_entity_name(entity)
+        EntityInstanceId.validate_key(key)
+        self.entity = entity.lower()
+        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) -> "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
+        -------
+        EntityInstanceId
+            The parsed EntityInstanceId object.
+
+        Raises
+        ------
+        ValueError
+            If the input string is not in the correct format.
+        """
+        if not entity_id.startswith("@"):
+            raise ValueError("Entity ID must start with '@'.")
+        try:
+            _, entity, key = entity_id.split("@", 2)
+        except ValueError as ex:
+            raise ValueError(f"Invalid entity ID format: {entity_id}") from ex
+        return EntityInstanceId(entity=entity, key=key)
+
+    @staticmethod
+    def validate_entity_name(name: str) -> None:
+        """Validate that the entity name does not contain invalid characters.
+
+        Parameters
+        ----------
+        name : str
+            The entity name to validate.
+
+        Raises
+        ------
+        ValueError
+            If the name is not a valid entity name.
+        """
+        if not name:
+            raise ValueError("Entity name cannot be empty.")
+        if "@" in name:
+            raise ValueError("Entity name cannot contain '@' symbol.")
+
+    @staticmethod
+    def validate_key(key: str) -> None:
+        """Validate that the entity key does not contain invalid characters.
+
+        Parameters
+        ----------
+        key : str
+            The entity key to validate.
+
+        Raises
+        ------
+        ValueError
+            If the key is not a valid entity key.
+        """
+        if not key:
+            raise ValueError("Entity key cannot be empty.")
+        if "@" in key:
+            raise ValueError("Entity key cannot contain '@' symbol.")

{durabletask-0.0.0.dev38 → durabletask-0.0.0.dev40}/durabletask/entities/entity_metadata.py

@@ -44,18 +44,22 @@ class EntityMetadata:
 
     @staticmethod
     def from_entity_response(entity_response: pb.GetEntityResponse, includes_state: bool):
+        return EntityMetadata.from_entity_metadata(entity_response.entity, includes_state)
+
+    @staticmethod
+    def from_entity_metadata(entity: pb.EntityMetadata, includes_state: bool):
         try:
-            entity_id = EntityInstanceId.parse(entity_response.entity.instanceId)
+            entity_id = EntityInstanceId.parse(entity.instanceId)
         except ValueError:
             raise ValueError("Invalid entity instance ID in entity response.")
         entity_state = None
         if includes_state:
-            entity_state = entity_response.entity.serializedState.value
+            entity_state = entity.serializedState.value
         return EntityMetadata(
             id=entity_id,
-            last_modified=entity_response.entity.lastModifiedTime.ToDatetime(timezone.utc),
-            backlog_queue_size=entity_response.entity.backlogQueueSize,
-            locked_by=entity_response.entity.lockedBy.value,
+            last_modified=entity.lastModifiedTime.ToDatetime(timezone.utc),
+            backlog_queue_size=entity.backlogQueueSize,
+            locked_by=entity.lockedBy.value,
             includes_state=includes_state,
             state=entity_state
         )

durabletask-0.0.0.dev40/durabletask/entities/entity_operation_failed_exception.py

@@ -0,0 +1,15 @@
+from durabletask.internal.orchestrator_service_pb2 import TaskFailureDetails
+from durabletask.entities.entity_instance_id import EntityInstanceId
+
+
+class EntityOperationFailedException(Exception):
+    """Exception raised when an operation on an Entity Function fails."""
+
+    def __init__(self, entity_instance_id: EntityInstanceId, operation_name: str, failure_details: TaskFailureDetails) -> None:
+        super().__init__()
+        self.entity_instance_id = entity_instance_id
+        self.operation_name = operation_name
+        self.failure_details = failure_details
+
+    def __str__(self) -> str:
+        return f"Operation '{self.operation_name}' on entity '{self.entity_instance_id}' failed with error: {self.failure_details.errorMessage}"

{durabletask-0.0.0.dev38 → durabletask-0.0.0.dev40}/durabletask/internal/helpers.py

@@ -184,6 +184,13 @@ def get_string_value(val: Optional[str]) -> Optional[wrappers_pb2.StringValue]:
         return wrappers_pb2.StringValue(value=val)
 
 
+def get_int_value(val: Optional[int]) -> Optional[wrappers_pb2.Int32Value]:
+    if val is None:
+        return None
+    else:
+        return wrappers_pb2.Int32Value(value=val)
+
+
 def get_string_value_or_empty(val: Optional[str]) -> wrappers_pb2.StringValue:
     if val is None:
         return wrappers_pb2.StringValue(value="")

durabletask-0.0.0.dev40/durabletask/internal/json_encode_output_exception.py

@@ -0,0 +1,12 @@
+from typing import Any
+
+
+class JsonEncodeOutputException(Exception):
+    """Custom exception type used to indicate that an orchestration result could not be JSON-encoded."""
+
+    def __init__(self, problem_object: Any):
+        super().__init__()
+        self.problem_object = problem_object
+
+    def __str__(self) -> str:
+        return f"The orchestration result could not be encoded. Object details: {self.problem_object}"