xref: /aosp_15_r20/external/grpc-grpc/doc/python/server_reflection.md (revision cc02d7e222339f7a4f6ba5f422e6413f4bd931f2) 
1# gRPC Python Server Reflection
2
3This document shows how to use gRPC Server Reflection in gRPC Python.
4Please see [C++ Server Reflection Tutorial] for general information
5and more examples how to use server reflection.
6
7## Enable server reflection in Python servers
8
9gRPC Python Server Reflection is an add-on library. To use it, first install
10the [grpcio-reflection] PyPI package into your project.
11
12Note that with Python you need to manually register the service
13descriptors with the reflection service implementation when creating a server
14(this isn't necessary with e.g. C++ or Java)
15```python
16# add the following import statement to use server reflection
17from grpc_reflection.v1alpha import reflection
18# ...
19def serve():
20    server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
21    helloworld_pb2_grpc.add_GreeterServicer_to_server(Greeter(), server)
22    # the reflection service will be aware of "Greeter" and "ServerReflection" services.
23    SERVICE_NAMES = (
24        helloworld_pb2.DESCRIPTOR.services_by_name['Greeter'].full_name,
25        reflection.SERVICE_NAME,
26    )
27    reflection.enable_server_reflection(SERVICE_NAMES, server)
28    server.add_insecure_port('[::]:50051')
29    server.start()
30```
31
32Please see [greeter_server_with_reflection.py] in the examples directory for the full
33example, which extends the gRPC [Python `Greeter` example] on a reflection-enabled server.
34
35After starting the server, you can verify that the server reflection
36is working properly by using the [`grpc_cli` command line tool]:
37
38 ```sh
39  $ grpc_cli ls localhost:50051
40  ```
41
42  output:
43  ```sh
44  grpc.reflection.v1alpha.ServerReflection
45  helloworld.Greeter
46  ```
47
48  For more examples and instructions how to use the `grpc_cli` tool,
49  please refer to the [`grpc_cli` documentation] and the
50  [C++ Server Reflection Tutorial].
51
52
53## Use Server Reflection in a Python client
54
55Server Reflection can be used by clients to get information about gRPC services
56at runtime. We've provided a descriptor database called
57[ProtoReflectionDescriptorDatabase](../../src/python/grpcio_reflection/grpc_reflection/v1alpha/proto_reflection_descriptor_database.py)
58which implements the
59[DescriptorDatabase](https://googleapis.dev/python/protobuf/latest/google/protobuf/descriptor_database.html#google.protobuf.descriptor_database.DescriptorDatabase)
60interface. It manages the communication between clients and reflection services
61and the storage of received information. Clients can use it as using a local
62descriptor database.
63
64- To use Server Reflection with ProtoReflectionDescriptorDatabase, first
65  initialize an instance with a channel.
66
67  ```Python
68  import grpc
69  from grpc_reflection.v1alpha.proto_reflection_descriptor_database import ProtoReflectionDescriptorDatabase
70
71  channel = grpc.secure_channel(server_address, creds)
72  reflection_db = ProtoReflectionDescriptorDatabase(channel)
73  ```
74
75- Then use this instance to feed a
76  [DescriptorPool](https://googleapis.dev/python/protobuf/latest/google/protobuf/descriptor_pool.html#google.protobuf.descriptor_pool.DescriptorPool).
77
78  ```Python
79  from google.protobuf.descriptor_pool import DescriptorPool
80
81  desc_pool = DescriptorPool(reflection_db)
82  ```
83
84- Example usage of this descriptor pool:
85
86  * Get Service/method descriptors.
87
88    ```Python
89    service_desc = desc_pool.FindServiceByName("helloworld.Greeter")
90    method_desc = service_desc.FindMethodByName("helloworld.Greeter.SayHello")
91    ```
92
93  * Get message type descriptors and create messages dynamically.
94
95    ```Python
96    request_desc = desc_pool.FindMessageTypeByName("helloworld.HelloRequest")
97    request = MessageFactory(desc_pool).GetPrototype(request_desc)()
98    ```
99
100- You can also use the Reflection Database to list all the services:
101
102    ```Python
103    services = reflection_db.get_services()
104    ```
105
106
107## Additional Resources
108
109The [Server Reflection Protocol] provides detailed
110information about how the server reflection works and describes the server reflection
111protocol in detail.
112
113
114[C++ Server Reflection Tutorial]: ../server_reflection_tutorial.md
115[grpcio-reflection]: https://pypi.org/project/grpcio-reflection/
116[greeter_server_with_reflection.py]: https://github.com/grpc/grpc/blob/master/examples/python/helloworld/greeter_server_with_reflection.py
117[Python `Greeter` example]: https://github.com/grpc/grpc/tree/master/examples/python/helloworld
118[`grpc_cli` command line tool]: https://github.com/grpc/grpc/blob/master/doc/command_line_tool.md
119[`grpc_cli` documentation]: ../command_line_tool.md
120[C++ Server Reflection Tutorial]: ../server_reflection_tutorial.md
121[Server Reflection Protocol]: ../server-reflection.md
122