{"id":2524,"library":"grpc-stubs","title":"gRPC Mypy Stubs","description":"grpc-stubs provides high-quality Mypy stubs for the gRPC Python library (`grpcio`). It enables static type checking for gRPC client and server code, significantly improving code reliability and maintainability. The current version is 1.53.0.6, which tracks `grpcio` releases, with updates typically coinciding with `grpcio` major versions.","status":"active","version":"1.53.0.6","language":"en","source_language":"en","source_url":"https://github.com/shabbyrobe/grpc-stubs","tags":["gRPC","type hints","mypy","stubs","static analysis"],"install":[{"cmd":"pip install grpc-stubs","lang":"bash","label":"Install grpc-stubs"}],"dependencies":[{"reason":"grpc-stubs provides type hints for this library's runtime components.","package":"grpcio","optional":false},{"reason":"Required to perform static type checking and utilize the stubs.","package":"mypy","optional":false},{"reason":"Often used for generating gRPC Python code from .proto files, though grpc-stubs focuses on the core `grpc` library.","package":"grpcio-tools","optional":true}],"imports":[{"note":"grpc-stubs provides type hints for symbols imported from the `grpcio` library (e.g., `grpc`, `grpc.aio`), allowing static analysis tools like Mypy to type-check gRPC code. It does not introduce new runtime imports from `grpc_stubs` itself.","symbol":"grpc","correct":"import grpc"},{"note":"Specifically for asynchronous gRPC code, `grpc-stubs` also provides type hints for the `grpc.aio` module.","symbol":"grpc.aio","correct":"import grpc.aio"}],"quickstart":{"code":"import grpc\n\n# In a real project, these would be generated from your .proto files by grpcio-tools:\n# from your_project import greeter_pb2 as pb2\n# from your_project import greeter_pb2_grpc as pb2_grpc\n\n# For this example, we'll use placeholder types to make it runnable.\nclass HelloRequest:\n    def __init__(self, name: str):\n        self.name = name\nclass HelloReply:\n    def __init__(self, message: str):\n        self.message = message\nclass GreeterStub:\n    # This __init__ signature and method signature are what grpc-stubs would type.\n    def __init__(self, channel: grpc.Channel):\n        self._channel = channel\n    def SayHello(self, request: HelloRequest, timeout: float = None) -> HelloReply:\n        # Simulate a network call\n        print(f\"Simulating gRPC call for: {request.name}\")\n        return HelloReply(message=f\"Hello, {request.name}!\")\n\ndef run_client():\n    # grpc-stubs provides types for the `grpc` module itself, like `insecure_channel`\n    with grpc.insecure_channel('localhost:50051') as channel:\n        # And also for generated stubs like GreeterStub\n        stub: GreeterStub = GreeterStub(channel)\n        \n        # This interaction is now type-checked by mypy thanks to grpc-stubs\n        request = HelloRequest(name=\"Mypy User\")\n        response: HelloReply = stub.SayHello(request, timeout=5.0)\n        \n        print(f\"Client received: {response.message}\")\n\n        # Example of a type error that mypy would catch:\n        # stub.SayHello(HelloRequest(name=123)) # Mypy would flag `name` as int, expected str\n\nif __name__ == '__main__':\n    run_client()\n    print(\"\\nTo enable type checking for this code:\")\n    print(\"1. Ensure you have `grpcio`, `mypy`, and `grpc-stubs` installed:\")\n    print(\"   pip install grpcio mypy grpc-stubs\")\n    print(\"2. Run mypy on your script:\")\n    print(\"   mypy your_script_name.py\")","lang":"python","description":"This quickstart demonstrates a simplified gRPC client using placeholder types to represent code typically generated by `grpcio-tools`. `grpc-stubs` provides the necessary type hints for `grpc.Channel`, generated `_grpc.py` stubs, and other `grpcio` components, enabling tools like Mypy to perform static analysis on your gRPC client and server code. To run this, install `grpcio`, `mypy`, and `grpc-stubs` and then execute `mypy your_script_name.py`."},"warnings":[{"fix":"Always install `grpc-stubs` with the same major.minor version as your `grpcio` (e.g., if `grpcio==1.53.0`, use `grpc-stubs==1.53.0.*`). Use `pip install grpcio==X.Y.Z grpc-stubs==X.Y.Z.*` to enforce this.","message":"Ensure your `grpc-stubs` version matches your installed `grpcio` runtime library version. Mismatched versions can lead to incorrect or missing type hints, as `grpc-stubs` tracks the `grpcio` API.","severity":"gotcha","affected_versions":"All versions."},{"fix":"Understand that `grpc-stubs` is a developer tool. Integrate `mypy` or similar static analysis tools into your development workflow and CI/CD pipeline to leverage its benefits.","message":"`grpc-stubs` provides type hints for static analysis (e.g., Mypy) only. It does not affect runtime behavior or introduce new runtime APIs. Your code will execute the same whether `grpc-stubs` is installed or not.","severity":"gotcha","affected_versions":"All versions."},{"fix":"For type hints related to your own generated stubs (from `.proto` files), rely on `grpcio-tools` to produce accurate type hints. `grpc-stubs` is most valuable for the core `grpc` library components. If conflicts occur, you might need to exclude specific paths from `mypy` configuration or carefully manage your stub generation process.","message":"If you use `grpcio-tools` to generate your own Python stubs from `.proto` files, `grpc-stubs` might conflict or duplicate type definitions, especially for `_pb2.py` and `_pb2_grpc.py` modules. The `grpc-stubs` package primarily targets the core `grpc` runtime module.","severity":"gotcha","affected_versions":"All versions."},{"fix":"Integrate `mypy` into your development workflow and CI/CD. Use `mypy your_script.py` or configure it in your `pyproject.toml` or `mypy.ini`.","message":"To benefit from `grpc-stubs`, you *must* explicitly run `mypy` or another compatible static type checker. Simply installing the package has no effect if the type checker is not invoked.","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}