Add documentation

doc/python/sphinx/grpc.rst

@@ -186,3 +186,10 @@ Compression
 ^^^^^^^^^^^
 
 .. autoclass:: Compression
+
+Runtime Protobuf Parsing
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. autofunction:: protos
+.. autofunction:: services
+.. autofunction:: protos_and_services

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

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()