Merge branch 'dev' into master

Author: davidmrdavid

CONTRIBUTING.md

@@ -70,7 +70,7 @@ Note: Conda based environments are not yet supported in Azure Functions.
 ### Setting up durable-py debugging
 
 
-1.  Git clone your fork and use any starter sample from this [folder] in your fork (https://github.com/Azure/azure-functions-durable-python/tree/dev/samples/) and open this folder in your VS Code editor.
+1.  Git clone your fork and use any starter sample from this [folder](https://github.com/Azure/azure-functions-durable-python/tree/dev/samples/) in your fork and open this folder in your VS Code editor.
 
 2. Initialize this folder as an Azure Functions project using the VS Code Extension using these [instructions](https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-function-vs-code?pivots=programming-language-python). This step will create a Python virtual environment if one doesn't exist already.
 

README.md

@@ -5,68 +5,26 @@
 
 # Durable Functions for Python
 
-The `azure-functions-durable` [pip](https://pypi.org/project/azure-functions-durable/) package allows you to write [Durable Functions](https://docs.microsoft.com/en-us/azure/azure-functions/durable/durable-functions-overview) for [Python](https://docs.microsoft.com/en-us/azure/azure-functions/functions-reference-python). Durable Functions is an extension of [Azure Functions](https://docs.microsoft.com/en-us/azure/azure-functions/functions-overview) that lets you write stateful functions and workflows in a serverless environment. The extension manages state, checkpoints, and restarts for you. Durable Functions' advantages include:
+ [Durable Functions](https://docs.microsoft.com/en-us/azure/azure-functions/durable/durable-functions-overview) is an extension of [Azure Functions](https://docs.microsoft.com/en-us/azure/azure-functions/functions-overview) that lets you write stateful functions in a serverless compute environment. The extension lets you define stateful workflows by writing orchestrator functions and stateful entities by writing entity functions using the Azure Functions programming model. Behind the scenes, the extension manages state, checkpoints, and restarts for you, allowing you to focus on your business logic.
+
+ 🐍  Find us on PyPi [here](https://pypi.org/project/azure-functions-durable/) 🐍   
 
-* Define workflows in code. No JSON schemas or designers are needed.
-* Call other functions synchronously and asynchronously. Output from called functions can be saved to local variables.
-* Automatically checkpoint progress whenever the function schedules async work. Local state is never lost if the process recycles or the VM reboots.
 
 You can find more information at the following links:
 
 * [Azure Functions overview](https://docs.microsoft.com/en-us/azure/azure-functions/functions-overview)
 * [Azure Functions Python developers guide](https://docs.microsoft.com/en-us/azure/azure-functions/functions-reference-python)
 * [Durable Functions overview](https://docs.microsoft.com/en-us/azure/azure-functions/durable/durable-functions-overview?tabs=python)
+* [Core concepts and features overview](https://docs.microsoft.com/en-us/azure/azure-functions/durable/durable-functions-types-features-overview).
 
-A durable function, or _orchestration_, is a solution made up of different types of Azure Functions:
-
-* **Activity:** the functions and tasks being orchestrated by your workflow.
-* **Orchestrator:** a function that describes the way and order actions are executed in code.
-* **Client:** the entry point for creating an instance of a durable orchestration.
-
-Durable Functions' function types and features are documented in-depth [here.](https://docs.microsoft.com/en-us/azure/azure-functions/durable/durable-functions-types-features-overview)
-
-## Current limitations
-
-Python support for Durable Functions is currently in public preview. The following are the current known limitations.
-
-### Functionality
-
-* Sub-orchestrations are not yet supported (planned [#62](https://github.com/Azure/azure-functions-durable-python/issues/62))
-* Durable Entities are not yet supported (not yet planned [#96](https://github.com/Azure/azure-functions-durable-python/issues/96))
-
-### Tooling
-
-* Python Durable Functions requires [Azure Functions Core Tools](https://docs.microsoft.com/en-us/azure/azure-functions/functions-run-local) version 3.0.2630 or higher.
+> Durable Functions expects certain programming constraints to be followed. Please read the documentation linked above for more information.
 
 ## Getting Started
 
 Follow these instructions to get started with Durable Functions in Python:
 
 **🚀 [Python Durable Functions quickstart](https://docs.microsoft.com/azure/azure-functions/durable/quickstart-python-vscode)**
 
-## Samples
-
-Take a look at this project's [samples directory](./samples/):
-
-* [Function Chaining](./samples/function_chaining)
-* [Fan-out/Fan-in - Simple](./samples/fan_out_fan_in)
-* [Fan-out/Fan-in - TensorFlow](./samples/fan_out_fan_in_tensorflow)
-* [External Events - Human Interaction & Timeouts](./samples/external_events)
-
-### Orchestrator example
-
-```python
-import azure.durable_functions as df
-
-
-def orchestrator_function(context: df.DurableOrchestrationContext):
-    task1 = yield context.call_activity("DurableActivity", "One")
-    task2 = yield context.call_activity("DurableActivity", "Two")
-    task3 = yield context.call_activity("DurableActivity", "Three")
-
-    outputs = [task1, task2, task3]
-    return outputs
-
+## Tooling
 
-main = df.Orchestrator.create(orchestrator_function)
-```
+* Python Durable Functions requires [Azure Functions Core Tools](https://docs.microsoft.com/en-us/azure/azure-functions/functions-run-local) version 3.0.2630 or higher.

azure/durable_functions/__init__.py

@@ -3,14 +3,20 @@
 Exposes the different API components intended for public consumption
 """
 from .orchestrator import Orchestrator
+from .entity import Entity
+from .models.utils.entity_utils import EntityId
 from .models.DurableOrchestrationClient import DurableOrchestrationClient
 from .models.DurableOrchestrationContext import DurableOrchestrationContext
+from .models.DurableEntityContext import DurableEntityContext
 from .models.RetryOptions import RetryOptions
 from .models.TokenSource import ManagedIdentityTokenSource
 
 __all__ = [
     'Orchestrator',
+    'Entity',
+    'EntityId',
     'DurableOrchestrationClient',
+    'DurableEntityContext',
     'DurableOrchestrationContext',
     'ManagedIdentityTokenSource',
     'RetryOptions'

azure/durable_functions/entity.py

@@ -0,0 +1,125 @@
+from .models import DurableEntityContext
+from .models.entities import OperationResult, EntityState
+from datetime import datetime
+from typing import Callable, Any, List, Dict
+
+
+class InternalEntityException(Exception):
+    """Framework-internal Exception class (for internal use only)."""
+
+    pass
+
+
+class Entity:
+    """Durable Entity Class.
+
+    Responsible for executing the user-defined entity function.
+    """
+
+    def __init__(self, entity_func: Callable[[DurableEntityContext], None]):
+        """Create a new entity for the user-defined entity.
+
+        Responsible for executing the user-defined entity function
+
+        Parameters
+        ----------
+        entity_func: Callable[[DurableEntityContext], Generator[Any, Any, Any]]
+            The user defined entity function
+        """
+        self.fn: Callable[[DurableEntityContext], None] = entity_func
+
+    def handle(self, context: DurableEntityContext, batch: List[Dict[str, Any]]) -> str:
+        """Handle the execution of the user-defined entity function.
+
+        Loops over the batch, which serves to specify inputs to the entity,
+        and collects results and generates a final state, which are returned.
+
+        Parameters
+        ----------
+        context: DurableEntityContext
+            The entity context of the entity, which the user interacts with as their Durable API
+
+        Returns
+        -------
+        str
+            A JSON-formatted string representing the output state, results, and exceptions for the
+            entity execution.
+        """
+        response = EntityState(results=[], signals=[])
+        for operation_data in batch:
+            result: Any = None
+            is_error: bool = False
+            start_time: datetime = datetime.now()
+
+            try:
+                # populate context
+                operation = operation_data["name"]
+                if operation is None:
+                    message = "Durable Functions Internal Error:"\
+                        "Entity operation was missing a name field"
+                    raise InternalEntityException(message)
+                context._operation = operation
+                context._input = operation_data["input"]
+                self.fn(context)
+                result = context._result
+
+            except InternalEntityException as e:
+                raise e
+
+            except Exception as e:
+                is_error = True
+                result = str(e)
+
+            duration: int = self._elapsed_milliseconds_since(start_time)
+            operation_result = OperationResult(
+                is_error=is_error,
+                duration=duration,
+                result=result
+            )
+            response.results.append(operation_result)
+
+        response.state = context._state
+        response.entity_exists = context._exists
+        return response.to_json_string()
+
+    @classmethod
+    def create(cls, fn: Callable[[DurableEntityContext], None]) -> Callable[[Any], str]:
+        """Create an instance of the entity class.
+
+        Parameters
+        ----------
+            fn (Callable[[DurableEntityContext], None]): [description]
+
+        Returns
+        -------
+        Callable[[Any], str]
+            Handle function of the newly created entity client
+        """
+        def handle(context) -> str:
+            # It is not clear when the context JSON would be found
+            # inside a "body"-key, but this pattern matches the
+            # orchestrator implementation, so we keep it for safety.
+            context_body = getattr(context, "body", None)
+            if context_body is None:
+                context_body = context
+            ctx, batch = DurableEntityContext.from_json(context_body)
+            return Entity(fn).handle(ctx, batch)
+        return handle
+
+    def _elapsed_milliseconds_since(self, start_time: datetime) -> int:
+        """Calculate the elapsed time, in milliseconds, from the start_time to the present.
+
+        Parameters
+        ----------
+        start_time: datetime
+            The timestamp of when the entity began processing a batched request.
+
+        Returns
+        -------
+        int
+            The time, in millseconds, from start_time to now
+        """
+        end_time = datetime.now()
+        time_diff = end_time - start_time
+        elapsed_time = int(time_diff.total_seconds() * 1000)
+        return elapsed_time