Merge branch 'oss-next' of github.com:riptano/python-driver into oss-next

Author: aboudreault

README-dev.rst

@@ -26,7 +26,7 @@ Releasing
     # Download all wheels from the jfrog repository and copy them in
     # the dist/ directory
     cp /path/to/wheels/*.whl dist/
- 
+
     # Upload all files
     twine upload dist/*
 
@@ -128,67 +128,34 @@ web servers, use the SimpleHTTPServer module::
 
 Then, browse to `localhost:8000 <http://localhost:8000>`_.
 
+Tests
+=====
 
-Running the Tests
-=================
-In order for the extensions to be built and used in the test, run::
-
-    nosetests
-
-You can run a specific test module or package like so::
+Running Unit Tests
+------------------
+Unit tests can be run like so::
 
     nosetests -w tests/unit/
 
 You can run a specific test method like so::
 
     nosetests -w tests/unit/test_connection.py:ConnectionTest.test_bad_protocol_version
 
-Seeing Test Logs in Real Time
------------------------------
-Sometimes it's useful to output logs for the tests as they run::
-
-    nosetests -w tests/unit/ --nocapture --nologcapture
-
-Use tee to capture logs and see them on your terminal::
-
-    nosetests -w tests/unit/ --nocapture --nologcapture 2>&1 | tee test.log
-
-Specifying a Cassandra/DSE Version for Integration Tests
-----------------------------------------------------
-You can specify a cassandra version with the ``CASSANDRA_VERSION`` or ``DSE_VERSION` environment variable::
+Running Integration Tests
+-------------------------
+In order to run integration tests, you must specify a version to run using the ``CASSANDRA_VERSION`` or ``DSE_VERSION`` environment variable::
 
     CASSANDRA_VERSION=2.0.9 nosetests -w tests/integration/standard
-    DSE_VERSION=6.7.4 nosetests -w tests/integration/standard
-
-You can also specify a cassandra directory (to test unreleased versions)::
-
-    CASSANDRA_DIR=/home/thobbs/cassandra nosetests -w tests/integration/standard
-
-For this to work with DSE, you have to build it before. Once the appropriate commit is checked out, inside the ``bdp`` folder:
 
-	./gradlew clean dist
+Or you can specify a cassandra directory (to test unreleased versions)::
 
-Running the advanced authentication tests for DSE
--------------------------------------------------
-These tests are in the file ``tests/integration/advanced/test_auth.py``. These tests are run the same way
-as the rest but first the we have to set the variable ADS_HOME:
+    CASSANDRA_DIR=/home/thobbs/cassandra nosetests -w tests/integration/standard/
 
-	git clone https://github.com/riptano/testeng-devtools.git
-	cd testeng-devtools/EmbeddedAds
-	mvn clean install
-	cp target/embedded-ads-1.0.1-SNAPSHOT-*.jar embedded-ads.jar
-	export ADS_HOME=`pwd`
+Specifying the usage of an already running Cassandra cluster
+------------------------------------------------------------
+The test will start the appropriate Cassandra clusters when necessary  but if you don't want this to happen because a Cassandra cluster is already running the flag ``USE_CASS_EXTERNAL`` can be used, for example::
 
-After this we can run the tests normally from the appropriate folder:
-
-	DSE_VERSION=6.7.4 nosetests -w tests/integration/advanced/test_auth.py
-
-Specifying the usage of an already running cluster
---------------------------------------------------
-The test will start the appropriate Cassandra clusters when necessary  but if you don't want this to happen
-because a Cassandra cluster is already running the flag ``USE_CASS_EXTERNAL`` can be used, for example: 
-
-	USE_CASS_EXTERNAL=1 python setup.py nosetests -w tests/integration/standard
+    USE_CASS_EXTERNAL=1 CASSANDRA_VERSION=2.0.9 nosetests -w tests/integration/standard
 
 Specify a Protocol Version for Tests
 ------------------------------------
@@ -197,31 +164,31 @@ it with the ``PROTOCOL_VERSION`` environment variable::
 
     PROTOCOL_VERSION=3 nosetests -w tests/integration/standard
 
+Seeing Test Logs in Real Time
+-----------------------------
+Sometimes it's useful to output logs for the tests as they run::
+
+    nosetests -w tests/unit/ --nocapture --nologcapture
+
+Use tee to capture logs and see them on your terminal::
+
+    nosetests -w tests/unit/ --nocapture --nologcapture 2>&1 | tee test.log
+
 Testing Multiple Python Versions
 --------------------------------
-If you want to test all of python 2.7, 3.4, 3.5, 3.6 and pypy, use tox (this is what
+If you want to test all of python 2.7, 3.4, 3.5, 3.6, 3.7, and pypy, use tox (this is what
 TravisCI runs)::
 
     tox
 
-By default, tox only runs the unit tests because I haven't put in the effort
-to get the integration tests to run on TravicCI.  However, the integration
-tests should work locally.  To run them, edit the following line in tox.ini::
-
-    commands = {envpython} setup.py build_ext --inplace nosetests --verbosity=2 tests/unit/
-
-and change ``tests/unit/`` to ``tests/``.
+By default, tox only runs the unit tests.
 
 Running the Benchmarks
 ======================
 There needs to be a version of cassandra running locally so before running the benchmarks, if ccm is installed:
 
 	ccm create benchmark_cluster -v 3.0.1 -n 1 -s
 
-If testing against DSE:
-
-    ccm create 6.7.4 --dse [email protected] --dse-password=your_password -v 6.7.4 -n 1 -s
-
 To run the benchmarks, pick one of the files under the ``benchmarks/`` dir and run it::
 
     python benchmarks/future_batches.py
@@ -242,7 +209,7 @@ name to specify the built version::
 
     python setup.py egg_info -b-`git rev-parse --short HEAD` sdist --formats=zip
 
-The file (``dist/cassandra-driver-<version spec>.zip``) is packaged with Cassandra in ``cassandra/lib/cassandra-driver-internal-only.zip``.
+The file (``dist/cassandra-driver-<version spec>.zip``) is packaged with Cassandra in ``cassandra/lib/cassandra-driver-internal-only*zip``.
 
 Releasing an EAP
 ================
@@ -266,4 +233,4 @@ An EAP release is only uploaded on a private server and it is not published on p
 
     python setup.py doc
 
-* Upload the docs on the EAP download server.
+* Upload the docs on the EAP download server.

README.rst

@@ -4,12 +4,10 @@ DataStax Python Driver for Apache Cassandra
 .. image:: https://travis-ci.org/datastax/python-driver.png?branch=master
    :target: https://travis-ci.org/datastax/python-driver
 
-A modern, `feature-rich <https://github.com/datastax/python-driver#features>`_ and highly-tunable Python client library for Apache Cassandra (2.1+) using exclusively Cassandra's binary protocol and Cassandra Query Language v3.
+A modern, `feature-rich <https://github.com/datastax/python-driver#features>`_ and highly-tunable Python client library for Apache Cassandra (2.1+) and DataStax Enterprise (4.7+) using exclusively Cassandra's binary protocol and Cassandra Query Language v3.
 
 The driver supports Python 2.7, 3.4, 3.5, 3.6 and 3.7.
 
-If you require compatibility with DataStax Enterprise, use the `DataStax Enterprise Python Driver <http://docs.datastax.com/en/developer/python-dse-driver/>`_.
-
 **Note:** DataStax products do not support big-endian systems.
 
 Feedback Requested
@@ -27,6 +25,11 @@ Features
 * Configurable `load balancing <http://datastax.github.io/python-driver/api/cassandra/policies.html#load-balancing>`_ and `retry policies <http://datastax.github.io/python-driver/api/cassandra/policies.html#retrying-failed-operations>`_
 * `Concurrent execution utilities <http://datastax.github.io/python-driver/api/cassandra/concurrent.html>`_
 * `Object mapper <http://datastax.github.io/python-driver/object_mapper.html>`_
+* DSE Graph execution API
+* DSE Geometric type serialization
+* DSE PlainText and GSSAPI authentication
+
+A fluent API extension for DSE Graph is available in the ``dse-graph`` package. For more information, see `the documentation here <http://docs.datastax.com/en/developer/python-dse-graph/>`_.
 
 Installation
 ------------

docs/CHANGELOG.rst

@@ -0,0 +1,5 @@
+*********
+CHANGELOG 
+*********
+
+.. include:: ../CHANGELOG.rst

docs/conf.py

@@ -153,7 +153,7 @@
 #html_domain_indices = True
 
 # If false, no index is generated.
-#html_use_index = True
+html_use_index = False
 
 # If true, the index is split into individual pages for each letter.
 #html_split_index = False
@@ -223,5 +223,5 @@
 # (source start file, name, description, authors, manual section).
 man_pages = [
     ('index', 'cassandra-driver', u'Cassandra Driver Documentation',
-     [u'Tyler Hobbs'], 1)
+     [u'DataStax'], 1)
 ]

docs/execution_profiles.rst

@@ -121,7 +121,7 @@ New profiles can be added constructing from scratch, or deriving from default:
     locked_execution = ExecutionProfile(load_balancing_policy=WhiteListRoundRobinPolicy(['127.0.0.1']))
     node1_profile = 'node1_whitelist'
     cluster.add_execution_profile(node1_profile, locked_execution)
-    
+
     for _ in cluster.metadata.all_hosts():
         print session.execute(local_query, execution_profile=node1_profile)[0]
 
@@ -141,7 +141,7 @@ We also have the ability to pass profile instances to be used for execution, but
 .. code:: python
 
     from cassandra.query import tuple_factory
-    
+
     tmp = session.execution_profile_clone_update('node1', request_timeout=100, row_factory=tuple_factory)
 
     print session.execute(local_query, execution_profile=tmp)[0]

docs/geo_types.rst

@@ -0,0 +1,39 @@
+DSE Geometry Types
+==================
+This section shows how to query and work with the geometric types provided by DSE.
+
+These types are enabled implicitly by creating the Session from :class:`cassandra.cluster.Cluster`.
+This module implicitly registers these types for use in the driver. This extension provides
+some simple representative types in :mod:`cassandra.util` for inserting and retrieving data::
+
+    from cassandra.cluster import Cluster
+    from cassandra.util import Point, LineString, Polygon
+    session = Cluster().connect()
+
+    session.execute("INSERT INTO ks.geo (k, point, line, poly) VALUES (%s, %s, %s, %s)",
+                    0, Point(1, 2), LineString(((1, 2), (3, 4))), Polygon(((1, 2), (3, 4), (5, 6))))
+
+Queries returning geometric types return the :mod:`dse.util` types. Note that these can easily be used to construct
+types from third-party libraries using the common attributes::
+
+    from shapely.geometry import LineString
+    shapely_linestrings = [LineString(res.line.coords) for res in session.execute("SELECT line FROM ks.geo")]
+
+For prepared statements, shapely geometry types can be used interchangeably with the built-in types because their
+defining attributes are the same::
+
+    from shapely.geometry import Point
+    prepared = session.prepare("UPDATE ks.geo SET point = ? WHERE k = ?")
+    session.execute(prepared, (0, Point(1.2, 3.4)))
+
+In order to use shapely types in a CQL-interpolated (non-prepared) query, one must update the encoder with those types, specifying
+the same string encoder as set for the internal types::
+
+    from cassandra import util
+    from shapely.geometry import Point, LineString, Polygon
+
+    encoder_func = session.encoder.mapping[util.Point]
+    for t in (Point, LineString, Polygon):
+        session.encoder.mapping[t] = encoder_func
+
+    session.execute("UPDATE ks.geo SET point = %s where k = %s", (0, Point(1.2, 3.4)))

docs/getting_started.rst

@@ -11,6 +11,7 @@ instance of :class:`~.Cluster` for each Cassandra cluster you want to interact
 with.
 
 The simplest way to create a :class:`~.Cluster` is like this:
+First, make sure you have the Cassandra driver properly :doc:`installed <installation>`.
 
 .. code-block:: python
 
@@ -39,16 +40,48 @@ behavior in some other way, this is the place to do it:
 
 .. code-block:: python
 
-    from cassandra.cluster import Cluster
-    from cassandra.policies import DCAwareRoundRobinPolicy
+    from cassandra.cluster import Cluster, ExecutionProfile, EXEC_PROFILE_DEFAULT
+    from cassandra.query import tuple_factory
+
+    profile = ExecutionProfile(row_factory=tuple_factory)
+    cluster = Cluster(execution_profiles={EXEC_PROFILE_DEFAULT: profile})
+    session = cluster.connect()
+
+    print session.execute("SELECT release_version FROM system.local")[0]
 
-    cluster = Cluster(
-        ['10.1.1.3', '10.1.1.4', '10.1.1.5'],
-        load_balancing_policy=DCAwareRoundRobinPolicy(local_dc='US_EAST'),
-        port=9042)
+Profiles are passed in by ``execution_profiles`` dict.
 
+In this case we can construct the base ``ExecutionProfile`` passing all attributes:
+
+.. code-block:: python
+
+    from cassandra.cluster import Cluster, ExecutionProfile, EXEC_PROFILE_DEFAULT
+    from cassandra.policies import WhiteListRoundRobinPolicy, DowngradingConsistencyRetryPolicy
+    from cassandra.query import tuple_factory
+
+    profile = ExecutionProfile(
+        load_balancing_policy=WhiteListRoundRobinPolicy(['127.0.0.1']),
+        retry_policy=DowngradingConsistencyRetryPolicy(),
+        consistency_level=ConsistencyLevel.LOCAL_QUORUM,
+        serial_consistency_level=ConsistencyLevel.LOCAL_SERIAL,
+        request_timeout=15,
+        row_factory=tuple_factory
+    )
+    cluster = Cluster(execution_profiles={EXEC_PROFILE_DEFAULT: profile})
+    session = cluster.connect()
+
+    print session.execute("SELECT release_version FROM system.local")[0]
+
+Users are free to setup additional profiles to be used by name:
+
+.. code-block:: python
+
+    profile_long = ExecutionProfile(request_timeout=30)
+    cluster = Cluster(execution_profiles={'long': profile_long})
+    session = cluster.connect()
+    session.execute(statement, execution_profile='long')
 
-You can find a more complete list of options in the :class:`~.Cluster` documentation.
+Also, parameters passed to ``Session.execute`` or attached to ``Statement``\s are still honored as before.
 
 Instantiating a :class:`~.Cluster` does not actually connect us to any nodes.
 To establish connections and begin executing queries we need a
@@ -328,10 +361,8 @@ replicas of the data you are interacting with need to respond for
 the query to be considered a success.
 
 By default, :attr:`.ConsistencyLevel.LOCAL_ONE` will be used for all queries.
-You can specify a different default for the session on :attr:`.Session.default_consistency_level`
-if the cluster is configured in legacy mode (not using execution profiles). Otherwise this can
-be done by setting the :attr:`.ExecutionProfile.consistency_level` for the execution profile with key
-:data:`~.cluster.EXEC_PROFILE_DEFAULT`.
+You can specify a different default by setting the :attr:`.ExecutionProfile.consistency_level`
+for the execution profile with key :data:`~.cluster.EXEC_PROFILE_DEFAULT`.
 To specify a different consistency level per request, wrap queries
 in a :class:`~.SimpleStatement`: