`grpcio`: Interceptor base classes are incompatible with mypy `--disallow-any-generics` or `--strict` options

[bkeryan]

The grpcio package provides interceptor base classes (ServerInterceptor, UnaryUnaryClientInterceptor, etc.) that clients can subclass in order to intercept calls made by a gRPC client or server. However, the grpcio package and typeshed disagree about whether they are generic, which makes it difficult to use them with mypy's --disallow-any-generics or --strict options without type: ignore comments.

• In grpc/grpc the interceptor classes are ABCs but not generics, and they do not implement __class_getitem__, so they cannot be subscripted at run time. The interceptor example subclasses the interceptor base classes without subscripting.
• In typeshed the interceptor classes are ABCs and generics. If you use --disallow-any-generics or --strict, you will get a [type-arg] error if you subclass an interceptor base class without subscripting.

I also reported this to grpc/grpc as grpc/grpc#40550

Example 1 (no subscripting):

from __future__ import annotations
import grpc
import typing

class MyClientInterceptor(grpc.UnaryUnaryClientInterceptor):
    def intercept_unary_unary(
        self,
        continuation: typing.Callable[[grpc.ClientCallDetails, grpc._TRequest], grpc._CallFuture[grpc._TResponse]],
        client_call_details: grpc.ClientCallDetails,
        request: grpc._TRequest
    ) -> grpc._CallFuture[grpc._TResponse]:
        return continuation(client_call_details, request)

$ python test.py
$ mypy --disallow-any-generics test.py
test.py:5: error: Missing type parameters for generic type "UnaryUnaryClientInterceptor"  [type-arg]
Found 1 error in 1 file (checked 1 source file)
$ mypy --strict test.py
test.py:5: error: Missing type parameters for generic type "UnaryUnaryClientInterceptor"  [type-arg]
Found 1 error in 1 file (checked 1 source file)

Example 2 (subscripting):

from __future__ import annotations
import grpc
import typing

TRequest = typing.TypeVar("TRequest")
TResponse = typing.TypeVar("TResponse")

class MyClientInterceptor(
    typing.Generic[TRequest, TResponse],
    grpc.UnaryUnaryClientInterceptor[TRequest, TResponse]
):
    def intercept_unary_unary(
        self,
        continuation: typing.Callable[[grpc.ClientCallDetails, TRequest], grpc._CallFuture[TResponse]],
        client_call_details: grpc.ClientCallDetails,
        request: TRequest
    ) -> grpc._CallFuture[TResponse]:
        return continuation(client_call_details, request)

$ python test2.py
Traceback (most recent call last):
  File "test2.py", line 10, in <module>
    grpc.UnaryUnaryClientInterceptor[TRequest, TResponse]
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^
TypeError: type 'UnaryUnaryClientInterceptor' is not subscriptable
$ mypy --disallow-any-generics test2.py
Success: no issues found in 1 source file
$ mypy --strict test2.py
Success: no issues found in 1 source file

Versions used:

• Python 3.11.9 on Windows x64
• Packages

Package           Version
----------------- --------------
grpcio            1.74.0
mypy              1.17.1
mypy_extensions   1.1.0
pathspec          0.12.1
pip               24.0
setuptools        65.5.0
types-grpcio      1.0.0.20250703
typing_extensions 4.15.0

[brianschubert]

Possibly the stubs could specify some defaults for the type variables (perhaps just Any is there's nothing more meaningful), which would silence mypy's diagnostic.

In the meantime, you can also try the workaround from https://mypy.readthedocs.io/en/stable/runtime_troubles.html#using-classes-that-are-generic-in-stubs-but-not-at-runtime

[bkeryan]

@brianschubert Thanks for linking to the section of the mypy docs covering this exact situation. I overlooked that page when I was looking through the mypy docs the other day.

That workaround reminds me of a related issue: some gRPC interceptors implement or wrap the gRPC stream interfaces in order to customize the behavior of streaming calls. In Python, the gRPC stream interfaces are represented by the grpc._CallFuture[_TResponse] and grpc._CallIterator[_TResponse] ABCs, which are marked @type_check_only, so you can't subclass them at run time.

In the past, I have worked around this in a similar way to the BaseQueue example, except the else case redefines _CallFuture[_TResponse] and _CallIterator[_TResponse]: https://github.com/ni/ni-apis-python/blob/main/packages/ni-grpc-extensions/src/ni_grpc_extensions/loggers.py#L399

if TYPE_CHECKING:
    # These types are marked as @type_check_only and can be used only in type annotations,
    # so we redefine them as empty classes at run time. Pyright still warns due to the behavior
    # described in https://github.com/microsoft/pyright/issues/9934
    _CallFuture = grpc._CallFuture  # pyright: ignore[reportGeneralTypeIssues]
    _CallIterator = grpc._CallIterator  # pyright: ignore[reportGeneralTypeIssues]
else:

    class _CallFuture(Generic[_T]):
        pass

    class _CallIterator(Generic[_T]):
        pass

However, Pyright warns about this usage, so perhaps it's better to conditionally define a base class with a different name like in the _MyQueueBase example.

if TYPE_CHECKING:

class _BaseCallFuture(Generic[_T], grpc._CallFuture[_T]):
    pass

class _BaseCallIterator(Generic[_T], grpc._CallIterator[_T]):
    pass

else:

class _BaseCallFuture(Generic[_T]):
    pass

class _BaseCallIterator(Generic[_T]):
    pass