Add pyright strict type-check CI workflow

[berndverst]

Summary

Adds a new CI workflow that runs pyright in strict mode on the lowest
supported Python version (3.10) across both durabletask and
durabletask-azuremanaged packages, and cleans up every strict-mode type
error so the workflow starts at a green baseline. The cleanup also resolves
three related typing issues — #92, #93, and #94.

Note

All changes are purely additive: type annotations, cast(...) from
typing, and rule-specific # pyright: ignore[...] comments. No
runtime behavior is intentionally changed.

What changed

New CI workflow + config

• .github/workflows/typecheck.yml — runs on pushes to main and PRs to
  main (matches the existing durabletask.yml / durabletask-azuremanaged.yml
  triggers). Installs both packages with [azure-blob-payloads,opentelemetry]
  extras + the azuremanaged provider, then runs pyright.
• pyrightconfig.json at repo root — typeCheckingMode: strict,
  pythonVersion: 3.10. Excludes generated *_pb2.py, *_pb2.pyi,
  *_pb2_grpc.py, *_pb2_grpc.pyi, and local .venv* folders.
• pyright added to dev-requirements.txt.

Type-error cleanup

Started at 1,598 strict-mode errors and brought the repo to
0 errors, 0 warnings, 0 informations. The biggest categories cleaned:

File	Errors fixed
durabletask/worker.py	610
durabletask/history.py	261
durabletask/client.py	203
durabletask/testing/in_memory_backend.py	179
durabletask/internal/grpc_interceptor.py	82
durabletask/task.py	45
durabletask/extensions/azure_blob_payloads/blob_payload_store.py	44
17 other files (small fixes)	~174

Related typing issues

• create_timer should return specific TimerTask #93 — create_timer should return specific TimerTask.
  OrchestrationContext.create_timer(...) now returns TimerTask (was
  CancellableTask). The concrete _RuntimeOrchestrationContext override
  in worker.py and the in-memory backend override in testing/in_memory_backend.py
  match the new signature.

• when_any should specify type for input tasks #94 — when_any should specify type for input tasks.
  WhenAnyTask is now generic:

  class WhenAnyTask(CompositeTask[Task[T]], Generic[T]): ...
  
  def when_any(tasks: Sequence[Task[T]]) -> WhenAnyTask[T]: ...

  Calling when_any([t1, t2]) now infers WhenAnyTask[T] and
  .get_result() returns Task[T] instead of Task[Unknown].

• Add generic type safety hints #92 — Generic type-safety hints (umbrella). Broad fan-out from the
  workflow cleanup: registries use Orchestrator[Any, Any] / Activity[Any, Any] /
  Entity[Any, Any] instead of bare aliases, CompositeTask._tasks is
  list[Task[Any]], _parent: CompositeTask[Any] | None,
  RetryableTask is generic, wait_for_external_event(name) -> CancellableTask[Any],
  etc.

Notable design notes

• Optional opentelemetry imports (durabletask/internal/tracing.py) —
  reworked the lazy-import block to use a TYPE_CHECKING declaration as the
  source of truth, paired with a runtime try/except ImportError that
  rebinds the names. The except branch injects fallback stubs via
  globals() to avoid type-incompatible reassignment errors.
• ReplaySafeLogger — logging.LoggerAdapter is generic in stubs but
  not subscriptable at runtime before Python 3.11. Used the standard
  TYPE_CHECKING alias trick to satisfy both pyright and runtime.
• Private-usage policy — followed the project guidance: prefer renaming
  internal members to non-underscore names, otherwise use targeted
  # pyright: ignore[reportPrivateUsage]. For the
  durabletask-azuremanaged interceptor, eliminated dependence on the
  private _ClientCallDetails namedtuples and updated overrides to use
  the public grpc.ClientCallDetails / grpc.aio.ClientCallDetails
  (also fixes a Liskov-substitution violation).

Verification

• ✅ pyright — 0 errors, 0 warnings, 0 informations (validated with
  the exact install commands the new workflow runs).
• ✅ flake8 — clean across durabletask/, durabletask-azuremanaged/,
  examples/, tests/durabletask/, tests/durabletask-azuremanaged/.
• ✅ pymarkdownlnt — clean for both CHANGELOG.md files.
• ✅ Unit tests — 362 passed, 11 skipped (pytest tests/durabletask/ -m "not dts").
• ✅ Runtime imports — every modified module imports successfully.

Note

Some *_e2e.py tests fail locally on Windows with Failed to bind to address [::]:50060. This reproduces on main without these changes
(verified via a temporary checkout), so it is pre-existing and
unrelated to this PR.

Changelogs

• CHANGELOG.md — new workflow + type-coverage improvements with explicit
  callouts to Add generic type safety hints #92, create_timer should return specific TimerTask #93, when_any should specify type for input tasks #94.
• durabletask-azuremanaged/CHANGELOG.md — derived-benefit note (the
  TimerTask and generic when_any changes flow through to
  DurableTaskSchedulerWorker orchestrations).

Stats

27 files changed, 827 insertions(+), 459 deletions(-)

Closes #92
Closes #93
Closes #94

[Copilot]

Pull request overview

This PR introduces strict static type-checking to the Durable Task Python SDK by adding a dedicated pyright (strict mode) CI workflow and updating the codebase across both durabletask and durabletask-azuremanaged to reach a clean strict-type baseline (also addressing typing issues #92, #93, #94).

Changes:

• Added pyright strict configuration (pyrightconfig.json) and a new GitHub Actions workflow (.github/workflows/typecheck.yml) that runs on Python 3.10.
• Improved public API type precision (notably OrchestrationContext.create_timer() -> TimerTask and generic when_any() / WhenAnyTask typing).
• Performed broad strict-mode typing cleanup across core runtime, testing backend, gRPC utilities, tracing, and Azure Blob payload store.

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
pyrightconfig.json	Adds repo-wide pyright strict configuration and exclusions for generated files/venvs.
.github/workflows/typecheck.yml	New CI job to run pyright strict on Python 3.10 for both packages.
dev-requirements.txt	Adds pyright to dev dependencies.
CHANGELOG.md	Documents the new typecheck workflow and public typing improvements (#92/#93/#94).
durabletask-azuremanaged/CHANGELOG.md	Notes downstream typing improvements for Azure Managed consumers.
durabletask/task.py	Updates task/orchestration typing, including create_timer return type and generic when_any.
durabletask/worker.py	Large strict-typing pass across worker runtime and orchestration execution internals.
durabletask/client.py	Tightens typing around stubs/continuation tokens and adds typed stub Protocols.
durabletask/history.py	Improves typing for event conversion utilities and serialization helpers.
durabletask/testing/in_memory_backend.py	Adds strict typing across backend state, filters, and service method signatures.
durabletask/grpc_options.py	Typing adjustments for channel/retry options dataclasses.
durabletask/internal/grpc_interceptor.py	Reworks interceptor call-details typing and metadata typing for strict mode.
durabletask/internal/grpc_resiliency.py	Adds strict typing to sync/async resiliency interceptors.
durabletask/internal/tracing.py	Refactors optional OpenTelemetry imports to be strict-type-safe while remaining optional at runtime.
durabletask/extensions/azure_blob_payloads/blob_payload_store.py	Adds strict typing and explicit client types for sync/async blob clients.
durabletask/extensions/azure_blob_payloads/__init__.py	Adjusts optional import typing to satisfy strict checks.
durabletask/payload/helpers.py	Adds strict typing for protobuf descriptor helpers.
durabletask/internal/shared.py	Adds typing to JSON encode/decode helpers and encoder/decoder overrides.
durabletask/internal/helpers.py	Broadens is_empty typing to accept None.
durabletask/internal/history_helpers.py	Adds typing for history conversion helpers and private-usage annotations.
durabletask/internal/orchestration_entity_context.py	Adds typing for entity-context helpers and generator return types.
durabletask/internal/entity_state_shim.py	Adds typing for entity state shim methods.
durabletask/internal/client_helpers.py	Adds typing for continuation tokens and related helpers.
durabletask/entities/entity_context.py	Adds missing return typing and clarifies encoded payload types.
durabletask/entities/entity_lock.py	Adds targeted pyright ignore for intentional private call.
durabletask/entities/entity_instance_id.py	Tightens comparison method typing and corrects non-instance comparisons.
durabletask-azuremanaged/durabletask/azuremanaged/internal/durabletask_grpc_interceptor.py	Removes dependency on internal call-details types; uses public grpc call-details interfaces.

[andystaples]

Versioning + CHANGELOG considerations for 1.5.0

Reviewed this through a "what breaks for customers?" lens. Runtime behavior is preserved for typical users (clients, activity/orchestrator authors), but a handful of changes are breaking for anyone who subclasses our public abstract types or runs strict pyright/mypy against their own code. Since the package ships py.typed and the CHANGELOG declares SemVer adherence, these deserve an explicit call-out — but I don't think they require a major bump.

Type-level breaking changes to surface in CHANGELOG

These don't change runtime, but py.typed consumers will see type-check errors:

1. OrchestrationContext.create_timer return type narrowed CancellableTask → TimerTask (closes create_timer should return specific TimerTask #93). Subclassers must update their override return type.
2. OrchestrationContext.wait_for_external_event return type is now CancellableTask[Any] (was bare CancellableTask).
3. WhenAnyTask is generic; when_any(tasks: list[Task]) -> WhenAnyTask → when_any(tasks: Sequence[Task[T]]) -> WhenAnyTask[T] (closes when_any should specify type for input tasks #94). Anyone subclassing WhenAnyTask/CompositeTask and overriding __init__ / on_child_completed with the old non-generic signatures will hit LSP errors.
4. CompositeTask.on_child_completed parameter is now Task[Any] (was Task[T]); _tasks is list[Task[Any]].
5. TaskHubGrpcWorker.add_activity / .add_entity (and _Registry.add_entity / add_named_entity / get_entity) now require task.Activity[Any, Any] / task.Entity[Any, Any] instead of the bare aliases.
6. OrchestrationContext.call_entity / signal_entity input parameter widened from TInput | None → Any. (Liskov-safe for callers, but subclass overrides with the old narrower type will be flagged.)
7. DefaultClientInterceptorImpl._intercept_call / DefaultAsyncClientInterceptorImpl._intercept_call now take grpc.ClientCallDetails / grpc.aio.ClientCallDetails instead of the private _ClientCallDetails / _AsyncClientCallDetails. This is the Liskov fix already noted in the description, but it's worth flagging in the durabletask-azuremanaged CHANGELOG too since the same pattern affects any custom auth interceptor downstream consumers may have built.

Runtime behavior changes worth documenting

These are small but observable:

8. when_any now copies its input (return WhenAnyTask(list(tasks))). Previously WhenAnyTask._tasks aliased the caller's list, so mutations after construction were visible inside the task. New behavior is almost certainly desirable, but it's a silent semantic change not in the PR description today — worth one line in CHANGELOG.
9. durabletask/internal/tracing.py when opentelemetry is not installed: otel_context, trace, and TraceContextTextMapPropagator are now bound to None via globals() injection (previously the names simply didn't exist). External code that did from durabletask.internal.tracing import trace without checking OTEL_AVAILABLE will now succeed-then-fail-on-use (AttributeError: 'NoneType' object has no attribute ...) instead of failing at import time. Unlikely to affect anyone since the module is internal, but worth a comment in the file.
10. EntityInstanceId.__lt__ now returns NotImplemented for non-EntityInstanceId operands instead of return self < other (which infinitely recursed). Genuine bug fix; mixed-type comparisons now TypeError cleanly. Worth a "Fixed" line.
11. InternalJSONEncoder.encode / .default parameter renamed from obj → o to match stdlib. Internal class, very low risk, but technically breaks anyone calling with the keyword form encode(obj=...).

Suggested CHANGELOG structure for 1.5.0

## 1.5.0

### ⚠️ Type-level breaking changes (no runtime impact for typical users)
- `OrchestrationContext.create_timer` now returns `TimerTask` (was `CancellableTask`)
- `WhenAnyTask` is now generic; `when_any` returns `WhenAnyTask[T]`
- `CompositeTask.on_child_completed` now takes `Task[Any]`
- `TaskHubGrpcWorker.add_activity` / `add_entity` now require `Activity[Any, Any]` / `Entity[Any, Any]`
- `DefaultClientInterceptorImpl._intercept_call` now takes `grpc.ClientCallDetails`
  (subclassers should retype their override parameter)
- Closes #92, #93, #94

### Changed
- `when_any` now copies its input list; mutations after construction no longer affect the task
- `EntityInstanceId.__lt__` returns `NotImplemented` for non-matching types (was infinite recursion)
- Added pyright strict-mode CI on Python 3.10

### Fixed
- Type-check 0 errors across the repo under pyright strict

Recommendation

1.5.0 (minor) is appropriate provided the CHANGELOG has the explicit breaking-changes header above (not buried under generic "Changed"). A 2.0 would be the strict-SemVer-plus-py.typed call, but in practice no runtime API surface changes for normal usage, and a major bump would over-signal the impact.

[berndverst]

Thanks for the thorough versioning/CHANGELOG review — addressed in 1dc27cb.

• Moved all ## Unreleased entries into the v1.5.0 sections of both CHANGELOG.md and durabletask-azuremanaged/CHANGELOG.md.
• Added an explicit "BREAKING CHANGES (type-level only — no runtime impact for typical users)" section to v1.5.0, calling out: create_timer → TimerTask, wait_for_external_event → CancellableTask[Any], generic WhenAnyTask/when_any, CompositeTask.on_child_completed → Task[Any], add_activity/add_entity requiring Activity[Any, Any]/Entity[Any, Any], call_entity/signal_entity input widened to Any, and the public grpc.ClientCallDetails interceptor types (closes Add generic type safety hints #92/create_timer should return specific TimerTask #93/when_any should specify type for input tasks #94).
• Documented the runtime-observable changes you flagged: when_any now copies its input list (CHANGED), and the EntityInstanceId.__lt__ recursion fix → NotImplemented (FIXED).
• Flagged the interceptor ClientCallDetails retype in the durabletask-azuremanaged CHANGELOG too, since custom DTS auth interceptors built on DTSDefaultClientInterceptorImpl are affected.
• Removed the CI type-check workflow CHANGELOG entry — CI changes aren't user-facing, so per our changelog policy they don't belong there.

I left the internal-only items out of the CHANGELOG (the tracing.py None-binding and the InternalJSONEncoder obj→o rename), since those modules/classes are internal and, as you noted, very low risk. Agree that 1.5.0 (minor) is the right call given no runtime API surface changes for normal usage.