Add pyright strict type-check CI workflow

- New .github/workflows/typecheck.yml runs pyright in strict mode on
  Python 3.10 (lowest supported) across durabletask and
  durabletask-azuremanaged for PRs and pushes to main.
- Add pyrightconfig.json at repo root (strict, Python 3.10, excludes
  generated protobuf/gRPC files).
- Add pyright to dev-requirements.txt.
- Clean up 1598 strict-mode type errors across the SDK while preserving
  runtime behavior. Changes are purely additive type annotations,
  casts, and targeted `# pyright: ignore` comments scoped to
  specific rules.
- Address related typing issues:
  - #93: OrchestrationContext.create_timer now returns TimerTask
    (was CancellableTask).
  - #94: WhenAnyTask is now generic; when_any(tasks: Sequence[Task[T]])
    returns WhenAnyTask[T], so the completing child Task[T] is
    statically typed.
  - #92: Broad improvements to generic type-safety hints.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Bernd Verst

.github/workflows/typecheck.yml

@@ -0,0 +1,38 @@
+name: Type Check (pyright)
+
+on:
+  push:
+    branches:
+      - "main"
+    tags:
+      - "v*"
+      - "azuremanaged-v*"
+  pull_request:
+    branches:
+      - "main"
+
+permissions:
+  contents: read
+
+jobs:
+  pyright:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.10 (lowest supported)
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install packages and dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install -e ".[azure-blob-payloads,opentelemetry]"
+          pip install -e ./durabletask-azuremanaged
+          pip install pyright
+
+      - name: Run pyright (strict, Python 3.10)
+        run: pyright

CHANGELOG.md

@@ -17,6 +17,17 @@ ADDED
   resiliency-aware teardown introduced in v1.5.0 (in-flight recreate
   thread join, retired-channel timer cancellation, and SDK-owned channel
   cleanup) runs unchanged through the new `with` path.
+- Added a pyright type-check CI workflow that runs on pull requests and pushes
+  to `main`, using strict mode against the lowest supported Python version
+  (3.10) across both `durabletask` and `durabletask-azuremanaged` packages.
+- Improved type coverage across the public API. `OrchestrationContext.create_timer`
+  now returns the specific `TimerTask` type (previously `CancellableTask`)
+  ([#93](https://github.com/microsoft/durabletask-python/issues/93)), and
+  `WhenAnyTask` is now generic with `when_any(tasks: Sequence[Task[T]]) -> WhenAnyTask[T]`
+  for better static type inference of the completing child task
+  ([#94](https://github.com/microsoft/durabletask-python/issues/94)).
+  These changes also broadly improve generic type-safety hints throughout the
+  SDK ([#92](https://github.com/microsoft/durabletask-python/issues/92)).
 
 ## v1.5.0
 

dev-requirements.txt

@@ -1,2 +1,3 @@
 grpcio-tools
 pymarkdownlnt
+pyright

durabletask-azuremanaged/CHANGELOG.md

@@ -7,6 +7,12 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
 
+- Improved type coverage benefits Azure Managed users: `create_timer` now
+  returns the specific `TimerTask` type and `when_any` is generic so the
+  completing child task is type-checked through `DurableTaskSchedulerClient`,
+  `AsyncDurableTaskSchedulerClient`, and `DurableTaskSchedulerWorker` derived
+  orchestrations.
+
 ## v1.5.0
 
 - Updates base dependency to durabletask v1.5.0

durabletask-azuremanaged/durabletask/azuremanaged/internal/durabletask_grpc_interceptor.py

@@ -14,8 +14,6 @@
 from durabletask.internal.grpc_interceptor import (
     DefaultAsyncClientInterceptorImpl,
     DefaultClientInterceptorImpl,
-    _AsyncClientCallDetails,
-    _ClientCallDetails,
 )
 
 
@@ -62,7 +60,7 @@ def _upsert_authorization_header(self, token: str) -> None:
             self._metadata.append(("authorization", f"Bearer {token}"))
 
     def _intercept_call(
-            self, client_call_details: _ClientCallDetails) -> grpc.ClientCallDetails:
+            self, client_call_details: grpc.ClientCallDetails) -> grpc.ClientCallDetails:
         """Internal intercept_call implementation which adds metadata to grpc metadata in the RPC
             call details."""
         # Refresh the auth token if a credential was provided. The call to
@@ -114,7 +112,7 @@ def _upsert_authorization_header(self, token: str) -> None:
             self._metadata.append(("authorization", f"Bearer {token}"))
 
     async def _intercept_call(
-            self, client_call_details: _AsyncClientCallDetails) -> grpc.aio.ClientCallDetails:
+            self, client_call_details: grpc.aio.ClientCallDetails) -> grpc.aio.ClientCallDetails:
         """Internal intercept_call implementation which adds metadata to grpc metadata in the RPC
             call details."""
         # Refresh the auth token if a credential was provided. The call to

durabletask/client.py

@@ -6,13 +6,15 @@
 import threading
 import time
 import uuid
+from collections.abc import AsyncIterable, Iterable
 from dataclasses import dataclass
 from datetime import datetime
 from enum import Enum
-from typing import Any, Generic, Sequence, TypeVar
+from typing import Any, Generic, Protocol, Sequence, TypeVar, cast
 
 import grpc
 import grpc.aio
+from google.protobuf import wrappers_pb2
 
 import durabletask.history as history
 from durabletask.entities import EntityInstanceId
@@ -64,8 +66,8 @@ class OrchestrationStatus(Enum):
     PENDING = pb.ORCHESTRATION_STATUS_PENDING
     SUSPENDED = pb.ORCHESTRATION_STATUS_SUSPENDED
 
-    def __str__(self):
-        return helpers.get_orchestration_status_str(self.value)
+    def __str__(self) -> str:
+        return cast(str, helpers.get_orchestration_status_str(self.value))
 
 
 @dataclass
@@ -173,6 +175,128 @@ def parse_orchestration_state(state: pb.OrchestrationState) -> OrchestrationStat
 _RETIRED_CHANNEL_CLOSE_DELAY_SECONDS = 30.0
 
 
+class _SyncTaskHubSidecarServiceStub(Protocol):
+    def StartInstance(self, request: pb.CreateInstanceRequest) -> pb.CreateInstanceResponse:
+        ...
+
+    def GetInstance(self, request: pb.GetInstanceRequest) -> pb.GetInstanceResponse:
+        ...
+
+    def StreamInstanceHistory(self, request: pb.StreamInstanceHistoryRequest) -> Iterable[pb.HistoryChunk]:
+        ...
+
+    def ListInstanceIds(self, request: pb.ListInstanceIdsRequest) -> pb.ListInstanceIdsResponse:
+        ...
+
+    def QueryInstances(self, request: pb.QueryInstancesRequest) -> pb.QueryInstancesResponse:
+        ...
+
+    def WaitForInstanceStart(
+            self,
+            request: pb.GetInstanceRequest,
+            *,
+            timeout: float | None = None) -> pb.GetInstanceResponse:
+        ...
+
+    def WaitForInstanceCompletion(
+            self,
+            request: pb.GetInstanceRequest,
+            *,
+            timeout: float | None = None) -> pb.GetInstanceResponse:
+        ...
+
+    def RaiseEvent(self, request: pb.RaiseEventRequest) -> pb.RaiseEventResponse:
+        ...
+
+    def TerminateInstance(self, request: pb.TerminateRequest) -> pb.TerminateResponse:
+        ...
+
+    def SuspendInstance(self, request: pb.SuspendRequest) -> pb.SuspendResponse:
+        ...
+
+    def ResumeInstance(self, request: pb.ResumeRequest) -> pb.ResumeResponse:
+        ...
+
+    def RestartInstance(self, request: pb.RestartInstanceRequest) -> pb.RestartInstanceResponse:
+        ...
+
+    def PurgeInstances(self, request: pb.PurgeInstancesRequest) -> pb.PurgeInstancesResponse:
+        ...
+
+    def SignalEntity(self, request: pb.SignalEntityRequest) -> pb.SignalEntityResponse:
+        ...
+
+    def GetEntity(self, request: pb.GetEntityRequest) -> pb.GetEntityResponse:
+        ...
+
+    def QueryEntities(self, request: pb.QueryEntitiesRequest) -> pb.QueryEntitiesResponse:
+        ...
+
+    def CleanEntityStorage(self, request: pb.CleanEntityStorageRequest) -> pb.CleanEntityStorageResponse:
+        ...
+
+
+class _AsyncTaskHubSidecarServiceStub(Protocol):
+    async def StartInstance(self, request: pb.CreateInstanceRequest) -> pb.CreateInstanceResponse:
+        ...
+
+    async def GetInstance(self, request: pb.GetInstanceRequest) -> pb.GetInstanceResponse:
+        ...
+
+    def StreamInstanceHistory(self, request: pb.StreamInstanceHistoryRequest) -> AsyncIterable[pb.HistoryChunk]:
+        ...
+
+    async def ListInstanceIds(self, request: pb.ListInstanceIdsRequest) -> pb.ListInstanceIdsResponse:
+        ...
+
+    async def QueryInstances(self, request: pb.QueryInstancesRequest) -> pb.QueryInstancesResponse:
+        ...
+
+    async def WaitForInstanceStart(
+            self,
+            request: pb.GetInstanceRequest,
+            *,
+            timeout: float | None = None) -> pb.GetInstanceResponse:
+        ...
+
+    async def WaitForInstanceCompletion(
+            self,
+            request: pb.GetInstanceRequest,
+            *,
+            timeout: float | None = None) -> pb.GetInstanceResponse:
+        ...
+
+    async def RaiseEvent(self, request: pb.RaiseEventRequest) -> pb.RaiseEventResponse:
+        ...
+
+    async def TerminateInstance(self, request: pb.TerminateRequest) -> pb.TerminateResponse:
+        ...
+
+    async def SuspendInstance(self, request: pb.SuspendRequest) -> pb.SuspendResponse:
+        ...
+
+    async def ResumeInstance(self, request: pb.ResumeRequest) -> pb.ResumeResponse:
+        ...
+
+    async def RestartInstance(self, request: pb.RestartInstanceRequest) -> pb.RestartInstanceResponse:
+        ...
+
+    async def PurgeInstances(self, request: pb.PurgeInstancesRequest) -> pb.PurgeInstancesResponse:
+        ...
+
+    async def SignalEntity(self, request: pb.SignalEntityRequest) -> pb.SignalEntityResponse:
+        ...
+
+    async def GetEntity(self, request: pb.GetEntityRequest) -> pb.GetEntityResponse:
+        ...
+
+    async def QueryEntities(self, request: pb.QueryEntitiesRequest) -> pb.QueryEntitiesResponse:
+        ...
+
+    async def CleanEntityStorage(self, request: pb.CleanEntityStorageRequest) -> pb.CleanEntityStorageResponse:
+        ...
+
+
 class TaskHubGrpcClient:
     def __init__(self, *,
                  host_address: str | None = None,
@@ -245,7 +369,7 @@ def __init__(self, *,
         # observable effect. Callers wanting resiliency on a custom channel
         # can prepend the interceptor themselves via grpc.intercept_channel.
         self._channel = channel
-        self._stub = stubs.TaskHubSidecarServiceStub(channel)
+        self._stub = cast(_SyncTaskHubSidecarServiceStub, stubs.TaskHubSidecarServiceStub(channel))
         self._logger = shared.get_logger("client", log_handler, log_formatter)
         self.default_version = default_version
         self._payload_store = payload_store
@@ -322,7 +446,7 @@ def _maybe_recreate_channel(self) -> None:
                 interceptors=self._interceptors,
                 channel_options=self._channel_options,
             )
-            self._stub = stubs.TaskHubSidecarServiceStub(self._channel)
+            self._stub = cast(_SyncTaskHubSidecarServiceStub, stubs.TaskHubSidecarServiceStub(self._channel))
             self._last_recreate_time = now
             self._client_failure_tracker.record_success()
             close_timer = threading.Timer(
@@ -459,11 +583,11 @@ def get_all_orchestration_states(self,
                                      ) -> list[OrchestrationState]:
         if orchestration_query is None:
             orchestration_query = OrchestrationQuery()
-        _continuation_token = None
+        _continuation_token: wrappers_pb2.StringValue | None = None
 
         self._logger.info(f"Querying orchestration instances with query: {orchestration_query}")
 
-        states = []
+        states: list[OrchestrationState] = []
 
         while True:
             req = build_query_instances_req(orchestration_query, _continuation_token)
@@ -621,11 +745,11 @@ def get_all_entities(self,
                          entity_query: EntityQuery | None = None) -> list[EntityMetadata]:
         if entity_query is None:
             entity_query = EntityQuery()
-        _continuation_token = None
+        _continuation_token: wrappers_pb2.StringValue | None = None
 
         self._logger.info(f"Retrieving entities by filter: {entity_query}")
 
-        entities = []
+        entities: list[EntityMetadata] = []
 
         while True:
             query_request = build_query_entities_req(entity_query, _continuation_token)
@@ -647,7 +771,7 @@ def clean_entity_storage(self,
 
         empty_entities_removed = 0
         orphaned_locks_released = 0
-        _continuation_token = None
+        _continuation_token: wrappers_pb2.StringValue | None = None
 
         while True:
             req = pb.CleanEntityStorageRequest(
@@ -741,7 +865,7 @@ def __init__(self, *,
         # leave the failure-tracking opt-out implicit: callers wanting full
         # resiliency should let us create the channel.
         self._channel = channel
-        self._stub = stubs.TaskHubSidecarServiceStub(channel)
+        self._stub = cast(_AsyncTaskHubSidecarServiceStub, stubs.TaskHubSidecarServiceStub(channel))
         self._logger = shared.get_logger("async_client", log_handler, log_formatter)
         self.default_version = default_version
         self._payload_store = payload_store
@@ -839,7 +963,7 @@ async def _maybe_recreate_channel(self) -> None:
                 interceptors=self._interceptors,
                 channel_options=self._channel_options,
             )
-            self._stub = stubs.TaskHubSidecarServiceStub(self._channel)
+            self._stub = cast(_AsyncTaskHubSidecarServiceStub, stubs.TaskHubSidecarServiceStub(self._channel))
             self._last_recreate_time = now
             self._client_failure_tracker.record_success()
             self._retired_channels.append(old_channel)
@@ -940,11 +1064,11 @@ async def get_all_orchestration_states(self,
                                            ) -> list[OrchestrationState]:
         if orchestration_query is None:
             orchestration_query = OrchestrationQuery()
-        _continuation_token = None
+        _continuation_token: wrappers_pb2.StringValue | None = None
 
         self._logger.info(f"Querying orchestration instances with query: {orchestration_query}")
 
-        states = []
+        states: list[OrchestrationState] = []
 
         while True:
             req = build_query_instances_req(orchestration_query, _continuation_token)
@@ -1101,11 +1225,11 @@ async def get_all_entities(self,
                                entity_query: EntityQuery | None = None) -> list[EntityMetadata]:
         if entity_query is None:
             entity_query = EntityQuery()
-        _continuation_token = None
+        _continuation_token: wrappers_pb2.StringValue | None = None
 
         self._logger.info(f"Retrieving entities by filter: {entity_query}")
 
-        entities = []
+        entities: list[EntityMetadata] = []
 
         while True:
             query_request = build_query_entities_req(entity_query, _continuation_token)
@@ -1127,7 +1251,7 @@ async def clean_entity_storage(self,
 
         empty_entities_removed = 0
         orphaned_locks_released = 0
-        _continuation_token = None
+        _continuation_token: wrappers_pb2.StringValue | None = None
 
         while True:
             req = pb.CleanEntityStorageRequest(

durabletask/entities/entity_context.py

@@ -71,7 +71,7 @@ def get_state(self, intended_type: type[TState] | None = None, default: TState |
         """
         return self._state.get_state(intended_type, default)
 
-    def set_state(self, new_state: Any):
+    def set_state(self, new_state: Any) -> None:
         """Set the state of the entity to a new value.
 
         Parameters
@@ -93,7 +93,7 @@ def signal_entity(self, entity_instance_id: EntityInstanceId, operation: str, in
         input : Any, optional
             The input to provide to the entity for the operation.
         """
-        encoded_input = shared.to_json(input) if input is not None else None
+        encoded_input: str | None = shared.to_json(input) if input is not None else None
         self._state.add_operation_action(
             pb.OperationAction(
                 sendSignal=pb.SendSignalAction(
@@ -124,7 +124,7 @@ def schedule_new_orchestration(self, orchestration_name: str, input: Any | None
         str
             The instance ID of the scheduled orchestration.
         """
-        encoded_input = shared.to_json(input) if input is not None else None
+        encoded_input: str | None = shared.to_json(input) if input is not None else None
         if not instance_id:
             instance_id = uuid.uuid4().hex
         self._state.add_operation_action(