or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

aql.mdclient-database.mdcollections.mderrors-types.mdgraphs.mdindex.mdtransactions.md
tile.json

tessl/pypi-python-arango

Python Driver for ArangoDB, a scalable multi-model database that natively supports documents, graphs, and search.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/python-arango@8.2.x

To install, run

npx @tessl/cli install tessl/pypi-python-arango@8.2.0

index.mddocs/

Python-Arango

A comprehensive Python driver for ArangoDB, a scalable multi-model database that natively supports documents, graphs, and search. This driver provides full functionality for database operations including collections management, AQL query execution, graph traversal, and advanced features like Foxx services, backup/restore, and cluster management.

Package Information

  • Package Name: python-arango
  • Language: Python
  • Installation: pip install python-arango
  • Requirements: Python >=3.9

Core Imports

from arango import ArangoClient

For exception handling:

from arango import ArangoError, DocumentInsertError, CollectionCreateError

For custom HTTP clients:

from arango import DefaultHTTPClient, DeflateRequestCompression

Basic Usage

from arango import ArangoClient

# Initialize the client
client = ArangoClient(hosts='http://127.0.0.1:8529')

# Connect to "_system" database as root user
sys_db = client.db('_system', username='root', password='password')

# Create a new database
sys_db.create_database('example')

# Connect to the new database
db = client.db('example', username='root', password='password')

# Create a collection
students = db.create_collection('students')

# Insert a document
doc = students.insert({'name': 'jane', 'age': 39, 'gpa': 2.5})

# Get a document
student = students.get(doc['_key'])

# Execute AQL query
cursor = db.aql.execute('FOR s IN students RETURN s')
result = [doc for doc in cursor]

# Work with graphs
graph = db.create_graph('school')
vertex_col = graph.create_vertex_collection('teachers')
edge_col = graph.create_edge_definition(
    edge_collection='teach',
    from_vertex_collections=['teachers'],
    to_vertex_collections=['students']
)

Architecture

The python-arango driver follows a hierarchical client architecture:

  • ArangoClient: Top-level client managing connections and database access
  • Database: Database context providing collections, graphs, AQL, users, and transactions
  • Collection: Document/edge operations with CRUD, batch operations, and indexing
  • Graph: Graph operations with vertex/edge collections and traversal capabilities
  • AQL: Query interface with execution, analysis, caching, and function management
  • Cursor: Result iteration with lazy loading and metadata access
  • HTTP Layer: Pluggable HTTP clients with compression and session management

The driver provides both synchronous operations and comprehensive error handling with operation-specific exceptions that inherit from a common ArangoError base class.

Capabilities

Client & Database Management

Core client operations including database connections, database lifecycle management, server information, and cluster operations. Provides the foundation for all ArangoDB interactions.

class ArangoClient: 
    def __init__(self, hosts='http://127.0.0.1:8529', host_resolver='fallback',
                 resolver_max_tries=None, http_client=None, serializer=None, 
                 deserializer=None, verify_override=None, request_timeout=60,
                 request_compression=None, response_compression=None): ...
    def db(self, name='_system', username='root', password='', verify=False,
           auth_method='basic', user_token=None, superuser_token=None) -> StandardDatabase: ...
    def close(self) -> None: ...
    @property
    def hosts(self) -> Sequence[str]: ...
    @property  
    def version(self) -> str: ...
    @property
    def request_timeout(self) -> Any: ...

Client & Database Management

Document & Collection Operations

Complete document lifecycle management including CRUD operations, batch processing, and collection management. Supports standard collections, vertex collections, and edge collections with comprehensive indexing capabilities.

class StandardCollection:
    def insert(self, document: Json, return_new: bool = False, sync=None, 
               silent: bool = False, overwrite: bool = False, **kwargs) -> Result: ...
    def get(self, document, rev=None, check_rev: bool = True) -> Result: ...
    def update(self, document: Json, check_rev: bool = True, merge: bool = True, 
               keep_none: bool = True, return_new: bool = False, **kwargs) -> Result: ...
    def delete(self, document, rev=None, check_rev: bool = True, 
               ignore_missing: bool = False, **kwargs) -> Result: ...
    def insert_many(self, documents: Sequence[Json], **kwargs) -> Result: ...

Document & Collection Operations

AQL Query Interface

Advanced Query Language (AQL) interface providing query execution, analysis, optimization, caching, and user-defined function management. Includes query tracking, performance profiling, and result cursors.

class AQL:
    def execute(self, query: str, count: bool = False, batch_size=None, 
                bind_vars=None, **kwargs) -> Result[Cursor]: ...
    def explain(self, query: str, all_plans: bool = False, **kwargs) -> Result: ...
    def validate(self, query: str) -> Result[Json]: ...
    def functions(self) -> Result[List[Json]]: ...
    def create_function(self, name: str, code: str) -> Result[Json]: ...

AQL Query Interface

Graph Operations

Comprehensive graph database functionality including vertex and edge management, graph traversal, and specialized graph collections. Supports multi-graph scenarios with flexible edge definitions.

class Graph:
    def vertex_collection(self, name: str) -> VertexCollection: ...
    def edge_collection(self, name: str) -> EdgeCollection: ...
    def create_edge_definition(self, edge_collection: str, 
                               from_vertex_collections: Sequence[str],
                               to_vertex_collections: Sequence[str]) -> Result: ...
    def vertex(self, vertex, rev=None, check_rev: bool = True) -> Result: ...
    def insert_vertex(self, collection: str, vertex: Json, sync=None) -> Result[Json]: ...

Graph Operations

Transaction Management

Database transaction support with read/write/exclusive access patterns, transaction contexts, and JavaScript transaction execution. Provides ACID guarantees across multiple collections.

class StandardDatabase:
    def begin_transaction(self, read=None, write=None, exclusive=None, 
                          **kwargs) -> Result[TransactionDatabase]: ...
    def transaction(self, command: str, params=None, **kwargs) -> Result: ...

Transaction Management

Error Handling & Types

Comprehensive exception hierarchy with operation-specific error types, error code constants, and result wrappers. Provides structured error handling for all database operations.

class ArangoError(Exception): ...
class ArangoServerError(ArangoError): ...
class ArangoClientError(ArangoError): ...

# Operation-specific exceptions
class DocumentInsertError(ArangoServerError): ...
class CollectionCreateError(ArangoServerError): ...
class AQLQueryExecuteError(ArangoServerError): ...

Error Handling & Types

Common Types

# Type aliases used throughout the API
Json = Dict[str, Any]
Jsons = List[Json]
Result = Union[T, ArangoError]
Headers = Optional[MutableMapping[str, str]]
MutableMapping = Dict[str, Any]
Sequence = List[Any]