Improve the documentation for serializer and deserializer

doc/python/sphinx/glossary.rst

@@ -14,3 +14,16 @@ Glossary
 
   metadata
     A sequence of metadatum.
+
+  serializer
+    A callable function that encodes an object into bytes. Applications are
+    allowed to provide any customized serializer, so there isn't a restriction
+    for the input object (i.e. even ``None``). On the server-side, the
+    serializer is invoked with server handler's return value; on the
+    client-side, the serializer is invoked with outbound message objects.
+
+  deserializer
+    A callable function that decodes bytes into an object. Same as serializer,
+    the returned object doesn't have restrictions (i.e. ``None`` allowed). The
+    deserializer is invoked with inbound message bytes on both the server side
+    and the client-side.

src/python/grpcio/grpc/__init__.py

@@ -994,9 +994,9 @@ class Channel(six.with_metaclass(abc.ABCMeta)):
 
         Args:
           method: The name of the RPC method.
-          request_serializer: Optional behaviour for serializing the request
+          request_serializer: Optional :term:`serializer` for serializing the request
             message. Request goes unserialized in case None is passed.
-          response_deserializer: Optional behaviour for deserializing the
+          response_deserializer: Optional :term:`deserializer` for deserializing the
             response message. Response goes undeserialized in case None
             is passed.
 
@@ -1014,9 +1014,9 @@ class Channel(six.with_metaclass(abc.ABCMeta)):
 
         Args:
           method: The name of the RPC method.
-          request_serializer: Optional behaviour for serializing the request
+          request_serializer: Optional :term:`serializer` for serializing the request
             message. Request goes unserialized in case None is passed.
-          response_deserializer: Optional behaviour for deserializing the
+          response_deserializer: Optional :term:`deserializer` for deserializing the
             response message. Response goes undeserialized in case None is
             passed.
 
@@ -1034,9 +1034,9 @@ class Channel(six.with_metaclass(abc.ABCMeta)):
 
         Args:
           method: The name of the RPC method.
-          request_serializer: Optional behaviour for serializing the request
+          request_serializer: Optional :term:`serializer` for serializing the request
             message. Request goes unserialized in case None is passed.
-          response_deserializer: Optional behaviour for deserializing the
+          response_deserializer: Optional :term:`deserializer` for deserializing the
             response message. Response goes undeserialized in case None is
             passed.
 
@@ -1054,9 +1054,9 @@ class Channel(six.with_metaclass(abc.ABCMeta)):
 
         Args:
           method: The name of the RPC method.
-          request_serializer: Optional behaviour for serializing the request
+          request_serializer: Optional :term:`serializer` for serializing the request
             message. Request goes unserialized in case None is passed.
-          response_deserializer: Optional behaviour for deserializing the
+          response_deserializer: Optional :term:`deserializer` for deserializing the
             response message. Response goes undeserialized in case None
             is passed.
 
@@ -1271,11 +1271,11 @@ class RpcMethodHandler(six.with_metaclass(abc.ABCMeta)):
         or any arbitrary number of request messages.
       response_streaming: Whether the RPC supports exactly one response message
         or any arbitrary number of response messages.
-      request_deserializer: A callable behavior that accepts a byte string and
+      request_deserializer: A callable :term:`deserializer` that accepts a byte string and
         returns an object suitable to be passed to this object's business
         logic, or None to indicate that this object's business logic should be
         passed the raw request bytes.
-      response_serializer: A callable behavior that accepts an object produced
+      response_serializer: A callable :term:`serializer` that accepts an object produced
         by this object's business logic and returns a byte string, or None to
         indicate that the byte strings produced by this object's business logic
         should be transmitted on the wire as they are.
@@ -1496,8 +1496,8 @@ def unary_unary_rpc_method_handler(behavior,
     Args:
       behavior: The implementation of an RPC that accepts one request
         and returns one response.
-      request_deserializer: An optional behavior for request deserialization.
-      response_serializer: An optional behavior for response serialization.
+      request_deserializer: An optional :term:`deserializer` for request deserialization.
+      response_serializer: An optional :term:`serializer` for response serialization.
 
     Returns:
       An RpcMethodHandler object that is typically used by grpc.Server.
@@ -1516,8 +1516,8 @@ def unary_stream_rpc_method_handler(behavior,
     Args:
       behavior: The implementation of an RPC that accepts one request
         and returns an iterator of response values.
-      request_deserializer: An optional behavior for request deserialization.
-      response_serializer: An optional behavior for response serialization.
+      request_deserializer: An optional :term:`deserializer` for request deserialization.
+      response_serializer: An optional :term:`serializer` for response serialization.
 
     Returns:
       An RpcMethodHandler object that is typically used by grpc.Server.
@@ -1536,8 +1536,8 @@ def stream_unary_rpc_method_handler(behavior,
     Args:
       behavior: The implementation of an RPC that accepts an iterator of
         request values and returns a single response value.
-      request_deserializer: An optional behavior for request deserialization.
-      response_serializer: An optional behavior for response serialization.
+      request_deserializer: An optional :term:`deserializer` for request deserialization.
+      response_serializer: An optional :term:`serializer` for response serialization.
 
     Returns:
       An RpcMethodHandler object that is typically used by grpc.Server.
@@ -1556,8 +1556,8 @@ def stream_stream_rpc_method_handler(behavior,
     Args:
       behavior: The implementation of an RPC that accepts an iterator of
         request values and returns an iterator of response values.
-      request_deserializer: An optional behavior for request deserialization.
-      response_serializer: An optional behavior for response serialization.
+      request_deserializer: An optional :term:`deserializer` for request deserialization.
+      response_serializer: An optional :term:`serializer` for response serialization.
 
     Returns:
       An RpcMethodHandler object that is typically used by grpc.Server.

src/python/grpcio/grpc/_simple_stubs.py

@@ -192,9 +192,9 @@ def unary_unary(
       request: An iterator that yields request values for the RPC.
       target: The server address.
       method: The name of the RPC method.
-      request_serializer: Optional behaviour for serializing the request
+      request_serializer: Optional :term:`serializer` for serializing the request
         message. Request goes unserialized in case None is passed.
-      response_deserializer: Optional behaviour for deserializing the response
+      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
         runtime) to configure the channel.
@@ -263,9 +263,9 @@ def unary_stream(
       request: An iterator that yields request values for the RPC.
       target: The server address.
       method: The name of the RPC method.
-      request_serializer: Optional behaviour for serializing the request
+      request_serializer: Optional :term:`serializer` for serializing the request
         message. Request goes unserialized in case None is passed.
-      response_deserializer: Optional behaviour for deserializing the response
+      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
         runtime) to configure the channel.
@@ -333,9 +333,9 @@ def stream_unary(
       request_iterator: An iterator that yields request values for the RPC.
       target: The server address.
       method: The name of the RPC method.
-      request_serializer: Optional behaviour for serializing the request
+      request_serializer: Optional :term:`serializer` for serializing the request
         message. Request goes unserialized in case None is passed.
-      response_deserializer: Optional behaviour for deserializing the response
+      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
         runtime) to configure the channel.
@@ -403,9 +403,9 @@ def stream_stream(
       request_iterator: An iterator that yields request values for the RPC.
       target: The server address.
       method: The name of the RPC method.
-      request_serializer: Optional behaviour for serializing the request
+      request_serializer: Optional :term:`serializer` for serializing the request
         message. Request goes unserialized in case None is passed.
-      response_deserializer: Optional behaviour for deserializing the response
+      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
         runtime) to configure the channel.

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

@@ -274,9 +274,9 @@ class Channel(abc.ABC):
 
         Args:
           method: The name of the RPC method.
-          request_serializer: Optional behaviour for serializing the request
+          request_serializer: Optional :term:`serializer` for serializing the request
             message. Request goes unserialized in case None is passed.
-          response_deserializer: Optional behaviour for deserializing the
+          response_deserializer: Optional :term:`deserializer` for deserializing the
             response message. Response goes undeserialized in case None
             is passed.
 
@@ -295,9 +295,9 @@ class Channel(abc.ABC):
 
         Args:
           method: The name of the RPC method.
-          request_serializer: Optional behaviour for serializing the request
+          request_serializer: Optional :term:`serializer` for serializing the request
             message. Request goes unserialized in case None is passed.
-          response_deserializer: Optional behaviour for deserializing the
+          response_deserializer: Optional :term:`deserializer` for deserializing the
             response message. Response goes undeserialized in case None
             is passed.
 
@@ -316,9 +316,9 @@ class Channel(abc.ABC):
 
         Args:
           method: The name of the RPC method.
-          request_serializer: Optional behaviour for serializing the request
+          request_serializer: Optional :term:`serializer` for serializing the request
             message. Request goes unserialized in case None is passed.
-          response_deserializer: Optional behaviour for deserializing the
+          response_deserializer: Optional :term:`deserializer` for deserializing the
             response message. Response goes undeserialized in case None
             is passed.
 
@@ -337,9 +337,9 @@ class Channel(abc.ABC):
 
         Args:
           method: The name of the RPC method.
-          request_serializer: Optional behaviour for serializing the request
+          request_serializer: Optional :term:`serializer` for serializing the request
             message. Request goes unserialized in case None is passed.
-          response_deserializer: Optional behaviour for deserializing the
+          response_deserializer: Optional :term:`deserializer` for deserializing the
             response message. Response goes undeserialized in case None
             is passed.