updated changlog, added docs
Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/44a20fdc Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/44a20fdc Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/44a20fdc Branch: refs/heads/TINKERPOP-1599 Commit: 44a20fdcf31b4eb9db5d30b25e8712b160bc3603 Parents: 351513e Author: davebshow <[email protected]> Authored: Wed Feb 15 18:26:08 2017 -0500 Committer: davebshow <[email protected]> Committed: Wed Feb 15 18:30:39 2017 -0500 ---------------------------------------------------------------------- CHANGELOG.asciidoc | 4 ++ .../src/reference/gremlin-applications.asciidoc | 71 ++++++++++++++++++++ .../upgrade/release-3.2.x-incubating.asciidoc | 35 ++++++++++ 3 files changed, 110 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/44a20fdc/CHANGELOG.asciidoc ---------------------------------------------------------------------- diff --git a/CHANGELOG.asciidoc b/CHANGELOG.asciidoc index e3c78f9..f678cb9 100644 --- a/CHANGELOG.asciidoc +++ b/CHANGELOG.asciidoc @@ -27,7 +27,11 @@ TinkerPop 3.2.5 (Release Date: NOT OFFICIALLY RELEASED YET) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * Refactor `SparkContext` handler to support external kill and stop operations. +* Improved Gremlin-Python driver implementation by adding a threaded client with basic connection pooling and support for pluggable websocket clients. +Improvements +^^^^^^^^^^^^ +TINKERPOP-1599 implement real gremlin-python driver [[release-3-2-4]] TinkerPop 3.2.4 (Release Date: February 8, 2017) http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/44a20fdc/docs/src/reference/gremlin-applications.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/reference/gremlin-applications.asciidoc b/docs/src/reference/gremlin-applications.asciidoc index 7ca4efd..ece0a82 100644 --- a/docs/src/reference/gremlin-applications.asciidoc +++ b/docs/src/reference/gremlin-applications.asciidoc @@ -762,6 +762,77 @@ The above code demonstrates using the `TitanIoRegistry` which is an `IoRegistry` what classes (from Titan in this case) to auto-register during serialization. Gremlin Server roughly uses this same approach when it configures it's serializers, so using this same model will ensure compatibility when making requests. +[[connecting-via-python]] +Connecting via Python +~~~~~~~~~~~~~~~~~~~~~ + +[source,python] +---- +pip install gremlinpython +---- + +TinkerPop3 also includes a client for Python-based applications. It is referred to as Gremlin-Python Driver. +The `Client` class implementation/interface is based on the Java Driver, with some restrictions. Most notably, +Gremlin-Python does not yet implement the `Cluster` class. Instead, `Client` is instantiated directly. +Usage is as follows: + +[source,python] +---- +from gremlin_python.driver import client <1> +client = client.Client('ws://localhost:8182/gremlin', 'g') <2> +---- + +<1> Import the Gremlin-Python `client` module. +<2> Opens a reference to `localhost` - note that there are various configuration options that can be passed +to the `Client` object upon instantiation as keyword arguments. + +Once a `Client` instance is ready, it is possible to issue some Gremlin: + +[source,python] +---- +result_set = client.submit("[1,2,3,4]") <1> +future_results = result_set.all() <2> +results = future_results.result() <3> +assert results == [1, 2, 3, 4] <4> + +future_result_set = client.submitAsync("[1,2,3,4]") <5> +result_set = future_result_set.result() <6> +result = result_set.one() <7> +assert results == [1, 2, 3, 4] <8> +assert result_set.done.done() <9> +---- + +<1> Submit a script that simply returns a `List` of integers. This method blocks until the request is written to +the server and a `ResultSet` is constructed. +<2> Even though the `ResultSet` is constructed, it does not mean that the server has sent back the results (or even +evaluated the script potentially). The `ResultSet` is just a holder that is awaiting the results from the server. The `all` method +returns a `concurrent.futures.Future` that resolves to a list when it is complete. +<3> Block until the the script is evaluated and results are sent back by the server. +<4> Verify the result. +<5> Submit the same script to the server but don't block. +<6> Wait until request is written to the server and `ResultSet` is constructed. +<7> Read a single result off the result stream. +<8> Again, verify the result. +<9> Verify that the all results have been read and stream is closed. + +Configuration +^^^^^^^^^^^^^ + +The following table describes the various configuration options for the Gremlin-Python Driver. They +can be passed to the `Client` instance as keyword arguments: + +[width="100%",cols="3,10,^2",options="header"] +|========================================================= +|Key |Description |Default +|protocol_factory |A callable that returns an instance of `AbstractBaseProtocol`. |`gremlin_python.driver.protocol.GremlinServerWSProtocol` +|transport_factory |A callable that returns an instance of `AbstractBaseTransport`. |`gremlin_python.driver.tornado.transport.TornadoTransport` +|pool_size |The number of connections used by the pool. |4 +|max_workers |Maximum number of worker threads. |Number of CPUs * 5 +|message_serializer |The message serializer implementation.|`gremlin_python.driver.serializer.GraphSONMessageSerializer` +|password |The password to submit on requests that require authentication. |"" +|username |The username to submit on requests that require authentication. |"" +|========================================================= + Connecting via REST ~~~~~~~~~~~~~~~~~~~ http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/44a20fdc/docs/src/upgrade/release-3.2.x-incubating.asciidoc ---------------------------------------------------------------------- diff --git a/docs/src/upgrade/release-3.2.x-incubating.asciidoc b/docs/src/upgrade/release-3.2.x-incubating.asciidoc index c199238..c3c43e8 100644 --- a/docs/src/upgrade/release-3.2.x-incubating.asciidoc +++ b/docs/src/upgrade/release-3.2.x-incubating.asciidoc @@ -22,6 +22,41 @@ image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/ima *Nine Inch Gremlins* +TinkerPop 3.2.5 +--------------- + +*Release Date:* + +Upgrading for Users +~~~~~~~~~~~~~~~~~~~ + +Gremlin-Python Driver +^^^^^^^^^^^^^^^^^^^^^ +Gremlin-Python now offers a more complete driver implementation that uses connection pooling and +the Python `concurrent.futures` module to provide asynchronous I/0 using threading. The default underlying +websocket client implementation is still provided by Tornado, but it is trivial to plug in another client by +defining the `Transport` interface. + +Using the `DriverRemoteConnection` class is the exact same as in previous versions; however, +`DriverRemoteConnection` now uses the new `Client` class to submit messages to the server. + +The `Client` class implementation/interface is based on the Java Driver, with some restrictions. +Most notably, Gremlin-Python does not yet implement the `Cluster` class. Instead, `Client` is +instantiated directly. Usage is as follows: + +[source,python] +---- +from gremlin_python.driver import client + +client = client.Client('ws://localhost:8182/gremlin', 'g') +result_set = client.submit('1 + 1') +future_results = result_set.all() # returns a concurrent.futures.Future +results = future_results.result() # returns a list +assert results == [2] +---- + +See: link:https://issues.apache.org/jira/browse/TINKERPOP-1599[TINKERPOP-1599] + TinkerPop 3.2.4 ---------------
