Merge pull request #22745 from lidizheng/doc-channel-args

Explain how to find channel arguments in our doc

doc/python/sphinx/conf.py

@@ -28,13 +28,17 @@ sys.path.insert(0, os.path.join(PYTHON_FOLDER, 'grpcio_testing'))
 # -- Project information -----------------------------------------------------
 
 project = 'gRPC Python'
-copyright = '2018, The gRPC Authors'
+copyright = '2020, The gRPC Authors'
 author = 'The gRPC Authors'
 
 # Import generated grpc_version after the path been modified
 import grpc_version
-version = ".".join(grpc_version.VERSION.split(".")[:3])
+version = '.'.join(grpc_version.VERSION.split('.')[:3])
 release = grpc_version.VERSION
+if 'dev' in grpc_version.VERSION:
+    branch = 'master'
+else:
+    branch = 'v%s.%s.x' % tuple(grpc_version.VERSION.split('.')[:2])
 
 # -- General configuration ---------------------------------------------------
 
@@ -100,3 +104,7 @@ epub_exclude_files = ['search.html']
 # -- Options for todo extension ----------------------------------------------
 
 todo_include_todos = True
+
+# -- Options for substitutions -----------------------------------------------
+
+rst_epilog = '.. |grpc_types_link| replace:: https://github.com/grpc/grpc/blob/%s/include/grpc/impl/codegen/grpc_types.h' % branch

doc/python/sphinx/glossary.rst

@@ -39,3 +39,12 @@ Glossary
     until the channel is READY. Any submitted RPCs may still fail before the
     READY state is reached for other reasons, e.g., the client channel has been
     shut down or the RPC's deadline has been reached.
+
+  channel_arguments
+    A list of key-value pairs to configure the underlying gRPC Core channel or
+    server object. Channel arguments are meant for advanced usages and contain
+    experimental API (some may not labeled as experimental). Full list of
+    available channel arguments and documentation can be found under the
+    "grpc_arg_keys" section of "grpc_types.h" header file (|grpc_types_link|).
+    For example, if you want to disable TCP port reuse, you may construct
+    channel arguments like: ``options = (('grpc.so_reuseport', 0),)``.

src/python/grpcio/grpc/__init__.py

@@ -1857,7 +1857,7 @@ def insecure_channel(target, options=None, compression=None):
 
     Args:
       target: The server address
-      options: An optional list of key-value pairs (channel args
+      options: An optional list of key-value pairs (:term:`channel_arguments`
         in gRPC Core runtime) to configure the channel.
       compression: An optional value indicating the compression method to be
         used over the lifetime of the channel. This is an EXPERIMENTAL option.
@@ -1878,7 +1878,7 @@ def secure_channel(target, credentials, options=None, compression=None):
     Args:
       target: The server address.
       credentials: A ChannelCredentials instance.
-      options: An optional list of key-value pairs (channel args
+      options: An optional list of key-value pairs (:term:`channel_arguments`
         in gRPC Core runtime) to configure the channel.
       compression: An optional value indicating the compression method to be
         used over the lifetime of the channel. This is an EXPERIMENTAL option.
@@ -1942,7 +1942,7 @@ def server(thread_pool,
         and optionally manipulate the incoming RPCs before handing them over to
         handlers. The interceptors are given control in the order they are
         specified. This is an EXPERIMENTAL API.
-      options: An optional list of key-value pairs (channel args in gRPC runtime)
+      options: An optional list of key-value pairs (:term:`channel_arguments` in gRPC runtime)
         to configure the channel.
       maximum_concurrent_rpcs: The maximum number of concurrent RPCs this server
         will service before returning RESOURCE_EXHAUSTED status, or None to

src/python/grpcio/grpc/_simple_stubs.py

@@ -196,7 +196,7 @@ def unary_unary(
         message. Request goes unserialized in case None is passed.
       response_deserializer: Optional :term:`deserializer` for deserializing the response
         message. Response goes undeserialized in case None is passed.
-      options: An optional list of key-value pairs (channel args in gRPC Core
+      options: An optional list of key-value pairs (:term:`channel_arguments` in gRPC Core
         runtime) to configure the channel.
       channel_credentials: A credential applied to the whole channel, e.g. the
         return value of grpc.ssl_channel_credentials() or
@@ -267,7 +267,7 @@ def unary_stream(
         message. Request goes unserialized in case None is passed.
       response_deserializer: Optional :term:`deserializer` for deserializing the response
         message. Response goes undeserialized in case None is passed.
-      options: An optional list of key-value pairs (channel args in gRPC Core
+      options: An optional list of key-value pairs (:term:`channel_arguments` in gRPC Core
         runtime) to configure the channel.
       channel_credentials: A credential applied to the whole channel, e.g. the
         return value of grpc.ssl_channel_credentials().
@@ -337,7 +337,7 @@ def stream_unary(
         message. Request goes unserialized in case None is passed.
       response_deserializer: Optional :term:`deserializer` for deserializing the response
         message. Response goes undeserialized in case None is passed.
-      options: An optional list of key-value pairs (channel args in gRPC Core
+      options: An optional list of key-value pairs (:term:`channel_arguments` in gRPC Core
         runtime) to configure the channel.
       channel_credentials: A credential applied to the whole channel, e.g. the
         return value of grpc.ssl_channel_credentials().
@@ -407,7 +407,7 @@ def stream_stream(
         message. Request goes unserialized in case None is passed.
       response_deserializer: Optional :term:`deserializer` for deserializing the response
         message. Response goes undeserialized in case None is passed.
-      options: An optional list of key-value pairs (channel args in gRPC Core
+      options: An optional list of key-value pairs (:term:`channel_arguments` in gRPC Core
         runtime) to configure the channel.
       channel_credentials: A credential applied to the whole channel, e.g. the
         return value of grpc.ssl_channel_credentials().

src/python/grpcio/grpc/experimental/aio/_channel.py

@@ -406,7 +406,7 @@ def insecure_channel(
 
     Args:
       target: The server address
-      options: An optional list of key-value pairs (channel args
+      options: An optional list of key-value pairs (:term:`channel_arguments`
         in gRPC Core runtime) to configure the channel.
       compression: An optional value indicating the compression method to be
         used over the lifetime of the channel. This is an EXPERIMENTAL option.
@@ -430,7 +430,7 @@ def secure_channel(target: str,
     Args:
       target: The server address.
       credentials: A ChannelCredentials instance.
-      options: An optional list of key-value pairs (channel args
+      options: An optional list of key-value pairs (:term:`channel_arguments`
         in gRPC Core runtime) to configure the channel.
       compression: An optional value indicating the compression method to be
         used over the lifetime of the channel. This is an EXPERIMENTAL option.

src/python/grpcio/grpc/experimental/aio/_server.py

@@ -187,7 +187,7 @@ def server(migration_thread_pool: Optional[Executor] = None,
         and optionally manipulate the incoming RPCs before handing them over to
         handlers. The interceptors are given control in the order they are
         specified. This is an EXPERIMENTAL API.
-      options: An optional list of key-value pairs (channel args in gRPC runtime)
+      options: An optional list of key-value pairs (:term:`channel_arguments` in gRPC runtime)
         to configure the channel.
       maximum_concurrent_rpcs: The maximum number of concurrent RPCs this server
         will service before returning RESOURCE_EXHAUSTED status, or None to

src/python/grpcio_tests/tests/unit/_channel_args_test.py

@@ -11,7 +11,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-"""Tests of Channel Args on client/server side."""
+"""Tests of channel arguments on client/server side."""
 
 from concurrent import futures
 import unittest