Integrate Python driver examples into automated build process (#3231)

Integrates Python Gremlin examples into CI to ensure they remain functional in future releases. Examples now execute automatically after integration tests and fail the build if broken.

Changes Made
- Added example execution to gremlin-python-integration-tests container in docker-compose.yml
- Made server URLs configurable via environment variables (replaces hardcoded localhost:8182)
- Added configurable vertex labels and targeted cleanup using has_label()
- Added graph binding detection - uses gmodern in CI, g locally for proper environment handling

Author: kirill-stepanishin

CHANGELOG.asciidoc

@@ -22,6 +22,7 @@ image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/ima
 
 [[release-3-7-6]]
 === TinkerPop 3.7.6 (NOT OFFICIALLY RELEASED YET)
+* Integrated Python driver examples into automated build process to ensure examples remain functional.
 
 [[release-3-7-5]]
 === TinkerPop 3.7.5 (Release Date: November 12, 2025)

gremlin-examples/gremlin-python/basic_gremlin.py

@@ -23,27 +23,29 @@
 from gremlin_python.process.strategies import *
 from gremlin_python.driver.driver_remote_connection import DriverRemoteConnection
 
+VERTEX_LABEL = 'person'
 
 def main():
-    rc = DriverRemoteConnection('ws://localhost:8182/gremlin', 'g')
+    server_url = 'ws://localhost:8182/gremlin'
+    rc = DriverRemoteConnection(server_url, 'g')
     g = traversal().with_remote(rc)
 
     # basic Gremlin: adding and retrieving data
-    v1 = g.add_v('person').property('name', 'marko').next()
-    v2 = g.add_v('person').property('name', 'stephen').next()
-    v3 = g.add_v('person').property('name', 'vadas').next()
+    v1 = g.add_v(VERTEX_LABEL).property('name', 'marko').next()
+    v2 = g.add_v(VERTEX_LABEL).property('name', 'stephen').next()
+    v3 = g.add_v(VERTEX_LABEL).property('name', 'vadas').next()
 
     # be sure to use a terminating step like next() or iterate() so that the traversal "executes"
     # iterate() does not return any data and is used to just generate side-effects (i.e. write data to the database)
     g.V(v1).add_e('knows').to(v2).property('weight', 0.75).iterate()
     g.V(v1).add_e('knows').to(v3).property('weight', 0.75).iterate()
 
     # retrieve the data from the "marko" vertex
-    marko = g.V().has('person', 'name', 'marko').values('name').next()
+    marko = g.V().has(VERTEX_LABEL, 'name', 'marko').values('name').next()
     print("name: " + marko)
 
     # find the "marko" vertex and then traverse to the people he "knows" and return their data
-    people_marko_knows = g.V().has('person', 'name', 'marko').out('knows').values('name').to_list()
+    people_marko_knows = g.V().has(VERTEX_LABEL, 'name', 'marko').out('knows').values('name').to_list()
     for person in people_marko_knows:
         print("marko knows " + person)
 

gremlin-examples/gremlin-python/connections.py

@@ -24,6 +24,7 @@
 from gremlin_python.driver.driver_remote_connection import DriverRemoteConnection
 from gremlin_python.driver.serializer import GraphBinarySerializersV1
 
+VERTEX_LABEL = 'connection'
 
 def main():
     with_remote()
@@ -40,15 +41,13 @@ def with_remote():
     #
     # which starts it in "console" mode with an empty in-memory TinkerGraph ready to go bound to a
     # variable named "g" as referenced in the following line.
-    rc = DriverRemoteConnection('ws://localhost:8182/gremlin', 'g')
+    server_url = 'ws://localhost:8182/gremlin'
+    rc = DriverRemoteConnection(server_url, 'g')
     g = traversal().with_remote(rc)
 
-    # drop existing vertices
-    g.V().drop().iterate()
-
     # simple query to verify connection
-    v = g.add_v().iterate()
-    count = g.V().count().next()
+    v = g.add_v(VERTEX_LABEL).iterate()
+    count = g.V().has_label(VERTEX_LABEL).count().next()
     print("Vertex count: " + str(count))
 
     # cleanup
@@ -57,41 +56,44 @@ def with_remote():
 
 # connecting with plain text authentication
 def with_auth():
-    rc = DriverRemoteConnection('ws://localhost:8182/gremlin', 'g', username='stephen', password='password')
+    server_url = 'ws://localhost:8182/gremlin'
+    rc = DriverRemoteConnection(server_url, 'g', username='stephen', password='password')
     g = traversal().with_remote(rc)
 
-    v = g.add_v().iterate()
-    count = g.V().count().next()
+    v = g.add_v(VERTEX_LABEL).iterate()
+    count = g.V().has_label(VERTEX_LABEL).count().next()
     print("Vertex count: " + str(count))
 
     rc.close()
 
 
 # connecting with Kerberos SASL authentication
 def with_kerberos():
-    rc = DriverRemoteConnection('ws://localhost:8182/gremlin', 'g', kerberized_service='gremlin@hostname.your.org')
+    server_url = 'ws://localhost:8182/gremlin'
+    rc = DriverRemoteConnection(server_url, 'g', kerberized_service='gremlin@hostname.your.org')
     g = traversal().with_remote(rc)
 
-    v = g.add_v().iterate()
-    count = g.V().count().next()
+    v = g.add_v(VERTEX_LABEL).iterate()
+    count = g.V().has_label(VERTEX_LABEL).count().next()
     print("Vertex count: " + str(count))
 
     rc.close()
 
 
 # connecting with customized configurations
 def with_configs():
+    server_url = 'ws://localhost:8182/gremlin'
     rc = DriverRemoteConnection(
-        'ws://localhost:8182/gremlin', 'g',
+        server_url, 'g',
         username="", password="", kerberized_service='',
         message_serializer=GraphBinarySerializersV1(), graphson_reader=None,
         graphson_writer=None, headers=None, session=None,
         enable_user_agent_on_connect=True
     )
     g = traversal().with_remote(rc)
 
-    v = g.add_v().iterate()
-    count = g.V().count().next()
+    v = g.add_v(VERTEX_LABEL).iterate()
+    count = g.V().has_label(VERTEX_LABEL).count().next()
     print("Vertex count: " + str(count))
 
     rc.close()

gremlin-python/docker-compose.yml

@@ -72,7 +72,13 @@ services:
       && pip install .[test,kerberos]
       && pytest
       && radish -f dots -e -t -b ./radish ./gremlin-test --user-data='serializer=application/vnd.gremlin-v3.0+json'
-      && radish -f dots -e -t -b ./radish ./gremlin-test --user-data='serializer=application/vnd.graphbinary-v1.0';
+      && radish -f dots -e -t -b ./radish ./gremlin-test --user-data='serializer=application/vnd.graphbinary-v1.0'
+      && pip install .
+      && echo 'Running examples...'
+      && python3 examples/basic_gremlin.py
+      && python3 examples/connections.py
+      && python3 examples/modern_traversals.py
+      && echo 'All examples completed successfully';
       EXIT_CODE=$$?; chown -R `stat -c "%u:%g" .` .; exit $$EXIT_CODE"
     depends_on:
       gremlin-server-test-python:

gremlin-python/src/main/python/examples/basic_gremlin.py

@@ -16,34 +16,38 @@
 # under the License.
 
 import sys
+import os
 
 sys.path.append("..")
 
 from gremlin_python.process.anonymous_traversal import traversal
 from gremlin_python.process.strategies import *
 from gremlin_python.driver.driver_remote_connection import DriverRemoteConnection
 
+VERTEX_LABEL = os.getenv('VERTEX_LABEL', 'person')
 
 def main():
-    rc = DriverRemoteConnection('ws://localhost:8182/gremlin', 'g')
+    # if there is a port placeholder in the env var then we are running with docker so set appropriate port 
+    server_url = os.getenv('GREMLIN_SERVER_URL', 'ws://localhost:8182/gremlin').format(45940)
+    rc = DriverRemoteConnection(server_url, 'g')
     g = traversal().with_remote(rc)
 
     # basic Gremlin: adding and retrieving data
-    v1 = g.add_v('person').property('name', 'marko').next()
-    v2 = g.add_v('person').property('name', 'stephen').next()
-    v3 = g.add_v('person').property('name', 'vadas').next()
+    v1 = g.add_v(VERTEX_LABEL).property('name', 'marko').next()
+    v2 = g.add_v(VERTEX_LABEL).property('name', 'stephen').next()
+    v3 = g.add_v(VERTEX_LABEL).property('name', 'vadas').next()
 
     # be sure to use a terminating step like next() or iterate() so that the traversal "executes"
     # iterate() does not return any data and is used to just generate side-effects (i.e. write data to the database)
     g.V(v1).add_e('knows').to(v2).property('weight', 0.75).iterate()
     g.V(v1).add_e('knows').to(v3).property('weight', 0.75).iterate()
 
     # retrieve the data from the "marko" vertex
-    marko = g.V().has('person', 'name', 'marko').values('name').next()
+    marko = g.V().has(VERTEX_LABEL, 'name', 'marko').values('name').next()
     print("name: " + marko)
 
     # find the "marko" vertex and then traverse to the people he "knows" and return their data
-    people_marko_knows = g.V().has('person', 'name', 'marko').out('knows').values('name').to_list()
+    people_marko_knows = g.V().has(VERTEX_LABEL, 'name', 'marko').out('knows').values('name').to_list()
     for person in people_marko_knows:
         print("marko knows " + person)
 

gremlin-python/src/main/python/examples/connections.py

@@ -16,14 +16,19 @@
 # under the License.
 
 import sys
+import os
+import ssl
+import socket
 
 sys.path.append("..")
 
 from gremlin_python.process.anonymous_traversal import traversal
 from gremlin_python.process.strategies import *
 from gremlin_python.driver.driver_remote_connection import DriverRemoteConnection
 from gremlin_python.driver.serializer import GraphBinarySerializersV1
+from gremlin_python.driver.aiohttp.transport import AiohttpTransport
 
+VERTEX_LABEL = os.getenv('VERTEX_LABEL', 'connection')
 
 def main():
     with_remote()
@@ -40,15 +45,14 @@ def with_remote():
     #
     # which starts it in "console" mode with an empty in-memory TinkerGraph ready to go bound to a
     # variable named "g" as referenced in the following line.
-    rc = DriverRemoteConnection('ws://localhost:8182/gremlin', 'g')
+    # if there is a port placeholder in the env var then we are running with docker so set appropriate port 
+    server_url = os.getenv('GREMLIN_SERVER_URL', 'ws://localhost:8182/gremlin').format(45940)
+    rc = DriverRemoteConnection(server_url, 'g')
     g = traversal().with_remote(rc)
 
-    # drop existing vertices
-    g.V().drop().iterate()
-
     # simple query to verify connection
-    v = g.add_v().iterate()
-    count = g.V().count().next()
+    v = g.add_v(VERTEX_LABEL).iterate()
+    count = g.V().has_label(VERTEX_LABEL).count().next()
     print("Vertex count: " + str(count))
 
     # cleanup
@@ -57,41 +61,60 @@ def with_remote():
 
 # connecting with plain text authentication
 def with_auth():
-    rc = DriverRemoteConnection('ws://localhost:8182/gremlin', 'g', username='stephen', password='password')
+    # if there is a port placeholder in the env var then we are running with docker so set appropriate port 
+    server_url = os.getenv('GREMLIN_SERVER_BASIC_AUTH_URL', 'ws://localhost:8182/gremlin').format(45941)
+    
+    # disable SSL certificate verification for CI environments
+    if ':45941' in server_url:
+        ssl_opts = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+        ssl_opts.check_hostname = False
+        ssl_opts.verify_mode = ssl.CERT_NONE
+        rc = DriverRemoteConnection(server_url, 'g', username='stephen', password='password',
+                                    transport_factory=lambda: AiohttpTransport(ssl_options=ssl_opts))
+    else:
+        rc = DriverRemoteConnection(server_url, 'g', username='stephen', password='password')
+    
     g = traversal().with_remote(rc)
 
-    v = g.add_v().iterate()
-    count = g.V().count().next()
+    v = g.add_v(VERTEX_LABEL).iterate()
+    count = g.V().has_label(VERTEX_LABEL).count().next()
     print("Vertex count: " + str(count))
 
     rc.close()
 
 
 # connecting with Kerberos SASL authentication
 def with_kerberos():
-    rc = DriverRemoteConnection('ws://localhost:8182/gremlin', 'g', kerberized_service='gremlin@hostname.your.org')
+    # if there is a port placeholder in the env var then we are running with docker so set appropriate port 
+    server_url = os.getenv('GREMLIN_SERVER_URL', 'ws://localhost:8182/gremlin').format(45942)
+    kerberos_hostname = os.getenv('KRB_HOSTNAME', socket.gethostname())
+    kerberized_service = f'test-service@{kerberos_hostname}'
+    
+    rc = DriverRemoteConnection(server_url, 'g', kerberized_service=kerberized_service)
     g = traversal().with_remote(rc)
 
-    v = g.add_v().iterate()
-    count = g.V().count().next()
+    v = g.add_v(VERTEX_LABEL).iterate()
+    count = g.V().has_label(VERTEX_LABEL).count().next()
     print("Vertex count: " + str(count))
 
     rc.close()
 
 
 # connecting with customized configurations
 def with_configs():
+    # if there is a port placeholder in the env var then we are running with docker so set appropriate port 
+    server_url = os.getenv('GREMLIN_SERVER_URL', 'ws://localhost:8182/gremlin').format(45940)
     rc = DriverRemoteConnection(
-        'ws://localhost:8182/gremlin', 'g',
+        server_url, 'g',
         username="", password="", kerberized_service='',
         message_serializer=GraphBinarySerializersV1(), graphson_reader=None,
         graphson_writer=None, headers=None, session=None,
         enable_user_agent_on_connect=True
     )
     g = traversal().with_remote(rc)
 
-    v = g.add_v().iterate()
-    count = g.V().count().next()
+    v = g.add_v(VERTEX_LABEL).iterate()
+    count = g.V().has_label(VERTEX_LABEL).count().next()
     print("Vertex count: " + str(count))
 
     rc.close()

gremlin-python/src/main/python/examples/modern_traversals.py

@@ -16,6 +16,7 @@
 # under the License.
 
 import sys
+import os
 
 sys.path.append("..")
 
@@ -31,7 +32,16 @@ def main():
     # This example requires the Modern toy graph to be preloaded upon launching the Gremlin server.
     # For details, see https://tinkerpop.apache.org/docs/current/reference/#gremlin-server-docker-image and use
     # conf/gremlin-server-modern.yaml.
-    rc = DriverRemoteConnection('ws://localhost:8182/gremlin', 'g')
+    # if there is a port placeholder in the env var then we are running with docker so set appropriate port 
+    server_url = os.getenv('GREMLIN_SERVER_URL', 'ws://localhost:8182/gremlin').format(45940)
+    
+    # CI uses port 45940 with gmodern binding, local uses 8182 with g binding
+    if ':45940' in server_url:
+        graph_binding = 'gmodern'  # CI environment
+    else:
+        graph_binding = 'g'        # Local environment
+    
+    rc = DriverRemoteConnection(server_url, graph_binding)
     g = traversal().with_remote(rc)
 
     e1 = g.V(1).both_e().to_list()  # (1)