Docstrings for several api level objects

OchrestrationState, Task, TaskSet, clean up some excess docstrings

Author: scgbear

.flake8

@@ -1,8 +1,9 @@
 [flake8]
-# delete D100~D107 for docstring checks
+# delete D100 for docstring checks, promotes redundant documentation of what's in class docstring
 # W503 contradicts with pep8 and will soon be fixed by flake8
-ignore = W503
+ignore = W503, D100
 max-line-length = 99
+docstring-convention = numpy
 exclude =
     __pycache__,
     azure/durable_functions/grpc/protobuf/

azure/durable_functions/interfaces/IAction.py

@@ -1,10 +1,8 @@
-"""Defines the base interface for Actions that need to be executed."""
 from ..models.actions import ActionType
 
 
 class IAction:
     """Defines the base interface for Actions that need to be executed."""
 
     def __init__(self):
-        """Create a new Action object."""
         actionType: ActionType

azure/durable_functions/interfaces/IFunctionContext.py

@@ -1,10 +1,8 @@
-"""Interface for the Orchestration object exposed to the generator function."""
 from ..models import DurableOrchestrationContext
 
 
 class IFunctionContext:
-    """Orchestration object exposed to the generator function."""
+    """Interface for the Orchestration object exposed to the generator function."""
 
     def __init__(self, df=None):
-        """Create a new orchestration context."""
         self.df: DurableOrchestrationContext = df

azure/durable_functions/models/DurableOrchestrationBindings.py

@@ -1,4 +1,3 @@
-"""Binding information for durable functions."""
 import json
 from typing import Dict
 
@@ -11,7 +10,6 @@ class DurableOrchestrationBindings:
     """
 
     def __init__(self, client_data: str):
-        """Create a new binding object."""
         context = json.loads(client_data)
         self.task_hub_name: str = context.get('taskHubName')
         self.creation_urls: Dict[str, str] = context.get('creationUrls')

azure/durable_functions/models/DurableOrchestrationClient.py

@@ -1,4 +1,3 @@
-"""Durable Orchestration Client class definition."""
 import requests
 import json
 from typing import List
@@ -14,11 +13,6 @@ class DurableOrchestrationClient:
     """
 
     def __init__(self, context: str):
-        """Create a new Orchestration Client.
-
-        :param context: The object representing the orchestrationClient input
-        binding of the Azure function that will use this client.
-        """
         self.task_hub_name: str
         self._uniqueWebHookOrigins: List[str]
         self._event_name_placeholder: str = "{eventName}"
@@ -65,9 +59,7 @@ def _get_json_input(client_input: object) -> object:
         return json.dumps(client_input) if client_input is not None else None
 
     def _get_start_new_url(self, instance_id, orchestration_function_name):
-        request_url = self._orchestration_bindings.creation_urls[
-                'createNewInstancePostUri'
-        ]
+        request_url = self._orchestration_bindings.creation_urls['createNewInstancePostUri']
         request_url = request_url.replace(self._function_name_placeholder,
                                           orchestration_function_name)
         request_url = request_url.replace(self._instance_id_placeholder,

azure/durable_functions/models/DurableOrchestrationContext.py

@@ -1,4 +1,3 @@
-"""Defines the Durable Orchestration Context Class Object."""
 import json
 import logging
 import datetime

azure/durable_functions/models/OrchestratorState.py

@@ -1,4 +1,3 @@
-"""Defines the Orchestration State Class structure."""
 import json
 from typing import List, Any, Dict
 
@@ -24,6 +23,40 @@ def __init__(self,
         self._error: str = error
         self._custom_status: Any = custom_status
 
+    @property
+    def actions(self) -> List[List[Any]]:
+        """Get the ordered list of async actions the orchestrator function should perform.
+
+        This list is append-only; it must contain all scheduled async actions up to the latest
+        requested work, even actions that have already been completed.
+
+        Actions are grouped by execution. Each subsequent orchestrator execution should add a
+        new array of action objects to the collection.
+        """
+        return self._actions
+
+    @property
+    def is_done(self) -> bool:
+        """Get indicator of whether this is the last execution of this orchestrator instance.
+
+        When this value is true, the Durable Functions extension will consider the orchestration
+        instance completed and will attempt to return the output value.
+        """
+        return self._is_done
+
+    @property
+    def output(self):
+        """Get the JSON-serializable value returned by the orchestrator instance completion.
+
+        Optional.
+        """
+        return self._output
+
+    @property
+    def custom_status(self):
+        """Get the JSON-serializable value used by DurableOrchestrationContext.SetCustomStatus."""
+        return self._custom_status
+
     def to_json(self) -> Dict[str, Any]:
         """Convert object into a json dictionary.
 

azure/durable_functions/models/RetryOptions.py

@@ -1,4 +1,3 @@
-"""Define the Retry Options class."""
 from typing import Any, Dict
 
 from .utils.json_utils import add_attrib

azure/durable_functions/models/Task.py

@@ -14,7 +14,6 @@ class Task:
     are useful for parallelization and timeout operations in conjunction with
     Task.all and Task.any.
     """
-    _action: IAction
 
     def __init__(self, is_completed, is_faulted, action,
                  result=None, timestamp=None, id_=None, exc=None):
@@ -37,7 +36,6 @@ def is_completed(self) -> bool:
     @property
     def is_faulted(self) -> bool:
         """Get indicator whether the task faulted in some way due to error."""
-
         return self._is_faulted
 
     @property

azure/durable_functions/models/TaskSet.py

@@ -3,9 +3,55 @@
 
 
 class TaskSet:
-    def __init__(self, isCompleted, actions, result, isFaulted=False, e=None):
-        self.isCompleted: bool = isCompleted
-        self.actions: List[IAction] = actions
-        self.result = result
-        self.isFaulted: bool = isFaulted
-        self.exception = e
+    """Represents a list of some pending action.
+
+    Similar to a native JavaScript promise in
+    that it acts as a placeholder for outstanding asynchronous work, but has
+    a synchronous implementation and is specific to Durable Functions.
+
+    Tasks are only returned to an orchestration function when a
+    [[DurableOrchestrationContext]] operation is not called with `yield`. They
+    are useful for parallelization and timeout operations in conjunction with
+    Task.all and Task.any.
+    """
+
+    def __init__(self, is_completed, actions, result, is_faulted=False, exception=None):
+        self._is_completed: bool = is_completed
+        self._actions: List[IAction] = actions
+        self._result = result
+        self._is_faulted: bool = is_faulted
+        self._exception = exception
+
+    @property
+    def is_completed(self) -> bool:
+        """Get indicator whether the task has completed.
+
+        Note that completion is not equivalent to success.
+        """
+        return self._is_completed
+
+    @property
+    def is_faulted(self) -> bool:
+        """Get indicator whether the task faulted in some way due to error."""
+        return self._is_faulted
+
+    @property
+    def actions(self) -> IAction:
+        """Get the scheduled action represented by the task.
+
+        _Internal use only._
+        """
+        return self._actions
+
+    @property
+    def result(self) -> object:
+        """Get the result of the task, if completed. Otherwise `None`."""
+        return self._result
+
+    @property
+    def exception(self):
+        """Get the error thrown when attempting to perform the task's action.
+
+        If the Task has not yet completed or has completed successfully, `None`
+        """
+        return self._exception

azure/durable_functions/tasks/call_activity_with_retry.py

@@ -1,4 +1,3 @@
-import logging
 from typing import List, Any
 import logging
 

tests/orchestrator/test_sequential_orchestrator.py

@@ -26,7 +26,7 @@ def base_expected_state(output=None) -> OrchestratorState:
 
 def add_hello_action(state: OrchestratorState, input_: str):
     action = CallActivityAction(function_name='Hello', input_=input_)
-    state._actions.append([action])
+    state.actions.append([action])
 
 
 def add_hello_completed_events(