Add support for PyStein programming model (#398)

Author: davidmrdavid

azure/durable_functions/__init__.py

@@ -11,6 +11,7 @@
 from .models.DurableEntityContext import DurableEntityContext
 from .models.RetryOptions import RetryOptions
 from .models.TokenSource import ManagedIdentityTokenSource
+from .decorators import DFApp
 import json
 from pathlib import Path
 import sys
@@ -69,5 +70,6 @@ def validate_extension_bundles():
     'DurableOrchestrationContext',
     'ManagedIdentityTokenSource',
     'OrchestrationRuntimeStatus',
-    'RetryOptions'
+    'RetryOptions',
+    'DFApp'
 ]

azure/durable_functions/constants.py

@@ -3,3 +3,7 @@
 DEFAULT_LOCAL_ORIGIN: str = f'http://{DEFAULT_LOCAL_HOST}'
 DATETIME_STRING_FORMAT = '%Y-%m-%dT%H:%M:%S.%fZ'
 HTTP_ACTION_NAME = 'BuiltIn::HttpActivity'
+ORCHESTRATION_TRIGGER = "orchestrationTrigger"
+ACTIVITY_TRIGGER = "activityTrigger"
+ENTITY_TRIGGER = "entityTrigger"
+DURABLE_CLIENT = "durableClient"

azure/durable_functions/decorators/__init__.py

@@ -0,0 +1,8 @@
+#  Copyright (c) Microsoft Corporation. All rights reserved.
+#  Licensed under the MIT License.
+"""Decorator definitions for Durable Functions."""
+from .durable_app import DFApp
+
+__all__ = [
+    "DFApp"
+]

azure/durable_functions/decorators/durable_app.py

@@ -0,0 +1,228 @@
+#  Copyright (c) Microsoft Corporation. All rights reserved.
+#  Licensed under the MIT License.
+from .metadata import OrchestrationTrigger, ActivityTrigger, EntityTrigger,\
+    DurableClient
+from typing import Callable, Optional
+from azure.durable_functions.entity import Entity
+from azure.durable_functions.orchestrator import Orchestrator
+from azure.durable_functions import DurableOrchestrationClient
+from typing import Union
+from azure.functions import FunctionRegister, TriggerApi, BindingApi, AuthLevel
+from functools import wraps
+
+
+class DFApp(FunctionRegister, TriggerApi, BindingApi):
+    """Durable Functions (DF) app.
+
+    Exports the decorators required to register DF Function-types.
+    """
+
+    def __init__(self,
+                 http_auth_level: Union[AuthLevel, str] = AuthLevel.FUNCTION):
+        """Instantiate a Durable Functions app with which to register Functions.
+
+        Parameters
+        ----------
+        http_auth_level: Union[AuthLevel, str]
+            Authorization level required for Function invocation.
+            Defaults to AuthLevel.Function.
+
+        Returns
+        -------
+        DFApp
+            New instance of a Durable Functions app
+        """
+        super().__init__(auth_level=http_auth_level)
+
+    def _configure_entity_callable(self, wrap) -> Callable:
+        """Obtain decorator to construct an Entity class from a user-defined Function.
+
+        In the old programming model, this decorator's logic was unavoidable boilerplate
+        in user-code. Now, this is handled internally by the framework.
+
+        Parameters
+        ----------
+        wrap: Callable
+            The next decorator to be applied.
+
+        Returns
+        -------
+        Callable
+            The function to construct an Entity class from the user-defined Function,
+            wrapped by the next decorator in the sequence.
+        """
+        def decorator(entity_func):
+            # Construct an entity based on the end-user code
+            handle = Entity.create(entity_func)
+
+            # invoke next decorator, with the Entity as input
+            handle.__name__ = entity_func.__name__
+            return wrap(handle)
+
+        return decorator
+
+    def _configure_orchestrator_callable(self, wrap) -> Callable:
+        """Obtain decorator to construct an Orchestrator class from a user-defined Function.
+
+        In the old programming model, this decorator's logic was unavoidable boilerplate
+        in user-code. Now, this is handled internally by the framework.
+
+        Parameters
+        ----------
+        wrap: Callable
+            The next decorator to be applied.
+
+        Returns
+        -------
+        Callable
+            The function to construct an Orchestrator class from the user-defined Function,
+            wrapped by the next decorator in the sequence.
+        """
+        def decorator(orchestrator_func):
+            # Construct an orchestrator based on the end-user code
+            handle = Orchestrator.create(orchestrator_func)
+
+            # invoke next decorator, with the Orchestrator as input
+            handle.__name__ = orchestrator_func.__name__
+            return wrap(handle)
+
+        return decorator
+
+    def orchestration_trigger(self, context_name: str,
+                              orchestration: Optional[str] = None):
+        """Register an Orchestrator Function.
+
+        Parameters
+        ----------
+        context_name: str
+            Parameter name of the DurableOrchestrationContext object.
+        orchestration: Optional[str]
+            Name of Orchestrator Function.
+            The value is None by default, in which case the name of the method is used.
+        """
+        @self._configure_orchestrator_callable
+        @self._configure_function_builder
+        def wrap(fb):
+
+            def decorator():
+                fb.add_trigger(
+                    trigger=OrchestrationTrigger(name=context_name,
+                                                 orchestration=orchestration))
+                return fb
+
+            return decorator()
+
+        return wrap
+
+    def activity_trigger(self, input_name: str,
+                         activity: Optional[str] = None):
+        """Register an Activity Function.
+
+        Parameters
+        ----------
+        input_name: str
+            Parameter name of the Activity input.
+        activity: Optional[str]
+            Name of Activity Function.
+            The value is None by default, in which case the name of the method is used.
+        """
+        @self._configure_function_builder
+        def wrap(fb):
+            def decorator():
+                fb.add_trigger(
+                    trigger=ActivityTrigger(name=input_name,
+                                            activity=activity))
+                return fb
+
+            return decorator()
+
+        return wrap
+
+    def entity_trigger(self, context_name: str,
+                       entity_name: Optional[str] = None):
+        """Register an Entity Function.
+
+        Parameters
+        ----------
+        context_name: str
+            Parameter name of the Entity input.
+        entity_name: Optional[str]
+            Name of Entity Function.
+            The value is None by default, in which case the name of the method is used.
+        """
+        @self._configure_entity_callable
+        @self._configure_function_builder
+        def wrap(fb):
+            def decorator():
+                fb.add_trigger(
+                    trigger=EntityTrigger(name=context_name,
+                                          entity_name=entity_name))
+                return fb
+
+            return decorator()
+
+        return wrap
+
+    def _add_rich_client(self, fb, parameter_name,
+                         client_constructor):
+        # Obtain user-code and force type annotation on the client-binding parameter to be `str`.
+        # This ensures a passing type-check of that specific parameter,
+        # circumventing a limitation of the worker in type-checking rich DF Client objects.
+        # TODO: Once rich-binding type checking is possible, remove the annotation change.
+        user_code = fb._function._func
+        user_code.__annotations__[parameter_name] = str
+
+        # `wraps` This ensures we re-export the same method-signature as the decorated method
+        @wraps(user_code)
+        async def df_client_middleware(*args, **kwargs):
+
+            # Obtain JSON-string currently passed as DF Client,
+            # construct rich object from it,
+            # and assign parameter to that rich object
+            starter = kwargs[parameter_name]
+            client = client_constructor(starter)
+            kwargs[parameter_name] = client
+
+            # Invoke user code with rich DF Client binding
+            return await user_code(*args, **kwargs)
+
+        user_code_with_rich_client = df_client_middleware
+        fb._function._func = user_code_with_rich_client
+
+    def durable_client_input(self,
+                             client_name: str,
+                             task_hub: Optional[str] = None,
+                             connection_name: Optional[str] = None
+                             ):
+        """Register a Durable-client Function.
+
+        Parameters
+        ----------
+        client_name: str
+            Parameter name of durable client.
+        task_hub: Optional[str]
+            Used in scenarios where multiple function apps share the same storage account
+            but need to be isolated from each other. If not specified, the default value
+            from host.json is used.
+            This value must match the value used by the target orchestrator functions.
+        connection_name: Optional[str]
+            The name of an app setting that contains a storage account connection string.
+            The storage account represented by this connection string must be the same one
+            used by the target orchestrator functions. If not specified, the default storage
+            account connection string for the function app is used.
+        """
+
+        @self._configure_function_builder
+        def wrap(fb):
+            def decorator():
+                self._add_rich_client(fb, client_name, DurableOrchestrationClient)
+
+                fb.add_binding(
+                    binding=DurableClient(name=client_name,
+                                          task_hub=task_hub,
+                                          connection_name=connection_name))
+                return fb
+
+            return decorator()
+
+        return wrap

azure/durable_functions/decorators/metadata.py

@@ -0,0 +1,109 @@
+#  Copyright (c) Microsoft Corporation. All rights reserved.
+#  Licensed under the MIT License.
+from typing import Optional
+
+from azure.durable_functions.constants import ORCHESTRATION_TRIGGER, \
+    ACTIVITY_TRIGGER, ENTITY_TRIGGER, DURABLE_CLIENT
+from azure.functions.decorators.core import Trigger, InputBinding
+
+
+class OrchestrationTrigger(Trigger):
+    """OrchestrationTrigger.
+
+    Trigger representing an Orchestration Function.
+    """
+
+    @staticmethod
+    def get_binding_name() -> str:
+        """Get the name of this trigger, as a string.
+
+        Returns
+        -------
+        str
+            The string representation of this trigger.
+        """
+        return ORCHESTRATION_TRIGGER
+
+    def __init__(self,
+                 name: str,
+                 orchestration: Optional[str] = None,
+                 ) -> None:
+        self.orchestration = orchestration
+        super().__init__(name=name)
+
+
+class ActivityTrigger(Trigger):
+    """ActivityTrigger.
+
+    Trigger representing a Durable Functions Activity.
+    """
+
+    @staticmethod
+    def get_binding_name() -> str:
+        """Get the name of this trigger, as a string.
+
+        Returns
+        -------
+        str
+            The string representation of this trigger.
+        """
+        return ACTIVITY_TRIGGER
+
+    def __init__(self,
+                 name: str,
+                 activity: Optional[str] = None,
+                 ) -> None:
+        self.activity = activity
+        super().__init__(name=name)
+
+
+class EntityTrigger(Trigger):
+    """EntityTrigger.
+
+    Trigger representing an Entity Function.
+    """
+
+    @staticmethod
+    def get_binding_name() -> str:
+        """Get the name of this trigger, as a string.
+
+        Returns
+        -------
+        str
+            The string representation of this trigger.
+        """
+        return ENTITY_TRIGGER
+
+    def __init__(self,
+                 name: str,
+                 entity_name: Optional[str] = None,
+                 ) -> None:
+        self.entity_name = entity_name
+        super().__init__(name=name)
+
+
+class DurableClient(InputBinding):
+    """DurableClient.
+
+    Binding representing a Durable-client object.
+    """
+
+    @staticmethod
+    def get_binding_name() -> str:
+        """Get the name of this Binding, as a string.
+
+        Returns
+        -------
+        str
+            The string representation of this binding.
+        """
+        return DURABLE_CLIENT
+
+    def __init__(self,
+                 name: str,
+                 task_hub: Optional[str] = None,
+                 connection_name: Optional[str] = None
+                 ) -> None:
+        self.task_hub = task_hub
+        self.connection_name = connection_name
+        super().__init__(name=name)

azure/durable_functions/models/DurableOrchestrationClient.py

@@ -203,7 +203,7 @@ def get_client_response_links(
         payload = self._orchestration_bindings.management_urls.copy()
 
         for key, _ in payload.items():
-            if not(request is None) and request.url:
+            if not (request is None) and request.url:
                 payload[key] = self._replace_url_origin(request.url, payload[key])
             payload[key] = payload[key].replace(
                 self._orchestration_bindings.management_urls["id"], instance_id)

azure/durable_functions/models/DurableOrchestrationContext.py

@@ -129,7 +129,7 @@ def _generate_task(self, action: Action,
         task.parent = parent
 
         # if task is retryable, provide the retryable wrapper class
-        if not(retry_options is None):
+        if not (retry_options is None):
             task = RetryAbleTask(task, retry_options, self)
         return task
 
@@ -505,7 +505,7 @@ def will_continue_as_new(self) -> bool:
         return self._continue_as_new_flag
 
     def create_timer(self, fire_at: datetime.datetime) -> TaskBase:
-        """Create a Durable Timer Task to implement a deadline at which to wake-up the orchestrator.
+        """Create a Timer Task to fire after at the specified deadline.
 
         Parameters
         ----------