Add FAQ section to docs

PYTHON-115

docs/cqlengine/faq.rst

@@ -2,15 +2,15 @@
 Frequently Asked Questions
 ==========================
 
-Q: Why don't updates work correctly on models instantiated as Model(field=value, field2=value2)?
+Why don't updates work correctly on models instantiated as Model(field=value, field2=value2)?
 ------------------------------------------------------------------------------------------------
 
-A: The recommended way to create new rows is with the models .create method. The values passed into a model's init method are interpreted by the model as the values as they were read from a row. This allows the model to "know" which rows have changed since the row was read out of cassandra, and create suitable update statements.
+The recommended way to create new rows is with the models .create method. The values passed into a model's init method are interpreted by the model as the values as they were read from a row. This allows the model to "know" which rows have changed since the row was read out of cassandra, and create suitable update statements.
 
-Q: How to preserve ordering in batch query?
+How to preserve ordering in batch query?
 -------------------------------------------
 
-A: Statement Ordering is not supported by CQL3 batches. Therefore,
+Statement Ordering is not supported by CQL3 batches. Therefore,
 once cassandra needs resolving conflict(Updating the same column in one batch),
 The algorithm below would be used.
 

docs/faq.rst

@@ -0,0 +1,83 @@
+Frequently Asked Questions
+==========================
+
+See also :doc:`cqlengine FAQ <cqlengine/faq>`
+
+Why do connections or IO operations timeout in my WSGI application?
+-------------------------------------------------------------------
+Depending on your application process model, it may be forking after driver Session is created. Most IO reactors do not handle this, and problems will manifest as timeouts.
+
+To avoid this, make sure to create sessions per process, after the fork. Using uWSGI and Flask for example:
+
+.. code-block:: python
+
+    from flask import Flask
+    from uwsgidecorators import postfork
+    from cassandra.cluster import Cluster
+
+    session = None
+    prepared = None
+
+    @postfork
+    def connect():
+        global session, prepared
+        session = Cluster().connect()
+        prepared = session.prepare("SELECT release_version FROM system.local WHERE key=?")
+
+    app = Flask(__name__)
+
+    @app.route('/')
+    def server_version():
+        row = session.execute(prepared, ('local',))[0]
+        return row.release_version
+
+uWSGI provides a ``postfork`` hook you can use to create sessions and prepared statements after the child process forks.
+
+How do I trace a request?
+-------------------------
+Request tracing can be turned on for any request by setting ``trace=True`` in :meth:`.Session.execute_async`. View the results by waiting on the future, then :meth:`.ResponseFuture.get_query_trace`.
+Since tracing is done asynchronously to the request, this method polls until the trace is complete before querying data.
+
+.. code-block:: python
+
+    >>> future = session.execute_async("SELECT * FROM system.local", trace=True)
+    >>> result = future.result()
+    >>> trace = future.get_query_trace()
+    >>> for e in trace.events:
+    >>>     print e.source_elapsed, e.description
+
+    0:00:00.000077 Parsing select * from system.local
+    0:00:00.000153 Preparing statement
+    0:00:00.000309 Computing ranges to query
+    0:00:00.000368 Submitting range requests on 1 ranges with a concurrency of 1 (279.77142 rows per range expected)
+    0:00:00.000422 Submitted 1 concurrent range requests covering 1 ranges
+    0:00:00.000480 Executing seq scan across 1 sstables for (min(-9223372036854775808), min(-9223372036854775808))
+    0:00:00.000669 Read 1 live and 0 tombstone cells
+    0:00:00.000755 Scanned 1 rows and matched 1
+
+``trace`` is a :class:`QueryTrace` object.
+
+How do I determine the replicas for a query?
+----------------------------------------------
+With prepared statements, the replicas are obtained by ``routing_key``, based on current cluster token metadata:
+
+.. code-block:: python
+
+    >>> prepared = session.prepare("SELECT * FROM example.t WHERE key=?")
+    >>> bound = prepared.bind((1,))
+    >>> replicas = cluster.metadata.get_replicas(bound.keyspace, bound.routing_key)
+    >>> for h in replicas:
+    >>>   print h.address
+    127.0.0.1
+    127.0.0.2
+
+``replicas`` is a list of :class:`Host` objects.
+
+How does the driver manage request retries?
+-------------------------------------------
+By default, retries are managed by the :attr:`.Cluster.default_retry_policy` set on the session Cluster. It can also
+be specialized per statement by setting :attr:`.Statement.retry_policy`.
+
+Retries are presently attempted on the same coordinator, but this may change in the future.
+
+Please see :class:`.policies.RetryPolicy` for further details.

docs/index.rst

@@ -39,6 +39,9 @@ Contents
 :doc:`security`
     An overview of the security features of the driver.
 
+:doc:`faq`
+    A collection of Frequently Asked Questions
+
 .. toctree::
    :hidden:
 
@@ -51,9 +54,12 @@ Contents
    security
    user_defined_types
    object_mapper
+   faq
 
 Getting Help
 ------------
+Visit the :doc:`FAQ section <faq>` in this documentation.
+
 Please send questions to the `mailing list <https://groups.google.com/a/lists.datastax.com/forum/#!forum/python-driver-user>`_.
 
 Alternatively, you can use IRC.  Connect to the #datastax-drivers channel on irc.freenode.net.