You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tinkerpop.apache.org by ok...@apache.org on 2016/04/21 19:22:12 UTC

incubator-tinkerpop git commit: one more run through -- tessted all the code chunks again (found a bug in the Jython section -- phew. fixed). Added some text about gremlin-lang-driver and gremlin-lang naming conventions. A few more code call outs, but no

Repository: incubator-tinkerpop
Updated Branches:
  refs/heads/TINKERPOP-1232 343a34bc6 -> adce6cfad


one more run through -- tessted all the code chunks again (found a bug in the Jython section -- phew. fixed). Added some text about gremlin-lang-driver and gremlin-lang naming conventions. A few more code call outs, but not as many as I would like.


Project: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/commit/adce6cfa
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/tree/adce6cfa
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/diff/adce6cfa

Branch: refs/heads/TINKERPOP-1232
Commit: adce6cfada83f1593a3fda13f8dcfac579d2fcc5
Parents: 343a34b
Author: Marko A. Rodriguez <ok...@gmail.com>
Authored: Thu Apr 21 11:22:16 2016 -0600
Committer: Marko A. Rodriguez <ok...@gmail.com>
Committed: Thu Apr 21 11:22:16 2016 -0600

----------------------------------------------------------------------
 .../gremlin-language-variants/index.asciidoc    |  44 ++--
 docs/static/resources/gremlin-jython.py         | 227 ++++++++++---------
 2 files changed, 145 insertions(+), 126 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/adce6cfa/docs/src/tutorials/gremlin-language-variants/index.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/tutorials/gremlin-language-variants/index.asciidoc b/docs/src/tutorials/gremlin-language-variants/index.asciidoc
index 4dc2aed..b35a671 100644
--- a/docs/src/tutorials/gremlin-language-variants/index.asciidoc
+++ b/docs/src/tutorials/gremlin-language-variants/index.asciidoc
@@ -331,7 +331,7 @@ pythonClass.append("from org.apache.tinkerpop.gremlin.process.traversal.dsl.grap
 //////////////////////////
 // GraphTraversalSource //
 //////////////////////////
-methods = GraphTraversalSource.getMethods().collect{methodMap[it.name]} as Set; []
+methods = GraphTraversalSource.getMethods().collect{it.name} as Set; []
 pythonClass.append(
 """class JythonGraphTraversalSource(object):
   def __init__(self, traversalSource):
@@ -416,7 +416,7 @@ methods.each{ method ->
 pythonClass.append("\n\n")
 
 // save to a python file
-file = new File("/usr/local/apache-gremlin-console-x.y.z-standalone/lib/gremlin-jython.py")
+file = new File("/tmp/gremlin-jython.py")                                    //// <6>
 file.delete()
 pythonClass.eachLine{ file.append(it + "\n") }
 ----
@@ -426,6 +426,7 @@ pythonClass.eachLine{ file.append(it + "\n") }
 <3> Use Java reflection to get all the methods of `GraphTraversal`.
 <4> If the method is a fluent traversal-method, then mutate the underlying/wrapped `GraphTraversal` instance accordingly.
 <5> If the method is not a fluent traversal-method, return the result of applying the method.
+<6> Save the string representation of the Jython source code to `gremlin-jython.py`.
 
 From the Jython console, `gremlin-jython.py` is loaded and a complete Gremlin language variant is born: **Gremlin-Jython**.
 The generated file is available at link:../../resources/gremlin-jython.py[gremlin-jython.py].
@@ -435,7 +436,8 @@ The generated file is available at link:../../resources/gremlin-jython.py[gremli
 Jython 2.7.0 (default:9987c746f838, Apr 29 2015, 02:25:11)
 [Java HotSpot(TM) 64-Bit Server VM (Oracle Corporation)] on java1.8.0_40
 Type "help", "copyright", "credits" or "license" for more information.
->>> execfile("/usr/local/apache-gremlin-console-x.y.z-standalone/lib/gremlin-jython.py")
+>>> execfile("/tmp/gremlin-jython.py")
+>>> from org.apache.tinkerpop.gremlin.tinkergraph.structure import TinkerFactory
 >>> graph = TinkerFactory.createModern()
 >>> g = JythonGraphTraversalSource(graph.traversal())
 # using the Gremlin-Jython __getattr__ and __getitem__ extensions and anonymous traversals
@@ -460,6 +462,12 @@ The interested reader can solve the aforementioned problems as a training exerci
 * `__` is always required for anonymous traversals and thus, `repeat(__.both())` can not be replaced by `repeat(both())`.
 ** By placing the `@staticmethods` outside of the `__` Jython class, the methods would be globally scoped (analogous to `import static` in Java).
 
+NOTE: Another technique that can be leveraged in most link:https://en.wikipedia.org/wiki/Dynamic_programming_language[dynamic languages]
+is to use meta-programming and intercept all method calls to the variant's traversal classes. From there, the name of the
+method that was called, along with its parameters, are used to dynamically construct a method call to the wrapped traversals.
+In this way, there is no need to create a wrapper method for each method in `GraphTraversalSource`, `GraphTraversal`, and `__`.
+The drawback of this technique is that not all methods are fluent and those that are not, might need special handling.
+Moreover, runtime reflection is typically not efficient.
 
 [[using-python-and-gremlin-server]]
 Using Python and GremlinServer
@@ -626,20 +634,27 @@ methods.each{ method ->
 pythonClass.append("\n\n")
 
 // save to a python file
-file = new File("/usr/local/apache-gremlin-console-x.y.z-standalone/lib/gremlin-python.py")
+file = new File("/tmp/gremlin-python.py")                                                //// <3>
 file.delete()
 pythonClass.eachLine{ file.append(it + "\n") }
 ----
 
 <1> The `Helper` class contains static methods that are generally useful to the other classes. This could have been a separate file, but was included in the Groovy script so that the tutorial's code is consolidated.
 <2> `toList()`'s method `def` is not generated programmatically, but instead is hardcoded and uses the gremlinclient driver to communicate with GremlinServer.
+<3> Save the string representation of the Python source code to `gremlin-python.py`.
 
 When the above Groovy script is evaluated in GremlinConsole, **Gremlin-Python** is born.
 The generated file is available at link:../../resources/gremlin-python.py[gremlin-python.py]. Now, from any Python
 virtual machine (not just Jython), Gremlin traversals can be expressed in native Python and a legal Gremlin-Groovy
 string is created behind the scenes.
 
-Be sure that GremlinServer is running and has a GraphSON endpoint. The following serializers were added to `conf/gremlin-server-modern.yaml`.
+NOTE: The string that is generated for submission to a GremlinServer or `RemoteConnection` does not have to be a
+Gremlin-Groovy string. However, it must be a string that has a respective `ScriptEngine` that is enabled on the remote
+location. It is recommended that a Gremlin-Groovy string be constructed as Gremlin-Groovy is maintained by
+Apache TinkerPop and is guaranteed to always be aligned with Gremlin-Java.
+
+Be sure that GremlinServer is running and has a link:http://tinkerpop.apache.org/docs/x.y.z/reference/#graphson-reader-writer[GraphSON]
+endpoint. The following serializers were added to `conf/gremlin-server-modern.yaml`.
 
 [source,yaml]
 - { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerGremlinV1d0, config: { useMapperFromGraph: graph }} # application/vnd.gremlin-v1.0+json
@@ -682,7 +697,8 @@ $ bin/gremlin-server.sh conf/gremlin-server-modern.yaml
 Python 2.7.2 (default, Oct 11 2012, 20:14:37)
 [GCC 4.2.1 Compatible Apple Clang 4.0 (tags/Apple/clang-418.0.60)] on darwin
 Type "help", "copyright", "credits" or "license" for more information.
->>> execfile("/usr/local/apache-gremlin-console-x.y.z-standalone/lib/gremlin-python.py")
+>>> execfile("/tmp/gremlin-python.py")
+# PythonGraphTraversalSource requires a GremlinServer endpoint and a traversal alias
 >>> g = PythonGraphTraversalSource("ws://localhost:8182/", "g")
 >>> g
 graphtraversalsource[ws://localhost:8182/, g]
@@ -709,11 +725,6 @@ graphtraversalsource[ws://localhost:8182/, g.withComputer()]
 >>>
 ----
 
-NOTE: The string that is generated for submission to a GremlinServer or `RemoteConnection` does not have to be a
-Gremlin-Groovy string. However, it must be a string that has a respective `ScriptEngine` that is enabled on the remote
-location. It is recommended that a Gremlin-Groovy string be constructed as Gremlin-Groovy is maintained by
-Apache TinkerPop and is guaranteed to always be aligned with Gremlin-Java.
-
 Finally, for the sake of brevity, Gremlin-Python is simple and as such, incurs a few peculiarities that the interested
 reader may want to remedy as an exercise.
 
@@ -734,6 +745,11 @@ this dual-language bridge are provided.
 * If the host language does not use dot-notion for method chaining, then its method chaining convention should be used instead of going the route of operator overloading. For instance, a Gremlin-PHP implementation should do `$g->V()->out()`.
 * If a programming language does not support method overloading, then varargs and type introspection should be used. In Gremlin-Python, `*args` does just this and that is why there are not 200 methods off of `PythonGraphTraversal`.
 
+As stated in <<language-drivers-vs-language-variants,"Language Drivers vs. Language Variants">>, drivers and variants should
+be separate libraries. A proposed naming convention for each library type is `gremlin-<language>-driver` and
+`gremlin-<language>`. Unfortunately, numerous drivers and languages already exist for Gremlin that don't use this convention.
+However, moving forward, it might be good to be explicit in the naming so its obvious to users what is what.
+
 Finally, note that Gremlin-Jython and Gremlin-Python (as presented in this tutorial) were only manually tested. This
 means that there are most likely errors in the translation and thus, some traversals may break. A future addition to this
 tutorial will explain how to leverage TinkerPop's `ProcessStandardSuite` and `ProcessComputerSuite` to test not only
@@ -743,11 +759,11 @@ semantics will be validated and deemed an accurate representation of Gremlin-Jav
 Conclusion
 ----------
 
-Gremlin is a simple language because it relies two fundamental programming language constructs: function composition
+Gremlin is a simple language because it uses two fundamental programming language constructs: function composition
 and function nesting. Because of this foundation, it is relatively easy to implement Gremlin in any modern programming
 language. Two ways of doing this were presented in this tutorial. One using Jython (on the JVM) and one using Python
 (on CPython). It is strongly recommended that language variant designers leverage (especially when not on the JVM)
-leverage the reflection-based source code generation technique presented. This method ensures that the language
+the reflection-based source code generation technique presented. This method ensures that the language
 variant is always in sync with the corresponding Apache TinkerPop Gremlin-Java release version. Moreover, it reduces
-the chances of having missing methods or poorly implemented methods. While Gremlin is simple, there are nearly 200
+the chance of missing methods or creating poorly implemented methods. While Gremlin is simple, there are nearly 200
 steps in `GraphTraversal` and thus, its complexity is realized in the diversity of the atomic step operations it supports.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/adce6cfa/docs/static/resources/gremlin-jython.py
----------------------------------------------------------------------
diff --git a/docs/static/resources/gremlin-jython.py b/docs/static/resources/gremlin-jython.py
index c04b411..41d31ee 100644
--- a/docs/static/resources/gremlin-jython.py
+++ b/docs/static/resources/gremlin-jython.py
@@ -15,6 +15,8 @@ See the License for the specific language governing permissions and
 limitations under the License.
 '''
 
+from org.apache.tinkerpop.gremlin.process.traversal import *
+from org.apache.tinkerpop.gremlin.structure import *
 from org.apache.tinkerpop.gremlin.process.traversal.dsl.graph import __ as anon
 
 class JythonGraphTraversalSource(object):
@@ -31,12 +33,8 @@ class JythonGraphTraversalSource(object):
     return JythonGraphTraversal(self.traversalSource.V(*args))
   def E(self, *args):
     return JythonGraphTraversal(self.traversalSource.E(*args))
-  def getStrategies(self, *args):
-    return self.traversalSource.getStrategies(*args)
-  def addV(self, *args):
-    return JythonGraphTraversal(self.traversalSource.addV(*args))
-  def getGraph(self, *args):
-    return self.traversalSource.getGraph(*args)
+  def build(self, *args):
+    return self.traversalSource.build(*args)
   def withSack(self, *args):
     self.traversalSource = self.traversalSource.withSack(*args)
     return self
@@ -62,10 +60,14 @@ class JythonGraphTraversalSource(object):
     return self
   def standard(self, *args):
     return self.traversalSource.standard(*args)
-  def build(self, *args):
-    return self.traversalSource.build(*args)
   def inject(self, *args):
     return JythonGraphTraversal(self.traversalSource.inject(*args))
+  def getStrategies(self, *args):
+    return self.traversalSource.getStrategies(*args)
+  def addV(self, *args):
+    return JythonGraphTraversal(self.traversalSource.addV(*args))
+  def getGraph(self, *args):
+    return self.traversalSource.getGraph(*args)
   def tx(self, *args):
     return self.traversalSource.tx(*args)
   def wait(self, *args):
@@ -175,48 +177,49 @@ class JythonGraphTraversal(object):
   def id(self, *args):
     self.traversal = self.traversal.id(*args)
     return self
-  def label(self, *args):
-    self.traversal = self.traversal.label(*args)
-    return self
-  def has(self, *args):
-    self.traversal = self.traversal.has(*args)
-    return self
-  def union(self, *args):
-    self.traversal = self.traversal.union(*args)
-    return self
-  def groupCount(self, *args):
-    self.traversal = self.traversal.groupCount(*args)
-    return self
-  def flatMap(self, *args):
-    self.traversal = self.traversal.flatMap(*args)
+  def option(self, *args):
+    self.traversal = self.traversal.option(*args)
     return self
-  def iterate(self, *args):
-    self.traversal = self.traversal.iterate(*args)
+  def _not(self, *args):
+    return self.traversal.not(*args)
+  def property(self, *args):
+    self.traversal = self.traversal.property(*args)
     return self
-  def until(self, *args):
-    self.traversal = self.traversal.until(*args)
+  def program(self, *args):
+    self.traversal = self.traversal.program(*args)
     return self
-  def asAdmin(self, *args):
-    self.traversal = self.traversal.asAdmin(*args)
+  def label(self, *args):
+    self.traversal = self.traversal.label(*args)
     return self
   def choose(self, *args):
     self.traversal = self.traversal.choose(*args)
     return self
-  def program(self, *args):
-    self.traversal = self.traversal.program(*args)
+  def propertyMap(self, *args):
+    self.traversal = self.traversal.propertyMap(*args)
     return self
-  def both(self, *args):
-    self.traversal = self.traversal.both(*args)
+  def inject(self, *args):
+    self.traversal = self.traversal.inject(*args)
     return self
-  def toE(self, *args):
-    self.traversal = self.traversal.toE(*args)
+  def drop(self, *args):
+    self.traversal = self.traversal.drop(*args)
+    return self
+  def times(self, *args):
+    self.traversal = self.traversal.times(*args)
+    return self
+  def select(self, *args):
+    self.traversal = self.traversal.select(*args)
     return self
+  def _as(self, *args):
+    return self.traversal.as(*args)
   def outE(self, *args):
     self.traversal = self.traversal.outE(*args)
     return self
   def inE(self, *args):
     self.traversal = self.traversal.inE(*args)
     return self
+  def toE(self, *args):
+    self.traversal = self.traversal.toE(*args)
+    return self
   def bothE(self, *args):
     self.traversal = self.traversal.bothE(*args)
     return self
@@ -226,6 +229,9 @@ class JythonGraphTraversal(object):
   def outV(self, *args):
     self.traversal = self.traversal.outV(*args)
     return self
+  def both(self, *args):
+    self.traversal = self.traversal.both(*args)
+    return self
   def bothV(self, *args):
     self.traversal = self.traversal.bothV(*args)
     return self
@@ -349,36 +355,11 @@ class JythonGraphTraversal(object):
   def by(self, *args):
     self.traversal = self.traversal.by(*args)
     return self
-  def propertyMap(self, *args):
-    self.traversal = self.traversal.propertyMap(*args)
-    return self
-  def select(self, *args):
-    self.traversal = self.traversal.select(*args)
-    return self
-  def _as(self, *args):
-    return self.traversal.as(*args)
-  def property(self, *args):
-    self.traversal = self.traversal.property(*args)
-    return self
-  def inject(self, *args):
-    self.traversal = self.traversal.inject(*args)
-    return self
-  def drop(self, *args):
-    self.traversal = self.traversal.drop(*args)
-    return self
-  def times(self, *args):
-    self.traversal = self.traversal.times(*args)
-    return self
-  def option(self, *args):
-    self.traversal = self.traversal.option(*args)
-    return self
-  def cap(self, *args):
-    self.traversal = self.traversal.cap(*args)
-    return self
   def _is(self, *args):
     return self.traversal.is(*args)
-  def _not(self, *args):
-    return self.traversal.not(*args)
+  def until(self, *args):
+    self.traversal = self.traversal.until(*args)
+    return self
   def constant(self, *args):
     self.traversal = self.traversal.constant(*args)
     return self
@@ -390,6 +371,27 @@ class JythonGraphTraversal(object):
     return self
   def _from(self, *args):
     return self.traversal.from(*args)
+  def has(self, *args):
+    self.traversal = self.traversal.has(*args)
+    return self
+  def union(self, *args):
+    self.traversal = self.traversal.union(*args)
+    return self
+  def groupCount(self, *args):
+    self.traversal = self.traversal.groupCount(*args)
+    return self
+  def flatMap(self, *args):
+    self.traversal = self.traversal.flatMap(*args)
+    return self
+  def iterate(self, *args):
+    self.traversal = self.traversal.iterate(*args)
+    return self
+  def cap(self, *args):
+    self.traversal = self.traversal.cap(*args)
+    return self
+  def asAdmin(self, *args):
+    self.traversal = self.traversal.asAdmin(*args)
+    return self
   def next(self, *args):
     return self.traversal.next(*args)
   def fill(self, *args):
@@ -398,16 +400,16 @@ class JythonGraphTraversal(object):
     return self.traversal.forEachRemaining(*args)
   def toList(self, *args):
     return self.traversal.toList(*args)
+  def toSet(self, *args):
+    return self.traversal.toSet(*args)
+  def toBulkSet(self, *args):
+    return self.traversal.toBulkSet(*args)
   def tryNext(self, *args):
     return self.traversal.tryNext(*args)
   def toStream(self, *args):
     return self.traversal.toStream(*args)
-  def toBulkSet(self, *args):
-    return self.traversal.toBulkSet(*args)
   def explain(self, *args):
     return self.traversal.explain(*args)
-  def toSet(self, *args):
-    return self.traversal.toSet(*args)
   def remove(self, *args):
     return self.traversal.remove(*args)
   def hasNext(self, *args):
@@ -497,35 +499,35 @@ class __(object):
   def id(*args):
     return anon.id(*args)
   @staticmethod
-  def label(*args):
-    return anon.label(*args)
+  def _not(*args):
+    return anon.not(*args)
   @staticmethod
-  def has(*args):
-    return anon.has(*args)
+  def property(*args):
+    return anon.property(*args)
   @staticmethod
-  def union(*args):
-    return anon.union(*args)
+  def label(*args):
+    return anon.label(*args)
   @staticmethod
-  def groupCount(*args):
-    return anon.groupCount(*args)
+  def choose(*args):
+    return anon.choose(*args)
   @staticmethod
-  def flatMap(*args):
-    return anon.flatMap(*args)
+  def propertyMap(*args):
+    return anon.propertyMap(*args)
   @staticmethod
-  def until(*args):
-    return anon.until(*args)
+  def inject(*args):
+    return anon.inject(*args)
   @staticmethod
-  def __(*args):
-    return anon.__(*args)
+  def drop(*args):
+    return anon.drop(*args)
   @staticmethod
-  def choose(*args):
-    return anon.choose(*args)
+  def times(*args):
+    return anon.times(*args)
   @staticmethod
-  def both(*args):
-    return anon.both(*args)
+  def select(*args):
+    return anon.select(*args)
   @staticmethod
-  def toE(*args):
-    return anon.toE(*args)
+  def _as(*args):
+    return anon.as(*args)
   @staticmethod
   def outE(*args):
     return anon.outE(*args)
@@ -533,6 +535,9 @@ class __(object):
   def inE(*args):
     return anon.inE(*args)
   @staticmethod
+  def toE(*args):
+    return anon.toE(*args)
+  @staticmethod
   def bothE(*args):
     return anon.bothE(*args)
   @staticmethod
@@ -542,6 +547,9 @@ class __(object):
   def outV(*args):
     return anon.outV(*args)
   @staticmethod
+  def both(*args):
+    return anon.both(*args)
+  @staticmethod
   def bothV(*args):
     return anon.bothV(*args)
   @staticmethod
@@ -656,35 +664,14 @@ class __(object):
   def barrier(*args):
     return anon.barrier(*args)
   @staticmethod
-  def propertyMap(*args):
-    return anon.propertyMap(*args)
-  @staticmethod
-  def select(*args):
-    return anon.select(*args)
-  @staticmethod
-  def _as(*args):
-    return anon.as(*args)
-  @staticmethod
-  def property(*args):
-    return anon.property(*args)
-  @staticmethod
-  def inject(*args):
-    return anon.inject(*args)
-  @staticmethod
-  def drop(*args):
-    return anon.drop(*args)
-  @staticmethod
-  def times(*args):
-    return anon.times(*args)
-  @staticmethod
-  def cap(*args):
-    return anon.cap(*args)
-  @staticmethod
   def _is(*args):
     return anon.is(*args)
   @staticmethod
-  def _not(*args):
-    return anon.not(*args)
+  def until(*args):
+    return anon.until(*args)
+  @staticmethod
+  def __(*args):
+    return anon.__(*args)
   @staticmethod
   def constant(*args):
     return anon.constant(*args)
@@ -695,6 +682,21 @@ class __(object):
   def to(*args):
     return anon.to(*args)
   @staticmethod
+  def has(*args):
+    return anon.has(*args)
+  @staticmethod
+  def union(*args):
+    return anon.union(*args)
+  @staticmethod
+  def groupCount(*args):
+    return anon.groupCount(*args)
+  @staticmethod
+  def flatMap(*args):
+    return anon.flatMap(*args)
+  @staticmethod
+  def cap(*args):
+    return anon.cap(*args)
+  @staticmethod
   def wait(*args):
     return anon.wait(*args)
   @staticmethod
@@ -716,3 +718,4 @@ class __(object):
   def notifyAll(*args):
     return anon.notifyAll(*args)
 
+