diff --git a/doc/python/sphinx/conf.py b/doc/python/sphinx/conf.py index 49e5ecb1dcd..6e4bfab7d0e 100644 --- a/doc/python/sphinx/conf.py +++ b/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 diff --git a/doc/python/sphinx/glossary.rst b/doc/python/sphinx/glossary.rst index fb44bdf114d..a4daa31d180 100644 --- a/doc/python/sphinx/glossary.rst +++ b/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),)``. diff --git a/src/python/grpcio/grpc/__init__.py b/src/python/grpcio/grpc/__init__.py index 75b1a923f67..d6c6815291c 100644 --- a/src/python/grpcio/grpc/__init__.py +++ b/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 diff --git a/src/python/grpcio/grpc/_simple_stubs.py b/src/python/grpcio/grpc/_simple_stubs.py index 39535527ef5..202ad123e82 100644 --- a/src/python/grpcio/grpc/_simple_stubs.py +++ b/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(). diff --git a/src/python/grpcio/grpc/experimental/aio/_channel.py b/src/python/grpcio/grpc/experimental/aio/_channel.py index 89c556c997e..afa9cf30630 100644 --- a/src/python/grpcio/grpc/experimental/aio/_channel.py +++ b/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. diff --git a/src/python/grpcio/grpc/experimental/aio/_server.py b/src/python/grpcio/grpc/experimental/aio/_server.py index 478049e5db4..81438891268 100644 --- a/src/python/grpcio/grpc/experimental/aio/_server.py +++ b/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 diff --git a/src/python/grpcio_tests/tests/unit/_channel_args_test.py b/src/python/grpcio_tests/tests/unit/_channel_args_test.py index 3f3db2edd23..2f2eea61dbd 100644 --- a/src/python/grpcio_tests/tests/unit/_channel_args_test.py +++ b/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