Merge branch 'oss-next' into ngdg_master_ft

Author: aboudreault

CHANGELOG.rst

@@ -45,6 +45,7 @@ Bug Fixes
 * re-raising the CQLEngineException will fail on Python 3 (PYTHON-1166)
 * asyncio message chunks can be processed discontinuously (PYTHON-1185)
 * Reconnect attempts persist after downed node removed from peers (PYTHON-1181)
+* Connection fails to validate ssl certificate hostname when SSLContext.check_hostname is set (PYTHON-1186)
 
 Others
 ------

README.rst

@@ -72,7 +72,7 @@ Getting Help
 ------------
 Your best options for getting help with the driver are the
 `mailing list <https://groups.google.com/a/lists.datastax.com/forum/#!forum/python-driver-user>`_
-and the ``#datastax-drivers`` channel in the `DataStax Academy Slack <https://academy.datastax.com/slack>`_.
+and the `DataStax Community <https://community.datastax.com>`_.
 
 License
 -------

cassandra/connection.py

@@ -769,7 +769,14 @@ def factory(cls, endpoint, timeout, *args, **kwargs):
             return conn
 
     def _wrap_socket_from_context(self):
-        self._socket = self.ssl_context.wrap_socket(self._socket, **(self.ssl_options or {}))
+        ssl_options = self.ssl_options or {}
+        # PYTHON-1186: set the server_hostname only if the SSLContext has
+        # check_hostname enabled and it is not already provided by the EndPoint ssl options
+        if (self.ssl_context.check_hostname and
+                'server_hostname' not in ssl_options):
+            ssl_options = ssl_options.copy()
+            ssl_options['server_hostname'] = self.endpoint.address
+        self._socket = self.ssl_context.wrap_socket(self._socket, **ssl_options)
 
     def _initiate_connection(self, sockaddr):
         self._socket.connect(sockaddr)

docs/getting_started.rst

@@ -110,7 +110,6 @@ by executing a ``USE <keyspace>`` query:
     # or you can do this instead
     session.execute('USE users')
 
-
 Executing Queries
 -----------------
 Now that we have a :class:`.Session` we can begin to execute queries. The simplest
@@ -153,13 +152,45 @@ examples are equivalent:
 If you prefer another result format, such as a ``dict`` per row, you
 can change the :attr:`~.Session.row_factory` attribute.
 
-For queries that will be run repeatedly, you should use
-`Prepared statements <#prepared-statements>`_.
+As mentioned in our `Drivers Best Practices Guide <https://docs.datastax.com/en/devapp/doc/devapp/driversBestPractices.html#driversBestPractices__usePreparedStatements>`_,
+it is highly recommended to use `Prepared statements <#prepared-statement>`_ for your
+frequently run queries.
+
+.. _prepared-statement:
+
+Prepared Statements
+-------------------
+Prepared statements are queries that are parsed by Cassandra and then saved
+for later use.  When the driver uses a prepared statement, it only needs to
+send the values of parameters to bind.  This lowers network traffic
+and CPU utilization within Cassandra because Cassandra does not have to
+re-parse the query each time.
+
+To prepare a query, use :meth:`.Session.prepare()`:
+
+.. code-block:: python
+
+    user_lookup_stmt = session.prepare("SELECT * FROM users WHERE user_id=?")
+
+    users = []
+    for user_id in user_ids_to_query:
+        user = session.execute(user_lookup_stmt, [user_id])
+        users.append(user)
+
+:meth:`~.Session.prepare()` returns a :class:`~.PreparedStatement` instance
+which can be used in place of :class:`~.SimpleStatement` instances or literal
+string queries.  It is automatically prepared against all nodes, and the driver
+handles re-preparing against new nodes and restarted nodes when necessary.
+
+Note that the placeholders for prepared statements are ``?`` characters.  This
+is different than for simple, non-prepared statements (although future versions
+of the driver may use the same placeholders for both).
 
 Passing Parameters to CQL Queries
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-When executing non-prepared statements, the driver supports two forms of
-parameter place-holders: positional and named.
+Althought it is not recommended, you can also pass parameters to non-prepared
+statements. The driver supports two forms of parameter place-holders: positional
+and named.
 
 Positional parameters are used with a ``%s`` placeholder.  For example,
 when you execute:
@@ -376,34 +407,6 @@ in a :class:`~.SimpleStatement`:
         consistency_level=ConsistencyLevel.QUORUM)
     session.execute(query, ('John', 42))
 
-Prepared Statements
--------------------
-Prepared statements are queries that are parsed by Cassandra and then saved
-for later use.  When the driver uses a prepared statement, it only needs to
-send the values of parameters to bind.  This lowers network traffic
-and CPU utilization within Cassandra because Cassandra does not have to
-re-parse the query each time.
-
-To prepare a query, use :meth:`.Session.prepare()`:
-
-.. code-block:: python
-
-    user_lookup_stmt = session.prepare("SELECT * FROM users WHERE user_id=?")
-
-    users = []
-    for user_id in user_ids_to_query:
-        user = session.execute(user_lookup_stmt, [user_id])
-        users.append(user)
-
-:meth:`~.Session.prepare()` returns a :class:`~.PreparedStatement` instance
-which can be used in place of :class:`~.SimpleStatement` instances or literal
-string queries.  It is automatically prepared against all nodes, and the driver
-handles re-preparing against new nodes and restarted nodes when necessary.
-
-Note that the placeholders for prepared statements are ``?`` characters.  This
-is different than for simple, non-prepared statements (although future versions
-of the driver may use the same placeholders for both).
-
 Setting a Consistency Level with Prepared Statements
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 To specify a consistency level for prepared statements, you have two options.
@@ -434,3 +437,43 @@ level on that:
     user3_lookup = user_lookup_stmt.bind([user_id3])
     user3_lookup.consistency_level = ConsistencyLevel.ALL
     user3 = session.execute(user3_lookup)
+
+Speculative Execution
+^^^^^^^^^^^^^^^^^^^^^
+
+Speculative execution is a way to minimize latency by preemptively executing several
+instances of the same query against different nodes. For more details about this
+technique, see `Speculative Execution with DataStax Drivers <https://docs.datastax.com/en/devapp/doc/devapp/driversSpeculativeRetry.html>`_.
+
+To enable speculative execution:
+
+* Configure a :class:`~.policies.SpeculativeExecutionPolicy` with the ExecutionProfile
+* Mark your query as idempotent, which mean it can be applied multiple
+  times without changing the result of the initial application.
+  See `Query Idempotence <https://docs.datastax.com/en/devapp/doc/devapp/driversQueryIdempotence.html>`_ for more details.
+
+
+Example:
+
+.. code-block:: python
+
+    from cassandra.cluster import Cluster, ExecutionProfile, EXEC_PROFILE_DEFAULT
+    from cassandra.policies import ConstantSpeculativeExecutionPolicy
+    from cassandra.query import SimpleStatement
+
+    # Configure the speculative execution policy
+    ep = ExecutionProfile(
+        speculative_execution_policy=ConstantSpeculativeExecutionPolicy(delay=.5, max_attempts=10)
+    )
+    cluster = Cluster(..., execution_profiles={EXEC_PROFILE_DEFAULT: ep})
+    session = cluster.connect()
+
+    # Mark the query idempotent
+    query = SimpleStatement(
+        "UPDATE my_table SET list_col = [1] WHERE pk = 1",
+        is_idempotent=True
+    )
+
+    # Execute. A new query will be sent to the server every 0.5 second
+    # until we receive a response, for a max number attempts of 10.
+    session.execute(query)

docs/index.rst

@@ -100,7 +100,7 @@ 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 the `#datastax-drivers` channel in the DataStax Acadamy Slack to ask questions in real time.
+Alternatively, you can use the `DataStax Community <https://community.datastax.com>`_.
 
 Reporting Issues
 ----------------

docs/security.rst

@@ -69,6 +69,14 @@ To enable SSL with version 3.17.0 and higher, you will need to set :attr:`.Clust
 to a dict of options. These will be passed as kwargs to ``ssl.SSLContext.wrap_socket()``
 when new sockets are created.
 
+If you create your SSLContext using `ssl.create_default_context <https://docs.python.org/3/library/ssl.html#ssl.create_default_context>`_,
+be aware that SSLContext.check_hostname is set to True by default, so the hostname validation will be done
+by Python and not the driver. For this reason, we need to set the server_hostname at best effort, which is the
+resolved ip address. If this validation needs to be done against the FQDN, consider enabling it using the ssl_options
+as described in the following examples or implement your own :class:`~.connection.EndPoint` and
+:class:`~.connection.EndPointFactory`.
+
+
 The following examples assume you have generated your Cassandra certificate and
 keystore files with these intructions:
 

docs/user_defined_types.rst

@@ -9,12 +9,16 @@ new type through ``CREATE TYPE`` statements in CQL::
 
 Version 2.1 of the Python driver adds support for user-defined types.
 
-Registering a Class to Map to a UDT
------------------------------------
+Registering a UDT
+-----------------
 You can tell the Python driver to return columns of a specific UDT as
-instances of a class by registering them with your :class:`~.Cluster`
+instances of a class or a dict by registering them with your :class:`~.Cluster`
 instance through :meth:`.Cluster.register_user_type`:
 
+
+Map a Class to a UDT
+++++++++++++++++++++
+
 .. code-block:: python
 
     cluster = Cluster(protocol_version=3)
@@ -39,7 +43,29 @@ instance through :meth:`.Cluster.register_user_type`:
     # results will include Address instances
     results = session.execute("SELECT * FROM users")
     row = results[0]
-    print row.id, row.location.street, row.location.zipcode
+    print(row.id, row.location.street, row.location.zipcode)
+
+Map a dict to a UDT
++++++++++++++++++++
+
+.. code-block:: python
+
+    cluster = Cluster(protocol_version=3)
+    session = cluster.connect()
+    session.set_keyspace('mykeyspace')
+    session.execute("CREATE TYPE address (street text, zipcode int)")
+    session.execute("CREATE TABLE users (id int PRIMARY KEY, location frozen<address>)")
+
+    cluster.register_user_type('mykeyspace', 'address', dict)
+
+    # insert a row using a prepared statement and a tuple
+    insert_statement = session.prepare("INSERT INTO mykeyspace.users (id, location) VALUES (?, ?)")
+    session.execute(insert_statement, [0, ("123 Main St.", 78723)])
+
+    # results will include dict instances
+    results = session.execute("SELECT * FROM users")
+    row = results[0]
+    print(row.id, row.location['street'], row.location['zipcode'])
 
 Using UDTs Without Registering Them
 -----------------------------------
@@ -79,7 +105,7 @@ for the UDT:
     results = session.execute("SELECT * FROM users")
     first_row = results[0]
     address = first_row.location
-    print address  # prints "Address(street='123 Main St.', zipcode=78723)"
+    print(address)  # prints "Address(street='123 Main St.', zipcode=78723)"
     street = address.street
     zipcode = address.street