Add SDK docs for expoded methods

Author: andystaples

durabletask/entities/durable_entity.py

@@ -23,13 +23,61 @@ 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) -> Optional[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)

durabletask/entities/entity_context.py

@@ -55,12 +55,44 @@ 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) -> Optional[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(
@@ -76,6 +108,22 @@ def signal_entity(self, entity_instance_id: EntityInstanceId, operation: str, in
         )
 
     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

durabletask/entities/entity_instance_id.py

@@ -21,6 +21,18 @@ def __lt__(self, 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)

durabletask/task.py

@@ -181,8 +181,12 @@ def signal_entity(
         pass
 
     @abstractmethod
-    def lock_entities(self, entities: list[EntityInstanceId]) -> EntityLock:
-        """Lock the specified entity instances for the duration of the orchestration.
+    def lock_entities(self, entities: list[EntityInstanceId]) -> Task[EntityLock]:
+        """Creates a Task object that locks the specified entity instances.
+
+        The locks will be acquired the next time the orchestrator yields. 
+        Best practice is to immediately yield this Task and enter the returned EntityLock.
+        The lock is released when the EntityLock is exited.
 
         Parameters
         ----------
@@ -192,7 +196,7 @@ def lock_entities(self, entities: list[EntityInstanceId]) -> EntityLock:
         Returns
         -------
         EntityLock
-            A disposable object that acquires and releases the locks when initialized or disposed.
+            A context manager object that releases the locks when exited.
         """
         pass