From 2c1efcd0ae9b12b60ffcce75c0525febef4e437b Mon Sep 17 00:00:00 2001
From: Richard Belleville <j.belleville.richard@gmail.com>
Date: Thu, 6 Aug 2020 12:25:21 -0700
Subject: [PATCH] Add documentation

---
 doc/python/sphinx/grpc.rst                    |  7 +++
 src/python/grpcio/grpc/_runtime_protos.py     | 51 +++++++++++++++++++
 .../python/grpcio_tools/grpc_tools/protoc.py  |  6 ++-
 3 files changed, 62 insertions(+), 2 deletions(-)

diff --git a/doc/python/sphinx/grpc.rst b/doc/python/sphinx/grpc.rst
index 4717eb12332..a657dcc0f80 100644
--- a/doc/python/sphinx/grpc.rst
+++ b/doc/python/sphinx/grpc.rst
@@ -186,3 +186,10 @@ Compression
 ^^^^^^^^^^^
 
 .. autoclass:: Compression
+
+Runtime Protobuf Parsing
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autofunction:: protos
+.. autofunction:: services
+.. autofunction:: protos_and_services
diff --git a/src/python/grpcio/grpc/_runtime_protos.py b/src/python/grpcio/grpc/_runtime_protos.py
index 71ac7d0a8a0..8b25a1b4f20 100644
--- a/src/python/grpcio/grpc/_runtime_protos.py
+++ b/src/python/grpcio/grpc/_runtime_protos.py
@@ -48,6 +48,57 @@ def _interpreter_version_protos_and_services(*args, **kwargs):
     )
 
 
+def protos(protobuf_path):
+    """Returns a module generated by the indicated .proto file.
+
+    Use this function to retrieve classes corresponding to message
+    definitions in the .proto file.
+
+    To inspect the contents of the returned module, use the dir function.
+    For example:
+
+    ```
+    protos = grpc.protos("foo.proto")
+    print(dir(protos))
+    ```
+
+    The returned module object corresponds to the _pb2.py file generated
+    by protoc. The path is expected to be relative to an entry on sys.path
+    and all transitive dependencies of the file should also be resolveable
+    from an entry on sys.path.
+    """
+
+
+def services(protobuf_path):
+    """Returns a module generated by the indicated .proto file.
+
+    Use this function to retrieve classes and functions corresponding to
+    service definitions in the .proto file, including both stub and servicer
+    definitions.
+
+    To inspect the contents of the returned module, use the dir function.
+    For example:
+
+    ```
+    services = grpc.services("foo.proto")
+    print(dir(services))
+    ```
+
+    The returned module object corresponds to the _pb2_grpc.py file generated
+    by protoc. The path is expected to be relative to an entry on sys.path
+    and all transitive dependencies of the file should also be resolveable
+    from an entry on sys.path.
+    """
+
+
+def protos_and_services(protobuf_path):
+    """Returns a 2-tuple of modules corresponding to protos and services.
+
+    The return value of this function is equivalent to a call to protos and a
+    call to services.
+    """
+
+
 if sys.version_info[0] < 3:
     protos = _interpreter_version_protos
     services = _interpreter_version_services
diff --git a/tools/distrib/python/grpcio_tools/grpc_tools/protoc.py b/tools/distrib/python/grpcio_tools/grpc_tools/protoc.py
index b3f52233894..a16af4c418d 100644
--- a/tools/distrib/python/grpcio_tools/grpc_tools/protoc.py
+++ b/tools/distrib/python/grpcio_tools/grpc_tools/protoc.py
@@ -53,12 +53,14 @@ if sys.version_info[0] > 2:
         return ".".join(components[:-1] + [proto_base_name + suffix])
 
     def _protos(protobuf_path):
+        """Returns a gRPC module generated from the indicated proto file."""
         module_name = _proto_file_to_module_name(_PROTO_MODULE_SUFFIX,
                                                  protobuf_path)
         module = importlib.import_module(module_name)
         return module
 
     def _services(protobuf_path):
+        """Returns a module generated from the indicated proto file."""
         _protos(protobuf_path)
         module_name = _proto_file_to_module_name(_SERVICE_MODULE_SUFFIX,
                                                  protobuf_path)
@@ -66,8 +68,8 @@ if sys.version_info[0] > 2:
         return module
 
     def _protos_and_services(protobuf_path):
-        return (_protos(protobuf_path),
-                _services(protobuf_path))
+        """Returns two modules, corresponding to _pb2.py and _pb2_grpc.py files."""
+        return (_protos(protobuf_path), _services(protobuf_path))
 
     _proto_code_cache = {}
     _proto_code_cache_lock = threading.RLock()