Python HTTP Client

Manage Traverse databases, queries, and imports from Python over HTTP.

Install

pip install traverse-http

Connect

from traverse_http import TraverseHttpClient

client = TraverseHttpClient("http://localhost:7691")

# With API key authentication
client = TraverseHttpClient(
    "http://localhost:7691",
    api_key="tvs_your_api_key",
)

Context Manager

with TraverseHttpClient("http://localhost:7691", api_key="tvs_...") as client:
    health = client.health()
    print(health.version)

Health Check

health = client.health()
print(health.status)       # "ok"
print(health.version)      # server version
print(health.uptime_secs)  # seconds since start

# Quick readiness probe (returns bool, never raises)
if client.ready():
    print("Server is ready")

List Databases

databases = client.list_databases()
for db in databases:
    print(db.name, db.default)

Create & Drop Database

client.create_database("mydb")
client.drop_database("mydb")

Run a Query

result = client.query(
    "MATCH (n:Person) WHERE n.age > $min_age RETURN n.name, n.age",
    parameters={"min_age": 25},
    database="mydb",
)
for row in result.rows:
    print(row)

print(result.columns)     # ["n.name", "n.age"]
print(result.time_ms)     # query time in milliseconds

GQL Dialect

New in 0.8.0: pass dialect="gql" to run the query through the ISO/IEC 39075 GQL parser server-side. Check features.gql in the health response to detect support.

result = client.query("MATCH (n:Person) FILTER n.age > 30 RETURN n.name", dialect="gql")

Import Cypher

result = client.import_cypher(
    "CREATE (a:Person {name: 'Alice'});\nCREATE (b:Person {name: 'Bob'});",
    database="mydb",
)
print(result.executed, "of", result.total_statements, "statements")

Schema

schema = client.get_schema(database="mydb")
print(schema.labels)              # ["Person", "Movie"]
print(schema.relationship_types)  # ["KNOWS", "ACTED_IN"]
print(schema.indexes)             # list of IndexInfo

Aliases

# Create an alias
client.create_alias("production", "mydb")

# List aliases
for alias in client.list_aliases():
    print(alias.alias, "->", alias.database)

# Update and drop
client.alter_alias("production", "mydb_v2")
client.drop_alias("production")

File Upload

with open("backup.tvdb", "rb") as f:
    result = client.upload_file("backup.tvdb", f)
    print(result.size_bytes)

Save & Close

# Persist all databases to disk
client.save()

# Close the underlying HTTP session
client.close()

Constructor Options

client = TraverseHttpClient(
    "https://traverse.example.com",
    api_key="tvs_...",
    timeout=30.0,                       # API request timeout (seconds)
    transfer_timeout=600.0,             # file upload/download timeout (seconds)
    allow_untrusted_certificate=True,   # skip TLS verification
)