0
# Python-Arango
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: python-arango
7
- **Language**: Python
8
- **Installation**: `pip install python-arango`
9
- **Requirements**: Python >=3.9
10

11
## Core Imports
12

13
```python
14
from arango import ArangoClient
15
```
16

17
For exception handling:
18

19
```python
20
from arango import ArangoError, DocumentInsertError, CollectionCreateError
21
```
22

23
For custom HTTP clients:
24

25
```python
26
from arango import DefaultHTTPClient, DeflateRequestCompression
27
```
28

29
## Basic Usage
30

31
```python
32
from arango import ArangoClient
33

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

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

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

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

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

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

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

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

59
# Work with graphs
60
graph = db.create_graph('school')
61
vertex_col = graph.create_vertex_collection('teachers')
62
edge_col = graph.create_edge_definition(
63
    edge_collection='teach',
64
    from_vertex_collections=['teachers'],
65
    to_vertex_collections=['students']
66
)
67
```
68

69
## Architecture
70

71
The python-arango driver follows a hierarchical client architecture:
72

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

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

83
## Capabilities
84

85
### Client & Database Management
86

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

89
```python { .api }
90
class ArangoClient: 
91
    def __init__(self, hosts='http://127.0.0.1:8529', host_resolver='fallback',
92
                 resolver_max_tries=None, http_client=None, serializer=None, 
93
                 deserializer=None, verify_override=None, request_timeout=60,
94
                 request_compression=None, response_compression=None): ...
95
    def db(self, name='_system', username='root', password='', verify=False,
96
           auth_method='basic', user_token=None, superuser_token=None) -> StandardDatabase: ...
97
    def close(self) -> None: ...
98
    @property
99
    def hosts(self) -> Sequence[str]: ...
100
    @property  
101
    def version(self) -> str: ...
102
    @property
103
    def request_timeout(self) -> Any: ...
104
```
105

106
[Client & Database Management](./client-database.md)
107

108
### Document & Collection Operations
109

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

112
```python { .api }
113
class StandardCollection:
114
    def insert(self, document: Json, return_new: bool = False, sync=None, 
115
               silent: bool = False, overwrite: bool = False, **kwargs) -> Result: ...
116
    def get(self, document, rev=None, check_rev: bool = True) -> Result: ...
117
    def update(self, document: Json, check_rev: bool = True, merge: bool = True, 
118
               keep_none: bool = True, return_new: bool = False, **kwargs) -> Result: ...
119
    def delete(self, document, rev=None, check_rev: bool = True, 
120
               ignore_missing: bool = False, **kwargs) -> Result: ...
121
    def insert_many(self, documents: Sequence[Json], **kwargs) -> Result: ...
122
```
123

124
[Document & Collection Operations](./collections.md)
125

126
### AQL Query Interface
127

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

130
```python { .api }
131
class AQL:
132
    def execute(self, query: str, count: bool = False, batch_size=None, 
133
                bind_vars=None, **kwargs) -> Result[Cursor]: ...
134
    def explain(self, query: str, all_plans: bool = False, **kwargs) -> Result: ...
135
    def validate(self, query: str) -> Result[Json]: ...
136
    def functions(self) -> Result[List[Json]]: ...
137
    def create_function(self, name: str, code: str) -> Result[Json]: ...
138
```
139

140
[AQL Query Interface](./aql.md)
141

142
### Graph Operations
143

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

146
```python { .api }
147
class Graph:
148
    def vertex_collection(self, name: str) -> VertexCollection: ...
149
    def edge_collection(self, name: str) -> EdgeCollection: ...
150
    def create_edge_definition(self, edge_collection: str, 
151
                               from_vertex_collections: Sequence[str],
152
                               to_vertex_collections: Sequence[str]) -> Result: ...
153
    def vertex(self, vertex, rev=None, check_rev: bool = True) -> Result: ...
154
    def insert_vertex(self, collection: str, vertex: Json, sync=None) -> Result[Json]: ...
155
```
156

157
[Graph Operations](./graphs.md)
158

159
### Transaction Management
160

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

163
```python { .api }
164
class StandardDatabase:
165
    def begin_transaction(self, read=None, write=None, exclusive=None, 
166
                          **kwargs) -> Result[TransactionDatabase]: ...
167
    def transaction(self, command: str, params=None, **kwargs) -> Result: ...
168
```
169

170
[Transaction Management](./transactions.md)
171

172
### Error Handling & Types
173

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

176
```python { .api }
177
class ArangoError(Exception): ...
178
class ArangoServerError(ArangoError): ...
179
class ArangoClientError(ArangoError): ...
180

181
# Operation-specific exceptions
182
class DocumentInsertError(ArangoServerError): ...
183
class CollectionCreateError(ArangoServerError): ...
184
class AQLQueryExecuteError(ArangoServerError): ...
185
```
186

187
[Error Handling & Types](./errors-types.md)
188

189
## Common Types
190

191
```python { .api }
192
# Type aliases used throughout the API
193
Json = Dict[str, Any]
194
Jsons = List[Json]
195
Result = Union[T, ArangoError]
196
Headers = Optional[MutableMapping[str, str]]
197
MutableMapping = Dict[str, Any]
198
Sequence = List[Any]
199
```