Docs for custom_payload

cassandra/cluster.py

@@ -1390,9 +1390,9 @@ class Session(object):
         trace details, the :attr:`~.Statement.trace` attribute will be left as
         :const:`None`.
 
-        `custom_payload` is a dict as described in TODO section. If `query` is a Statement
+        `custom_payload` is a :ref:`custom_payload` dict to be passed to the server.
-        with its own custom_payload. the message will be a union of the two,
+        If `query` is a Statement with its own custom_payload. The message payload
-        with the values specified here taking precedence.
+        will be a union of the two, with the values specified here taking precedence.
         """
         if timeout is _NOT_SET:
             timeout = self.default_timeout
@@ -1426,12 +1426,13 @@ class Session(object):
         :meth:`.ResponseFuture.get_query_trace()` after the request
         completes to retrieve a :class:`.QueryTrace` instance.
 
-        `custom_payload` is a dict as described in TODO section. If `query` is
+        `custom_payload` is a :ref:`custom_payload` dict to be passed to the server.
-        a Statement with a custom_payload specified. the message will be a
+        If `query` is a Statement with its own custom_payload. The message payload
-        union of the two, with the values specified here taking precedence.
+        will be a union of the two, with the values specified here taking precedence.
 
         If the server sends a custom payload in the response message,
-        the dict can be obtained via :attr:`.ResponseFuture.custom_payload`
+        the dict can be obtained following :meth:`.ResponseFuture.result` via
+        :attr:`.ResponseFuture.custom_payload`
 
         Example usage::
 
@@ -1546,7 +1547,7 @@ class Session(object):
         Preparing the same query more than once will likely affect performance.
 
         `custom_payload` is a key value map to be passed along with the prepare
-        message. See TODO: refer to doc section
+        message. See :ref:`custom_payload`.
         """
         message = PrepareMessage(query=query)
         message.custom_payload = custom_payload

cassandra/query.py

@@ -199,11 +199,7 @@ class Statement(object):
 
     custom_payload = None
     """
-    TODO: refer to custom proto doc section
+    :ref:`custom_payload` to be passed to the server.
-    A string:binary_type dict holding custom key/value pairs to be passed
-    in the frame to a custom QueryHandler on the server side.
-
-    By default these values are ignored by the server.
 
     These are only allowed when using protocol version 4 or higher.
 
@@ -632,9 +628,10 @@ class BatchStatement(Statement):
         `consistency_level` should be a :class:`~.ConsistencyLevel` value
         to be used for all operations in the batch.
 
-        `custom_payload` is a key-value map TODO: refer to doc section
+        `custom_payload` is a :ref:`custom_payload` passed to the server.
         Note: as Statement objects are added to the batch, this map is
-        updated with values from their custom payloads.
+        updated with any values found in their custom payloads. These are
+        only allowed when using protocol version 4 or higher.
 
         Example usage:
 

docs/api/index.rst

@@ -14,6 +14,7 @@ Core Driver
    cassandra/metrics
    cassandra/query
    cassandra/pool
+   cassandra/protocol
    cassandra/encoder
    cassandra/decoder
    cassandra/concurrent