Address PR feedback and change all examples to use DTS

Author: Nicholas Greenfield

docs/contributing.md renamed to CONTRIBUTING.md

@@ -8,14 +8,14 @@ This repo contains a Python SDK for use with the [Azure Durable Task Scheduler](
 
 ⚠️ This SDK is currently under active development and is evolving rapidly. While it's not yet ready for production use, we are excited about its potential and look forward to your feedback as we continue to improve it. ⚠️
 
-> Note that this SDK is **not** currently compatible with [Azure Durable Functions](https://docs.microsoft.com/azure/azure-functions/durable/durable-functions-overview). If you are looking for a Python SDK for Azure Durable Functions, please see [this repo](https://github.com/Azure/azure-functions-durable-python).
+> Note that this SDK is **not** currently compatible with [Azure Durable Functions](https://learn.microsoft.com/azure/azure-functions/durable/durable-functions-overview). If you are looking for a Python SDK for Azure Durable Functions, please see [this repo](https://github.com/Azure/azure-functions-durable-python).
 
 # References
 - [Supported Patterns](./docs/supported-patterns.md)
 - [Available Features](./docs/features.md)
 - [Getting Started](./docs/getting-started.md)
 - [Development Guide](./docs/development.md) 
-- [Contributing Guide](./docs/development.md)
+- [Contributing Guide](./CONTRIBUTING.md)
 
 ## Trademarks
 This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft 

README.md

@@ -22,14 +22,14 @@ Orchestrations can start child orchestrations using the `call_sub_orchestrator`
 
 Orchestrations can wait for external events using the `wait_for_external_event` API. External events are useful for implementing human interaction patterns, such as waiting for a user to approve an order before continuing.
 
-### Continue-as-new (TODO)
+### Continue-as-new
 
 Orchestrations can be continued as new using the `continue_as_new` API. This API allows an orchestration to restart itself from scratch, optionally with a new input.
 
 ### Suspend, resume, and terminate
 
 Orchestrations can be suspended using the `suspend_orchestration` client API and will remain suspended until resumed using the `resume_orchestration` client API. A suspended orchestration will stop processing new events, but will continue to buffer any that happen to arrive until resumed, ensuring that no data is lost. An orchestration can also be terminated using the `terminate_orchestration` client API. Terminated orchestrations will stop processing new events and will discard any buffered events.
 
-### Retry policies (TODO)
+### Retry policies
 
 Orchestrations can specify retry policies for activities and sub-orchestrations. These policies control how many times and how frequently an activity or sub-orchestration will be retried in the event of a transient error.

docs/features.md

@@ -20,7 +20,7 @@ def sequence(ctx: task.OrchestrationContext, _):
     return [result1, result2, result3]
 ```
 
-You can find the full sample [here](./examples/activity_sequence.py).
+You can find the full sample [here](../examples/activity_sequence.py).
 
 ### Fan-out/fan-in
 
@@ -48,7 +48,7 @@ def orchestrator(ctx: task.OrchestrationContext, _):
     return {'work_items': work_items, 'results': results, 'total': sum(results)}
 ```
 
-You can find the full sample [here](./examples/fanout_fanin.py).
+You can find the full sample [here](../examples/fanout_fanin.py).
 
 ### Human interaction and durable timers
 
@@ -79,4 +79,4 @@ def purchase_order_workflow(ctx: task.OrchestrationContext, order: Order):
 
 As an aside, you'll also notice that the example orchestration above works with custom business objects. Support for custom business objects includes support for custom classes, custom data classes, and named tuples. Serialization and deserialization of these objects is handled automatically by the SDK.
 
-You can find the full sample [here](./examples/human_interaction.py).
+You can find the full sample [here](../examples/human_interaction.py).

docs/supported-patterns.md

@@ -1,27 +1,86 @@
-# Examples
-
-This directory contains examples of how to author durable orchestrations using the Durable Task Python SDK.
-
-## Prerequisites
-
-All the examples assume that you have a Durable Task-compatible sidecar running locally. There are two options for this:
-
-1. Install the latest version of the [Dapr CLI](https://docs.dapr.io/getting-started/install-dapr-cli/), which contains and exposes an embedded version of the Durable Task engine. The setup process (which requires Docker) will configure the workflow engine to store state in a local Redis container.
-
-2. Clone and run the [Durable Task Sidecar](https://github.com/microsoft/durabletask-go) project locally (requires Go 1.18 or higher). Orchestration state will be stored in a local sqlite database.
-
-## Running the examples
-
-With one of the sidecars running, you can simply execute any of the examples in this directory using `python3`:
-
-```sh
-python3 ./activity_sequence.py
-```
-
-In some cases, the sample may require command-line parameters or user inputs. In these cases, the sample will print out instructions on how to proceed.
-
-## List of examples
-
-- [Activity sequence](./activity_sequence.py): Orchestration that schedules three activity calls in a sequence.
-- [Fan-out/fan-in](./fanout_fanin.py): Orchestration that schedules a dynamic number of activity calls in parallel, waits for all of them to complete, and then performs an aggregation on the results.
-- [Human interaction](./human_interaction.py): Orchestration that waits for a human to approve an order before continuing.
+# Examples
+
+This directory contains examples of how to author durable orchestrations using the Durable Task Python SDK in conjunction with the Durable Task Scheduler (DTS).
+
+## Prerequisites
+If using a deployed Durable Task Scheduler:
+ - [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli)
+ - [`az durabletask` CLI extension](https://learn.microsoft.com/en-us/cli/azure/durabletask?view=azure-cli-latest)
+
+## Running the Examples
+There are two separate ways to run an example:
+
+- Using the Emulator (recommended for learning and development)
+- Using a deployed Scheduler and Taskhub in Azure 
+
+### Running with the Emulator
+We recommend using the emulator for learning and development as it's faster to set up and doesn't require any Azure resources. The emulator simulates a scheduler and taskhub, packaged into an easy-to-use Docker container.
+
+1. Install Docker: If it is not already installed.
+
+2. Pull the Docker Image for the Emulator:
+```bash
+docker pull mcr.microsoft.com/dts/dts-emulator:v0.0.6
+```
+
+3. Run the Emulator: Wait a few seconds for the container to be ready.
+```bash
+docker run --name dtsemulator -d -p 8080:8080 mcr.microsoft.com/dts/dts-emulator:v0.0.6
+```
+
+4. Install the Required Packages:
+```bash
+pip install -r requirements.txt
+```
+
+Note: The example code has been updated to use the default emulator settings automatically (endpoint: http://localhost:8080, taskhub: default). You don't need to set any environment variables.
+
+### Running with a Deployed Scheduler and Taskhub Resource in Azure
+For production scenarios or when you're ready to deploy to Azure, you can create a taskhub using the Azure CLI:
+
+1. Create a Scheduler:
+```bash
+az durabletask scheduler create --resource-group <testrg> --name <testscheduler> --location <eastus> --ip-allowlist "[0.0.0.0/0]" --sku-capacity 1 --sku-name "Dedicated" --tags "{'myattribute':'myvalue'}"
+```
+
+2. Create Your Taskhub:
+```bash
+az durabletask taskhub create --resource-group <testrg> --scheduler-name <testscheduler> --name <testtaskhub>
+```
+
+3. Retrieve the Endpoint for the Scheduler: Locate the taskhub in the Azure portal to find the endpoint.
+
+4. Set the Environment Variables:
+Bash:
+```bash
+export TASKHUB=<taskhubname>
+export ENDPOINT=<taskhubEndpoint>
+```
+Powershell:
+```powershell
+$env:TASKHUB = "<taskhubname>"
+$env:ENDPOINT = "<taskhubEndpoint>"
+```
+
+5. Install the Required Packages:
+```bash
+pip install -r requirements.txt
+```
+
+### Running the Examples
+You can now execute any of the examples in this directory using Python:
+
+```bash
+python3 example_file.py
+```
+
+### Review Orchestration History and Status in the Durable Task Scheduler Dashboard
+To access the Durable Task Scheduler Dashboard, follow these steps:
+
+- **Using the Emulator**: By default, the dashboard runs on portal 8082. Navigate to http://localhost:8082 and click on the default task hub.
+
+- **Using a Deployed Scheduler**: Navigate to the Scheduler resource. Then, go to the Task Hub subresource that you are using and click on the dashboard URL in the top right corner.
+
+```sh
+python3 activity_sequence.py
+```

examples/README.md

@@ -1,35 +1,54 @@
-"""End-to-end sample that demonstrates how to configure an orchestrator
-that calls an activity function in a sequence and prints the outputs."""
-from durabletask import client, task, worker
-
-
-def hello(ctx: task.ActivityContext, name: str) -> str:
-    """Activity function that returns a greeting"""
-    return f'Hello {name}!'
-
-
-def sequence(ctx: task.OrchestrationContext, _):
-    """Orchestrator function that calls the 'hello' activity function in a sequence"""
-    # call "hello" activity function in a sequence
-    result1 = yield ctx.call_activity(hello, input='Tokyo')
-    result2 = yield ctx.call_activity(hello, input='Seattle')
-    result3 = yield ctx.call_activity(hello, input='London')
-
-    # return an array of results
-    return [result1, result2, result3]
-
-
-# configure and start the worker
-with worker.TaskHubGrpcWorker() as w:
-    w.add_orchestrator(sequence)
-    w.add_activity(hello)
-    w.start()
-
-    # create a client, start an orchestration, and wait for it to finish
-    c = client.TaskHubGrpcClient()
-    instance_id = c.schedule_new_orchestration(sequence)
-    state = c.wait_for_orchestration_completion(instance_id, timeout=10)
-    if state and state.runtime_status == client.OrchestrationStatus.COMPLETED:
-        print(f'Orchestration completed! Result: {state.serialized_output}')
-    elif state:
-        print(f'Orchestration failed: {state.failure_details}')
+"""End-to-end sample that demonstrates how to configure an orchestrator
+that calls an activity function in a sequence and prints the outputs."""
+import os
+
+from azure.identity import DefaultAzureCredential
+
+from durabletask import client, task
+from durabletask.azuremanaged.client import DurableTaskSchedulerClient
+from durabletask.azuremanaged.worker import DurableTaskSchedulerWorker
+
+
+def hello(ctx: task.ActivityContext, name: str) -> str:
+    """Activity function that returns a greeting"""
+    return f'Hello {name}!'
+
+
+def sequence(ctx: task.OrchestrationContext, _):
+    """Orchestrator function that calls the 'hello' activity function in a sequence"""
+    # call "hello" activity function in a sequence
+    result1 = yield ctx.call_activity(hello, input='Tokyo')
+    result2 = yield ctx.call_activity(hello, input='Seattle')
+    result3 = yield ctx.call_activity(hello, input='London')
+
+    # return an array of results
+    return [result1, result2, result3]
+
+
+# Use environment variables if provided, otherwise use default emulator values
+taskhub_name = os.getenv("TASKHUB", "default")
+endpoint = os.getenv("ENDPOINT", "http://localhost:8080")
+
+print(f"Using taskhub: {taskhub_name}")
+print(f"Using endpoint: {endpoint}")
+
+# Set credential to None for emulator, or DefaultAzureCredential for Azure
+credential = None if endpoint == "http://localhost:8080" else DefaultAzureCredential()
+
+# configure and start the worker - use secure_channel=False for emulator
+secure_channel = endpoint != "http://localhost:8080"
+with DurableTaskSchedulerWorker(host_address=endpoint, secure_channel=secure_channel,
+                                taskhub=taskhub_name, token_credential=credential) as w:
+    w.add_orchestrator(sequence)
+    w.add_activity(hello)
+    w.start()
+
+    # Construct the client and run the orchestrations
+    c = DurableTaskSchedulerClient(host_address=endpoint, secure_channel=secure_channel,
+                                   taskhub=taskhub_name, token_credential=credential)
+    instance_id = c.schedule_new_orchestration(sequence)
+    state = c.wait_for_orchestration_completion(instance_id, timeout=60)
+    if state and state.runtime_status == client.OrchestrationStatus.COMPLETED:
+        print(f'Orchestration completed! Result: {state.serialized_output}')
+    elif state:
+        print(f'Orchestration failed: {state.failure_details}')