From 39f8202990cb16b11028c6fec42b53775cba3301 Mon Sep 17 00:00:00 2001
From: Alan Boudreault <alan@alanb.ca>
Date: Tue, 13 Sep 2016 09:50:27 -0400
Subject: [PATCH] some docs improvement for 3.7.0

---
 cassandra/policies.py           |  3 +++
 docs/api/cassandra/policies.rst |  9 +++++++++
 docs/query_paging.rst           | 21 ++++++++++++++++++++-
 3 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/cassandra/policies.py b/cassandra/policies.py
index 27b66def..347907ec 100644
--- a/cassandra/policies.py
+++ b/cassandra/policies.py
@@ -939,6 +939,9 @@ class NoSpeculativeExecutionPolicy(SpeculativeExecutionPolicy):
 
 
 class ConstantSpeculativeExecutionPolicy(SpeculativeExecutionPolicy):
+    """
+    A speculative execution policy that sends a new query every X seconds (**delay**) for a maximum of Y attempts (**max_attempts**).
+    """
 
     def __init__(self, delay, max_attempts):
         self.delay = delay
diff --git a/docs/api/cassandra/policies.rst b/docs/api/cassandra/policies.rst
index c96e491a..83a193ba 100644
--- a/docs/api/cassandra/policies.rst
+++ b/docs/api/cassandra/policies.rst
@@ -68,3 +68,12 @@ Retrying Failed Operations
 
 .. autoclass:: DowngradingConsistencyRetryPolicy
    :members:
+
+Retrying Idempotent Operations
+------------------------------
+
+.. autoclass:: SpeculativeExecutionPolicy
+   :members:
+
+.. autoclass:: ConstantSpeculativeExecutionPolicy
+   :members:
diff --git a/docs/query_paging.rst b/docs/query_paging.rst
index 52366116..0b97de48 100644
--- a/docs/query_paging.rst
+++ b/docs/query_paging.rst
@@ -3,7 +3,7 @@
 Paging Large Queries
 ====================
 Cassandra 2.0+ offers support for automatic query paging.  Starting with
-version 2.0 of the driver, if :attr:`~.Cluster.protocol_version` is greater than 
+version 2.0 of the driver, if :attr:`~.Cluster.protocol_version` is greater than
 :const:`2` (it is by default), queries returning large result sets will be
 automatically paged.
 
@@ -74,3 +74,22 @@ pages.  For example::
     handler.finished_event.wait()
     if handler.error:
         raise handler.error
+
+Resume Paged Results
+--------------------
+
+You can resume the pagination when executing a new query by using the :attr:`.ResultSet.paging_state`. This can be useful if you want to provide some stateless pagination capabilities to your application (ie. via http). For example::
+
+    from cassandra.query import SimpleStatement
+    query = "SELECT * FROM users"
+    statement = SimpleStatement(query, fetch_size=10)
+    results = session.execute(statement)
+
+    # save the paging_state somewhere and return current results
+    session['paging_stage'] = results.paging_state
+
+
+    # resume the pagination sometime later...
+    statement = SimpleStatement(query, fetch_size=10)
+    ps = session['paging_state']
+    results = session.execute(statement, paging_state=ps)