Merge remote-tracking branch 'origin/main' into andystaples/add-functions-support

# Conflicts:
#	durabletask/worker.py

Author: andystaples

.github/copilot-instructions.md

@@ -36,6 +36,21 @@ Examples:
 - Follow PEP 8 conventions.
 - Use `autopep8` for Python formatting.
 
+## Copyright Headers
+
+Every new Python (`.py`) source file MUST begin with the following copyright
+header as the first two lines, followed by a blank line before any code,
+docstring, or imports:
+
+```python
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+```
+
+This applies to all hand-written Python files, including `__init__.py` files,
+tests, and examples. The only exceptions are auto-generated protobuf files
+(`*_pb2.py` and `*_pb2_grpc.py`), which carry their own generated header.
+
 ## Python Type Checking
 
 Before linting, check for and fix any Pylance errors in the files you

.github/workflows/typecheck.yml

@@ -31,8 +31,18 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           pip install -r requirements.txt
-          pip install -e ".[azure-blob-payloads,opentelemetry]"
-          pip install -e ./durabletask-azuremanaged
+          # Install third-party dependencies declared by the examples so they
+          # type-check cleanly. Each example's requirements.txt is the single
+          # source of truth for its dependencies.
+          for req in examples/requirements.txt examples/*/requirements.txt; do
+            pip install -r "$req"
+          done
+          # Install the packages under test from local source last (non-editable
+          # so the durabletask / durabletask.azuremanaged namespace packages are
+          # physically merged in site-packages, which pyright can resolve). This
+          # overrides any PyPI copy pulled in by the example requirements above.
+          pip install --force-reinstall --no-deps . ./durabletask-azuremanaged
+          pip install ".[azure-blob-payloads,opentelemetry]"
           pip install pyright
 
       - name: Run pyright (strict, Python 3.10)

CHANGELOG.md

@@ -7,6 +7,99 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
 
+## v1.7.0
+
+ADDED
+
+- Added `durabletask.scheduled`, a recurring schedule feature built on durable
+  entities. Use `worker.configure_scheduled_tasks()` to enable it on a worker,
+  then manage schedules from the client via `ScheduledTaskClient` (and the
+  per-schedule `ScheduleClient`). Supports creating, describing, listing,
+  updating, pausing, resuming, and deleting schedules with configurable
+  `interval`, `start_at`, `end_at`, and `start_immediately_if_late` options.
+- Added an optional `signal_time` parameter to `EntityContext.signal_entity`
+  and `DurableEntity.signal_entity`, allowing an entity signal to be scheduled
+  for future delivery.
+- Added an optional `signal_time` parameter to `OrchestrationContext.signal_entity`
+  and to the client `signal_entity` methods (sync and async), allowing entity
+  signals to be scheduled for future delivery from orchestrations and clients.
+- Added a pluggable `DataConverter` (`durabletask.serialization`) accepted by
+  `TaskHubGrpcWorker`, `TaskHubGrpcClient`, and `AsyncTaskHubGrpcClient` via a
+  `data_converter` argument. Every payload boundary (inputs, outputs, events,
+  custom status, entity state) routes through it, so one converter controls how
+  Python values become JSON and how they are reconstructed. The default
+  `JsonDataConverter` preserves existing behavior, so a custom converter (for
+  example one backed by pydantic) is fully opt-in.
+- Custom objects can participate in serialization by exposing a `to_json()`
+  method and a `from_json(value)` classmethod. Both are honored recursively, so
+  nested custom objects round-trip through their own hooks.
+- Payloads are reconstructed into a caller-supplied type — dataclasses
+  (including nested fields), `from_json()`-capable types, and `enum.Enum`
+  members, recursing through `list`, `dict`, `tuple`, and `Optional`/`Union`
+  hints. The type comes from a function's annotations, from an explicit
+  `return_type` on `call_activity` / `call_sub_orchestrator` / `call_entity`
+  (or `data_type` on `wait_for_external_event`), or from the typed accessors
+  `get_input()` / `get_output()` / `get_custom_status()` on
+  `client.OrchestrationState` and `EntityMetadata.get_typed_state(...)`. It is
+  never inferred from the payload. Which annotated types are eligible is decided
+  by the converter via the overridable `DataConverter.can_reconstruct(...)`; a
+  custom converter can override it to recognize its own types (for example
+  `pydantic.BaseModel` subclasses).
+
+CHANGED
+
+- Custom objects (dataclasses, `SimpleNamespace`, namedtuples) are now
+  serialized as plain JSON. Decoding such a payload *without* a type hint now
+  yields a plain `dict` (previously a `SimpleNamespace`; a namedtuple now
+  round-trips as a JSON array). To get the original type back, supply a type via
+  one of the mechanisms above. Payloads produced by older SDK versions still
+  deserialize — including into a `SimpleNamespace` when no type is supplied — so
+  in-flight orchestrations continue to replay across an upgrade.
+- JSON serialization failures now raise a `TypeError` that chains the original
+  error (`__cause__`) and names the offending type.
+- `EntityContext.get_state()` / `DurableEntity.get_state()` now return a freshly
+  reconstructed value on every call rather than a reference to a single cached
+  object. This changes v1.6.0 behavior: mutating the returned value in place no
+  longer affects persisted state — write it back with `set_state()`. State is
+  also serialized eagerly at `set_state()` time, so a non-serializable value
+  fails inside the operation (which rolls back) instead of after the batch has
+  run.
+
+FIXED
+
+- Falsy entity states (`0`, `""`, `[]`, `{}`) are no longer dropped when an
+  entity batch is persisted. Previously a falsy current state was treated as
+  "no state" and written as `None`, effectively deleting it; only an actual
+  `None` state now clears the persisted entity state.
+
+DEPRECATED
+
+- `durabletask.internal.shared.to_json` and `durabletask.internal.shared.from_json`
+  are deprecated and now emit a `DeprecationWarning`. Use a
+  `durabletask.serialization.DataConverter` (for example the default
+  `JsonDataConverter`) instead. The functions continue to work for backwards
+  compatibility.
+
+BREAKING CHANGES (no runtime impact for typical users)
+
+Most of these are type-level only: because the package ships `py.typed`,
+consumers running strict type checkers (pyright/mypy) — or subclassing the
+public abstract types — may need to update their code. The constructor change
+below also affects callers who *directly* construct the named classes, which is
+uncommon since they are normally handed to you by the SDK.
+
+- `OrchestrationContext.call_activity`, `call_sub_orchestrator`, `call_entity`,
+  and `wait_for_external_event` gained new keyword-only parameters
+  (`return_type` / `data_type`). Subclasses overriding these methods should add
+  the parameter to match the base signature.
+- `EntityContext` and `EntityMetadata` (and its `from_entity_metadata` /
+  `from_entity_response` factories) now require a `data_converter` argument.
+  These objects are normally constructed by the SDK — you receive an
+  `EntityContext` in an entity function and an `EntityMetadata` from the client —
+  so this only affects code that constructs them directly.
+
+## v1.6.0
+
 ADDED
 
 - Added overridable activity-dispatch hooks `_on_activity_execution_started`

docs/supported-patterns.md

@@ -68,7 +68,8 @@ def purchase_order_workflow(ctx: task.OrchestrationContext, order: Order):
     yield ctx.call_activity(send_approval_request, input=order)
 
     # Approvals must be received within 24 hours or they will be cancelled.
-    approval_event = ctx.wait_for_external_event("approval_received")
+    # Passing ``data_type`` reconstructs the event payload as an ``Approval``.
+    approval_event = ctx.wait_for_external_event("approval_received", data_type=Approval)
     timeout_event = ctx.create_timer(timedelta(hours=24))
     winner = yield task.when_any([approval_event, timeout_event])
     if winner == timeout_event:
@@ -81,9 +82,11 @@ 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.
+objects. Custom classes, data classes, and named tuples are serialized to plain JSON automatically.
+To reconstruct the original type on the receiving side, supply the type — for example via the
+`data_type` argument to `wait_for_external_event` (shown above), the `return_type` argument to
+`call_activity` / `call_sub_orchestrator` / `call_entity`, or by annotating the consuming function's
+input parameter. Without a type, the payload is returned as plain JSON (a `dict` or `list`).
 
 See the full [human interaction sample](../examples/human_interaction.py).
 

durabletask-azuremanaged/CHANGELOG.md

@@ -7,6 +7,19 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
 
+## v1.7.0
+
+- Updates base dependency to durabletask v1.7.0.
+
+ADDED
+
+- `DurableTaskSchedulerWorker`, `DurableTaskSchedulerClient`, and the async
+  client now accept a `data_converter` argument and forward it to the base
+  worker/client, so a custom `durabletask.serialization.DataConverter` (for
+  example a pydantic-backed one) can be used with the Durable Task Scheduler.
+
+## v1.6.0
+
 - Updates base dependency to durabletask v1.6.0.
 - Added preview support for Durable Task Scheduler on-demand sandbox
   activities under `durabletask.azuremanaged.preview.sandboxes`. Applications

durabletask-azuremanaged/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.

durabletask-azuremanaged/durabletask/azuremanaged/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.

durabletask-azuremanaged/durabletask/azuremanaged/client.py

@@ -20,6 +20,7 @@
 )
 import durabletask.internal.shared as shared
 from durabletask.payload.store import PayloadStore
+from durabletask.serialization import DataConverter
 
 
 # Client class used for Durable Task Scheduler (DTS)
@@ -35,6 +36,7 @@ def __init__(self, *,
                  resiliency_options: GrpcClientResiliencyOptions | None = None,
                  default_version: str | None = None,
                  payload_store: PayloadStore | None = None,
+                 data_converter: DataConverter | None = None,
                  log_handler: logging.Handler | None = None,
                  log_formatter: logging.Formatter | None = None):
 
@@ -59,7 +61,8 @@ def __init__(self, *,
             channel_options=channel_options,
             resiliency_options=resiliency_options,
             default_version=default_version,
-            payload_store=payload_store)
+            payload_store=payload_store,
+            data_converter=data_converter)
 
 
 # Async client class used for Durable Task Scheduler (DTS)
@@ -113,6 +116,7 @@ def __init__(self, *,
                  resiliency_options: GrpcClientResiliencyOptions | None = None,
                  default_version: str | None = None,
                  payload_store: PayloadStore | None = None,
+                 data_converter: DataConverter | None = None,
                  log_handler: logging.Handler | None = None,
                  log_formatter: logging.Formatter | None = None):
 
@@ -137,4 +141,5 @@ def __init__(self, *,
             channel_options=channel_options,
             resiliency_options=resiliency_options,
             default_version=default_version,
-            payload_store=payload_store)
+            payload_store=payload_store,
+            data_converter=data_converter)

durabletask-azuremanaged/durabletask/azuremanaged/worker.py

@@ -18,6 +18,7 @@
 )
 import durabletask.internal.shared as shared
 from durabletask.payload.store import PayloadStore
+from durabletask.serialization import DataConverter
 from durabletask.worker import ConcurrencyOptions, TaskHubGrpcWorker
 
 
@@ -81,6 +82,7 @@ def __init__(self, *,
                  resiliency_options: GrpcWorkerResiliencyOptions | None = None,
                  concurrency_options: ConcurrencyOptions | None = None,
                  payload_store: PayloadStore | None = None,
+                 data_converter: DataConverter | None = None,
                  log_handler: logging.Handler | None = None,
                  log_formatter: logging.Formatter | None = None):
 
@@ -110,5 +112,6 @@ def __init__(self, *,
             concurrency_options=concurrency_options,
             # DTS natively supports long timers so chunking is unnecessary
             maximum_timer_interval=None,
-            payload_store=payload_store
+            payload_store=payload_store,
+            data_converter=data_converter
         )

durabletask-azuremanaged/pyproject.toml

@@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "durabletask.azuremanaged"
-version = "1.6.0"
+version = "1.7.0"
 description = "Durable Task Python SDK provider implementation for the Azure Durable Task Scheduler"
 keywords = [
     "durable",
@@ -26,13 +26,13 @@ requires-python = ">=3.10"
 license = {file = "LICENSE"}
 readme = "README.md"
 dependencies = [
-    "durabletask>=1.6.0",
+    "durabletask>=1.7.0",
     "azure-identity>=1.19.0"
 ]
 
 [project.optional-dependencies]
 azure-blob-payloads = [
-    "durabletask[azure-blob-payloads]>=1.6.0"
+    "durabletask[azure-blob-payloads]>=1.7.0"
 ]
 
 [project.urls]