0
# Ariadne
1

2
A comprehensive Python library for implementing GraphQL servers using a schema-first approach. Ariadne provides full GraphQL compatibility with support for queries, mutations, subscriptions, custom scalars, enums, schema directives, unions, interfaces, file uploads, and asynchronous resolvers. It's designed to be simple, consistent, and modular while following GraphQL community best practices.
3

4
## Package Information
5

6
- **Package Name**: ariadne
7
- **Language**: Python
8
- **Installation**: `pip install ariadne`
9
- **Python Requirements**: Python 3.9 or higher
10

11
## Core Imports
12

13
```python
14
import ariadne
15
```
16

17
Common imports for basic functionality:
18

19
```python
20
from ariadne import ObjectType, QueryType, gql, make_executable_schema
21
from ariadne.asgi import GraphQL
22
```
23

24
## Basic Usage
25

26
```python
27
from ariadne import ObjectType, QueryType, gql, make_executable_schema
28
from ariadne.asgi import GraphQL
29

30
# Define GraphQL schema using Schema Definition Language
31
type_defs = gql("""
32
    type Query {
33
        people: [Person!]!
34
    }
35

36
    type Person {
37
        firstName: String
38
        lastName: String
39
        age: Int
40
        fullName: String
41
    }
42
""")
43

44
# Create query resolver
45
query = QueryType()
46

47
@query.field("people")
48
def resolve_people(*_):
49
    return [
50
        {"firstName": "John", "lastName": "Doe", "age": 21},
51
        {"firstName": "Bob", "lastName": "Boberson", "age": 24},
52
    ]
53

54
# Create object type resolver
55
person = ObjectType("Person")
56

57
@person.field("fullName")
58
def resolve_person_fullname(person, *_):
59
    return f"{person['firstName']} {person['lastName']}"
60

61
# Create executable schema
62
schema = make_executable_schema(type_defs, query, person)
63

64
# Create ASGI application
65
app = GraphQL(schema, debug=True)
66
```
67

68
## Architecture
69

70
Ariadne follows a schema-first approach with clear separation of concerns:
71

72
- **Schema Definition**: GraphQL schemas defined using SDL strings
73
- **Bindables**: Python classes that bind resolvers to schema elements
74
- **Execution**: GraphQL query execution with async/sync support
75
- **Extensions**: Middleware-like system for cross-cutting concerns
76
- **ASGI Integration**: Web server support for production deployment
77

78
The bindable pattern allows associating Python logic with GraphQL schema elements while maintaining loose coupling and explicit type reuse across multiple schemas.
79

80
## Capabilities
81

82
### Core Schema Creation
83

84
Essential functionality for creating executable GraphQL schemas from type definitions and binding Python logic to schema elements.
85

86
```python { .api }
87
def make_executable_schema(
88
    type_defs: Union[str, list[str]],
89
    *bindables: Union[SchemaBindable, type[Enum], list[Union[SchemaBindable, type[Enum]]]],
90
    directives: Optional[dict[str, type[SchemaDirectiveVisitor]]] = None,
91
    convert_names_case: Union[bool, SchemaNameConverter] = False,
92
) -> GraphQLSchema: ...
93

94
def load_schema_from_path(path: str) -> str: ...
95

96
def gql(string: str) -> str: ...
97
```
98

99
[Core Schema](./core-schema.md)
100

101
### GraphQL Execution
102

103
Functions for executing GraphQL queries, mutations, and subscriptions with support for both synchronous and asynchronous execution.
104

105
```python { .api }
106
async def graphql(
107
    schema: GraphQLSchema,
108
    data: dict,
109
    *,
110
    context_value: Optional[Any] = None,
111
    root_value: Optional[Any] = None,
112
    debug: bool = False,
113
    **kwargs
114
) -> dict: ...
115

116
def graphql_sync(
117
    schema: GraphQLSchema,
118
    data: dict,
119
    *,
120
    context_value: Optional[Any] = None,
121
    root_value: Optional[Any] = None,
122
    debug: bool = False,
123
    **kwargs
124
) -> dict: ...
125

126
async def subscribe(
127
    schema: GraphQLSchema,
128
    data: dict,
129
    *,
130
    context_value: Optional[Any] = None,
131
    root_value: Optional[Any] = None,
132
    debug: bool = False,
133
    **kwargs
134
): ...
135
```
136

137
[GraphQL Execution](./execution.md)
138

139
### Type Bindables
140

141
Classes for binding Python logic to different GraphQL schema elements including objects, scalars, enums, interfaces, unions, and input types.
142

143
```python { .api }
144
class ObjectType(SchemaBindable):
145
    def __init__(self, name: str): ...
146
    def field(self, name: str): ...
147

148
class QueryType(ObjectType): ...
149
class MutationType(ObjectType): ...
150

151
class ScalarType(SchemaBindable):
152
    def __init__(self, name: str): ...
153
    def serializer(self, serializer_func): ...
154
    def value_parser(self, parser_func): ...
155
    def literal_parser(self, parser_func): ...
156

157
class EnumType(SchemaBindable):
158
    def __init__(self, name: str, values: dict): ...
159

160
class InterfaceType(SchemaBindable):
161
    def __init__(self, name: str): ...
162
    def field(self, name: str): ...
163
    def type_resolver(self, type_resolver_func): ...
164

165
class UnionType(SchemaBindable):
166
    def __init__(self, name: str): ...
167
    def type_resolver(self, type_resolver_func): ...
168

169
class InputType(SchemaBindable):
170
    def __init__(self, name: str): ...
171
    def out_type(self, out_type_func): ...
172

173
class SubscriptionType(SchemaBindable):
174
    def __init__(self, name: str): ...
175
    def field(self, name: str): ...
176
    def source(self, name: str): ...
177
```
178

179
[Type Bindables](./type-bindables.md)
180

181
### ASGI Integration
182

183
ASGI application for serving GraphQL APIs with WebSocket support for subscriptions and integration with ASGI servers.
184

185
```python { .api }
186
class GraphQL:
187
    def __init__(
188
        self,
189
        schema: GraphQLSchema,
190
        *,
191
        context_value: Optional[Any] = None,
192
        root_value: Optional[Any] = None,
193
        debug: bool = False,
194
        explorer: Optional[Explorer] = None,
195
        **kwargs
196
    ): ...
197
```
198

199
[ASGI Integration](./asgi.md)
200

201
### Error Handling
202

203
Functions for formatting GraphQL errors and extracting error information for client responses.
204

205
```python { .api }
206
def format_error(error: Exception, debug: bool = False) -> dict: ...
207
def get_error_extension(error: Exception) -> Optional[dict]: ...
208
def get_formatted_error_context(error: dict) -> Optional[Any]: ...  
209
def get_formatted_error_traceback(error: dict) -> Optional[str]: ...
210
def unwrap_graphql_error(error: Exception) -> Exception: ...
211
```
212

213
[Error Handling](./error-handling.md)
214

215
### Resolver Utilities
216

217
Helper functions and classes for creating field resolvers with support for fallback resolvers and case conversion.
218

219
```python { .api }
220
def resolve_to(value: Any): ...
221
def is_default_resolver(resolver: Callable) -> bool: ...
222

223
fallback_resolvers: FallbackResolversSetter
224
snake_case_fallback_resolvers: SnakeCaseFallbackResolversSetter
225

226
class FallbackResolversSetter(SchemaBindable): ...
227
class SnakeCaseFallbackResolversSetter(SchemaBindable): ...
228
```
229

230
[Resolver Utilities](./resolvers.md)
231

232
### GraphQL Explorer
233

234
Built-in GraphQL development tools including GraphQL Playground, GraphiQL, and Apollo Studio integration for API exploration and testing.
235

236
```python { .api }
237
class Explorer:
238
    def __init__(self, title: str = "Ariadne GraphQL"): ...
239

240
class ExplorerPlayground(Explorer): ...
241
class ExplorerGraphiQL(Explorer): ...
242
class ExplorerApollo(Explorer): ...
243
class ExplorerHttp405(Explorer): ...
244
```
245

246
[GraphQL Explorer](./explorer.md)
247

248
### File Uploads
249

250
Support for GraphQL multipart file uploads following the GraphQL multipart request specification.
251

252
```python { .api }
253
def combine_multipart_data(operations: dict, files_map: dict, files: dict) -> dict: ...
254

255
upload_scalar: ScalarType
256
```
257

258
[File Uploads](./file-uploads.md)
259

260
### Apollo Federation
261

262
Support for Apollo Federation allowing microservice architecture with federated GraphQL schemas.
263

264
```python { .api }
265
class FederatedObjectType(ObjectType):
266
    def __init__(self, name: str): ...
267
    def reference_resolver(self, resolver_func): ...
268

269
class FederatedInterfaceType(InterfaceType):
270
    def __init__(self, name: str): ...
271
    def reference_resolver(self, resolver_func): ...
272

273
def make_federated_schema(
274
    type_defs: Union[str, list[str]],
275
    *bindables,
276
    **kwargs
277
) -> GraphQLSchema: ...
278
```
279

280
[Apollo Federation](./federation.md)
281

282
### Relay Support
283

284
Implementation of Relay specifications including connections, global object identification, and pagination.
285

286
```python { .api }
287
class RelayObjectType(ObjectType):
288
    def __init__(self, name: str): ...
289

290
class RelayQueryType(QueryType):
291
    def __init__(self): ...
292

293
class RelayNodeInterfaceType(InterfaceType):
294
    def __init__(self): ...
295

296
class RelayConnection:
297
    def __init__(
298
        self,
299
        edges: list,
300
        page_info: dict,
301
        total_count: Optional[int] = None
302
    ): ...
303

304
class ConnectionArguments:
305
    first: Optional[int]
306
    after: Optional[str]
307
    last: Optional[int]
308
    before: Optional[str]
309

310
def encode_global_id(type_name: str, node_id: str) -> str: ...
311
def decode_global_id(global_id: str) -> tuple[str, str]: ...
312
```
313

314
[Relay Support](./relay.md)
315

316
### Validation
317

318
Query validation tools for implementing security measures like query cost analysis and introspection control.
319

320
```python { .api }
321
cost_directive: SchemaDirectiveVisitor
322
cost_validator: Callable
323
```
324

325
[Validation](./validation.md)
326

327
## Types
328

329
```python { .api }
330
# Base types
331
SchemaBindable = Protocol
332
Extension = Protocol
333
Resolver = Callable
334
SchemaBindables = Union[SchemaBindable, type[Enum], list[Union[SchemaBindable, type[Enum]]]]
335

336
# ASGI types  
337
Extensions = dict[str, Any]
338
MiddlewareList = list[Callable]
339
Middlewares = Union[MiddlewareList, Callable]
340
OnConnect = Callable
341
OnDisconnect = Callable
342
OnOperation = Callable
343
OnComplete = Callable
344
Operation = dict[str, Any]
345

346
# Relay types
347
ConnectionResolver = Callable
348
GlobalIDTuple = tuple[str, str]
349

350
# Exception types
351
class WebSocketConnectionError(Exception): ...
352
```