[Mogost]

Fixes #15495.
Closes #15497 and #16461.

Builds on the work by @XiaXia009 and @wolfgang-aura, following @srittau's guidance for a private, type-check-only _AsyncRpcMethodHandler.

Adds async overloads for all four handler factories and preserves handler types through generic registration and aio interceptor chains, including streaming handlers using context.write().

Aio interceptor continuations can return synchronous or asynchronous handlers without adapting their behavior, so their return type includes both. Fully annotated callbacks retain precise handler types. Callbacks accepting both synchronous and asynchronous inputs produce Any to avoid misclassifying ambiguous callbacks. The existing permissive factory fallbacks are retained for compatibility.

Runtime references:

• [Handler factories](https://github.com/grpc/grpc/blob/v1.84.0/src/python/grpcio/grpc/__init__.py)
• [Aio handler resolution and dispatch](https://github.com/grpc/grpc/blob/v1.84.0/src/python/grpcio/grpc/_cython/_cygrpc/aio/server.pyx.pxi)

[Copilot]

🟡 Changes recommended

Async-first overloads can misclassify dynamically typed synchronous callbacks, compromising synchronous registration compatibility.

1 open issue

• Ambiguous overloads misclassify synchronous callbacks as async · New

What changed in this PR

Extends grpcio stubs to support asynchronous handler factories and mixed synchronous/asynchronous aio interceptor chains.

Changes:

• Adds async overloads for all four handler factories.
• Preserves handler types through generic registration and expands aio handler support.
• Adds regression cases for inference, registration, and interceptor wrapping.

File	Description
stubs/​grpcio/​grpc/​aio/​__init__.pyi	Models async handlers and mixed aio registration and interception.
stubs/​grpcio/​grpc/​__init__.pyi	Adds async factory overloads and generic handler typing.
stubs/​grpcio/​@tests/​test_cases/​check_server_interceptor.py	Covers mixed-handler continuations and async wrapping.
stubs/​grpcio/​@tests/​test_cases/​check_rpc_method_handlers.py	Covers factory inference and handler registration.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Optional serializers can still cause synchronous streaming callbacks to be inferred as asynchronous handlers.

1 open issue

• Optional serializers misclassify Any-typed streaming handlers · New

1 resolved since last review

• Ambiguous overloads misclassify synchronous callbacks as async

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Factory overloads can erase synchronous handler types or misclassify asynchronous callbacks as synchronous.

No open issues 🎉

2 previously missed issues

In code that hasn't changed since last review

Serializer overload misclassifies asynchronous callbacks as synchronous

stubs/​grpcio/​grpc/​__init__.pyi:166

A non-None serializer does not always distinguish synchronous from asynchronous callbacks. Calling this factory with the test's partial_async_unary and a Callable[[object], bytes] serializer matches this first synchronous overload: the callback accepts the synchronous context through Any, and _TResponse can accommodate its coroutine return. The result is classified as RpcMethodHandler, incorrectly allowing synchronous-server registration. The positional and keyword-only overloads have this problem; stream_unary_rpc_method_handler also has it when both callback inputs are typed Any. Handle awaitable-returning ambiguity before these synchronous overloads, retaining an unknown handler type where necessary without regressing Any-returning synchronous callbacks. Add regression cases using a serializer that accepts object.

Any fallback misclassifies synchronous callbacks without codecs

stubs/​grpcio/​grpc/​__init__.pyi:173

The Any fallback also matches unambiguously synchronous callbacks. For example, a callback annotated (bytes, grpc.ServicerContext) -> bytes, passed without codecs, now returns Any instead of retaining the RpcMethodHandler interface. This disables checks on subsequent handler use. The corresponding overloads in all four factories have the same problem, including when the serializer is optional. Restrict these ambiguity overloads to callbacks accepting both context types, for example by using ServicerContext | aio.ServicerContext[_TRequest, _TResponse] for their context parameter, so synchronous-only callbacks reach the typed fallback. Add regression assertions for fully annotated synchronous callbacks without codecs.

1 resolved since last review

• Optional serializers misclassify Any-typed streaming handlers

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Overload resolution and generic registration compatibility need final human verification across supported type checkers.

No open issues 🎉

_{Review effort: Balanced}

[github-actions]

According to mypy_primer, this change has no effect on the checked open source code. 🤖🎉

[Mogost]

@srittau Could you take a look when you have time? This follows your guidance in #15497 and also covers factory inference, registration, and mixed synchronous/asynchronous aio interceptor chains.