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/af1c579a Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/af1c579a Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/af1c579a Branch: refs/heads/TINKERPOP-1599 Commit: af1c579a8b99db1512d3714e94beda501b69d23e Parents: b711b5e Author: davebshow <davebs...@gmail.com> Authored: Wed Feb 15 18:26:08 2017 -0500 Committer: davebshow <davebs...@gmail.com> Committed: Fri Feb 17 11:42:24 2017 -0500 ---------------------------------------------------------------------- CHANGELOG.asciidoc | 5 ++ .../src/reference/gremlin-applications.asciidoc | 71 ++++++++++++++++++++ .../upgrade/release-3.2.x-incubating.asciidoc | 30 ++++++++- 3 files changed, 103 insertions(+), 3 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/af1c579a/CHANGELOG.asciidoc ---------------------------------------------------------------------- diff --git a/CHANGELOG.asciidoc b/CHANGELOG.asciidoc index de78d24..744ffee 100644 --- a/CHANGELOG.asciidoc +++ b/CHANGELOG.asciidoc @@ -29,6 +29,11 @@ TinkerPop 3.2.5 (Release Date: NOT OFFICIALLY RELEASED YET) * Refactor `SparkContext` handler to support external kill and stop operations. * Fixed an optimization bug in `LazyBarrierStrategy` around appending barriers to the end of a `Traversal`. * `TraverserIterator` in GremlinServer is smart to try and bulk traversers prior to network I/O. +* 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/af1c579a/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/af1c579a/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 1247433..6bfc028 100644 --- a/docs/src/upgrade/release-3.2.x-incubating.asciidoc +++ b/docs/src/upgrade/release-3.2.x-incubating.asciidoc @@ -32,6 +32,33 @@ Please see the link:https://github.com/apache/tinkerpop/blob/3.2.5/CHANGELOG.asc 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] + Upgrading for Providers ~~~~~~~~~~~~~~~~~~~~~~~ @@ -45,9 +72,6 @@ some `ProviderStrategies`. Most likely not, but just be aware. See: link:https://issues.apache.org/jira/browse/TINKERPOP-1627[TINKERPOP-1627] -TinkerGraph Deserialization -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - TinkerPop 3.2.4 ---------------
