{"library":"grpcio-reflection","title":"gRPC Python Reflection","description":"grpcio-reflection is the Python implementation of the standard Protobuf Reflection Service for gRPC. It enables gRPC clients to dynamically discover available services, their RPC methods, and associated message types at runtime, without needing pre-compiled .proto files. This is particularly useful for debugging tools like grpcurl and Postman. The library is currently at version 1.80.0 and follows the gRPC core's approximately six-week release cadence.","status":"active","version":"1.80.0","language":"en","source_language":"en","source_url":"https://github.com/grpc/grpc/tree/master/src/python/grpcio_reflection","tags":["gRPC","reflection","protobuf","service discovery","introspection"],"install":[{"cmd":"pip install grpcio-reflection","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core gRPC library; grpcio-reflection depends on it for server and client functionalities.","package":"grpcio"},{"reason":"While grpcio itself decoupled from direct protobuf dependency in v1.12.0, grpcio-reflection directly uses protobuf for descriptor management. Ensure a compatible version is installed.","package":"protobuf"}],"imports":[{"note":"The common pattern is to import the 'reflection' module directly, not the parent package. The module provides functions like `enable_server_reflection` and the `SERVICE_NAME` constant.","wrong":"import grpc_reflection.v1alpha.reflection","symbol":"reflection","correct":"from grpc_reflection.v1alpha import reflection"}],"quickstart":{"code":"import grpc\nfrom concurrent import futures\nfrom grpc_reflection.v1alpha import reflection\n\n# --- Simulate generated protobuf code ---\n# In a real application, these would be generated by grpcio-tools\n# from your .proto files (e.g., my_service.proto).\n# For this example, we define minimal mock objects.\nclass MockService_pb2:\n    DESCRIPTOR = type('Descriptor', (object,), {'services_by_name': {'MyService': type('ServiceDescriptor', (object,), {'full_name': 'my.package.MyService'})}}})()\n\nclass MockService_pb2_grpc:\n    class MyServiceServicer:\n        def __init__(self):\n            pass\n\n    def add_MyServiceServicer_to_server(servicer, server):\n        print(f\"Mock: Adding {servicer.__class__.__name__} to server\")\n\n# --- Real gRPC server with reflection ---\n\nclass MyServiceServicer(MockService_pb2_grpc.MyServiceServicer):\n    def MyMethod(self, request, context):\n        # In a real scenario, handle actual RPC logic\n        print(f\"Received request for MyMethod: {request}\")\n        return \"Response from MyMethod\"\n\ndef serve_with_reflection(port='[::]:50051'):\n    server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))\n\n    # Register your actual gRPC service implementation\n    MockService_pb2_grpc.add_MyServiceServicer_to_server(MyServiceServicer(), server)\n\n    # Enable server reflection\n    # List all service names you want to expose via reflection.\n    # This typically includes your custom services and the reflection service itself.\n    SERVICE_NAMES = (\n        MockService_pb2.DESCRIPTOR.services_by_name['MyService'].full_name,\n        reflection.SERVICE_NAME,\n    )\n    reflection.enable_server_reflection(SERVICE_NAMES, server)\n\n    server.add_insecure_port(port)\n    server.start()\n    print(f\"Server with reflection enabled listening on {port}\")\n    server.wait_for_termination()\n\nif __name__ == '__main__':\n    # To run this, you'd typically have your actual .proto files compiled\n    # and replace MockService_pb2 and MockService_pb2_grpc with your generated ones.\n    # Example usage with grpcurl (after running this script):\n    # grpcurl -plaintext localhost:50051 list\n    # grpcurl -plaintext localhost:50051 list my.package.MyService\n    # grpcurl -plaintext -d '{\"name\": \"World\"}' localhost:50051 my.package.MyService/MyMethod\n    serve_with_reflection()","lang":"python","description":"This quickstart demonstrates how to enable server reflection for a gRPC Python server. It includes a mock gRPC service setup to illustrate the integration of `grpcio-reflection`. In a real application, you would replace the `MockService_pb2` and `MockService_pb2_grpc` with the actual modules generated from your `.proto` files using `grpcio-tools`. The `reflection.enable_server_reflection` function is called with a list of fully-qualified service names you wish to expose."},"warnings":[{"fix":"Ensure `grpcio-reflection` is installed (`pip install grpcio-reflection`) and add `from grpc_reflection.v1alpha import reflection` and `reflection.enable_server_reflection(SERVICE_NAMES, server)` to your server setup.","message":"Reflection is not automatically enabled on a gRPC server. You must explicitly install `grpcio-reflection` and call `reflection.enable_server_reflection()` with the list of service names you want to expose. In Python, this also entails manually registering service descriptors, unlike some other gRPC language implementations.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always install `grpcio-reflection` alongside `grpcio` and `protobuf` using compatible versions. If encountering issues, explicitly upgrade `protobuf` to a version compatible with your `grpcio-reflection` version. Consult the `grpcio-reflection` changelog or PyPI dependency metadata for specific requirements.","message":"Older versions of `grpcio-reflection` might have version incoherence issues with `protobuf`. For instance, `grpcio-reflection 1.71.0` was noted to internally require `protobuf >=5.29.0` while its metadata specified `protobuf >=5.26.1`, leading to potential runtime failures if an incompatible `protobuf` version was present.","severity":"breaking","affected_versions":"<= 1.71.0"},{"fix":"Implement conditional logic (e.g., via environment variables) to enable reflection only when needed. Consider adding authentication or access controls if reflection must be exposed in sensitive environments.","message":"Exposing gRPC reflection in production environments can be a security risk as it allows clients to discover your API's internal structure. It's recommended to enable reflection conditionally (e.g., only in development or staging environments) or secure its access.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always include `grpcio-reflection` in your project's dependencies (`install_requires` in `setup.py` or `dependencies` in `pyproject.toml`) and ensure it is installed.","message":"If `grpcio-reflection` is not explicitly listed as a dependency and installed, applications using `grpc_reflection.v1alpha.reflection` will fail with a `ModuleNotFoundError`, even if `grpcio` and `grpcio-tools` are installed.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-05T00:00:00.000Z","next_check":"2026-07-04T00:00:00.000Z"}