0
# GraphQL-Core
1

2
GraphQL-Core is a comprehensive Python port of GraphQL.js, providing the complete GraphQL specification implementation for Python. It enables developers to build and execute GraphQL schemas, handle queries, mutations, and subscriptions with full type safety and validation, supporting both synchronous and asynchronous execution.
3

4
## Package Information
5

6
- **Package Name**: graphql-core
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install graphql-core`
10
- **Minimum Python Version**: 3.6+
11

12
## Core Imports
13

14
```python
15
import graphql
16
```
17

18
Main functions:
19

20
```python
21
from graphql import graphql, graphql_sync
22
```
23

24
Schema definition:
25

26
```python
27
from graphql import (
28
    GraphQLSchema, 
29
    GraphQLObjectType, 
30
    GraphQLField, 
31
    GraphQLString,
32
    GraphQLInt,
33
    GraphQLFloat,
34
    GraphQLBoolean,
35
    GraphQLID
36
)
37
```
38

39
## Basic Usage
40

41
```python
42
from graphql import (
43
    GraphQLSchema, GraphQLObjectType, GraphQLField, GraphQLString,
44
    graphql_sync
45
)
46

47
# Define a simple schema
48
schema = GraphQLSchema(
49
    query=GraphQLObjectType(
50
        name='RootQueryType',
51
        fields={
52
            'hello': GraphQLField(
53
                GraphQLString,
54
                resolve=lambda obj, info: 'world'
55
            )
56
        }
57
    )
58
)
59

60
# Execute a query
61
query = '{ hello }'
62
result = graphql_sync(schema, query)
63
print(result.data)  # {'hello': 'world'}
64
```
65

66
## Architecture
67

68
GraphQL-Core follows the GraphQL specification architecture with clear separation of concerns:
69

70
- **Language Module**: Parsing GraphQL documents into Abstract Syntax Trees (AST), lexical analysis, and AST manipulation
71
- **Type System**: Schema definition, built-in scalar types, custom types, directives, and type validation
72
- **Validation Module**: Query validation against schema using specification-defined rules
73
- **Execution Module**: Query execution engine with support for resolvers, middleware, and subscriptions
74
- **Utilities Module**: Schema introspection, schema building from SDL, type comparisons, and development tools
75
- **Error Handling**: Comprehensive error reporting with location information and extensible error formatting
76

77
## Capabilities
78

79
### Primary Execution Functions
80

81
High-level functions to execute GraphQL operations against a schema with complete parsing, validation, and execution pipeline.
82

83
```python { .api }
84
async def graphql(
85
    schema: GraphQLSchema,
86
    source: Union[str, Source],
87
    root_value: Any = None,
88
    context_value: Any = None,
89
    variable_values: Optional[Dict[str, Any]] = None,
90
    operation_name: Optional[str] = None,
91
    field_resolver: Optional[GraphQLFieldResolver] = None,
92
    type_resolver: Optional[GraphQLTypeResolver] = None,
93
    middleware: Optional[Middleware] = None,
94
    execution_context_class: Optional[Type[ExecutionContext]] = None,
95
    is_awaitable: Optional[Callable[[Any], bool]] = None,
96
) -> ExecutionResult
97

98
def graphql_sync(
99
    schema: GraphQLSchema,
100
    source: Union[str, Source],
101
    root_value: Any = None,
102
    context_value: Any = None,
103
    variable_values: Optional[Dict[str, Any]] = None,
104
    operation_name: Optional[str] = None,
105
    field_resolver: Optional[GraphQLFieldResolver] = None,
106
    type_resolver: Optional[GraphQLTypeResolver] = None,
107
    middleware: Optional[Middleware] = None,
108
    execution_context_class: Optional[Type[ExecutionContext]] = None,
109
    check_sync: bool = False,
110
) -> ExecutionResult
111
```
112

113
[Primary Execution](./execution.md)
114

115
### Language Processing and AST
116

117
Parse GraphQL documents, manipulate AST nodes, and work with GraphQL source code including lexical analysis, parsing, and AST visitor patterns.
118

119
```python { .api }
120
def parse(source: Union[str, Source]) -> DocumentNode
121
def parse_value(source: Union[str, Source]) -> ValueNode
122
def parse_type(source: Union[str, Source]) -> TypeNode
123
def print_ast(ast: Node) -> str
124
def visit(root: Node, visitor: Visitor) -> Any
125

126
class Source:
127
    def __init__(self, body: str, name: str = "GraphQL request")
128

129
class Lexer:
130
    def __init__(self, source: Source)
131
```
132

133
[Language Processing](./language.md)
134

135
### Type System and Schema Definition
136

137
Build GraphQL schemas with types, fields, directives, and validation. Includes built-in scalar types and comprehensive type checking.
138

139
```python { .api }
140
class GraphQLSchema:
141
    def __init__(
142
        self,
143
        query: Optional[GraphQLObjectType] = None,
144
        mutation: Optional[GraphQLObjectType] = None,
145
        subscription: Optional[GraphQLObjectType] = None,
146
        types: Optional[Sequence[GraphQLNamedType]] = None,
147
        directives: Optional[Sequence[GraphQLDirective]] = None,
148
        description: Optional[str] = None,
149
        extensions: Optional[Dict[str, Any]] = None,
150
    )
151

152
class GraphQLObjectType:
153
    def __init__(
154
        self,
155
        name: str,
156
        fields: Union[Thunk[GraphQLFieldMap], GraphQLFieldMap],
157
        interfaces: Optional[Thunk[Sequence[GraphQLInterfaceType]]] = None,
158
        is_type_of: Optional[GraphQLIsTypeOfFn] = None,
159
        description: Optional[str] = None,
160
        extensions: Optional[Dict[str, Any]] = None,
161
    )
162

163
class GraphQLField:
164
    def __init__(
165
        self,
166
        type_: GraphQLOutputType,
167
        args: Optional[GraphQLArgumentMap] = None,
168
        resolve: Optional[GraphQLFieldResolver] = None,
169
        subscribe: Optional[GraphQLFieldResolver] = None,
170
        description: Optional[str] = None,
171
        deprecation_reason: Optional[str] = None,
172
        extensions: Optional[Dict[str, Any]] = None,
173
    )
174
```
175

176
[Type System](./type-system.md)
177

178
### Query Validation
179

180
Validate GraphQL documents against schemas using specification-defined validation rules and custom validation logic.
181

182
```python { .api }
183
def validate(schema: GraphQLSchema, document: DocumentNode, rules: Optional[Sequence[ValidationRule]] = None) -> List[GraphQLError]
184

185
class ValidationContext:
186
    def __init__(self, schema: GraphQLSchema, document: DocumentNode, type_info: TypeInfo, on_error: Callable[[GraphQLError], None])
187

188
specified_rules: List[ValidationRule]
189
```
190

191
[Query Validation](./validation.md)
192

193
### Query Execution Engine
194

195
Execute validated GraphQL operations with resolver functions, middleware support, and subscription handling.
196

197
```python { .api }
198
def execute(
199
    schema: GraphQLSchema,
200
    document: DocumentNode,
201
    root_value: Any = None,
202
    context_value: Any = None,
203
    variable_values: Optional[Dict[str, Any]] = None,
204
    operation_name: Optional[str] = None,
205
    field_resolver: Optional[GraphQLFieldResolver] = None,
206
    type_resolver: Optional[GraphQLTypeResolver] = None,
207
    subscribe_field_resolver: Optional[GraphQLFieldResolver] = None,
208
    middleware: Optional[Middleware] = None,
209
    execution_context_class: Optional[Type[ExecutionContext]] = None,
210
    is_awaitable: Optional[Callable[[Any], bool]] = None,
211
) -> AwaitableOrValue[ExecutionResult]
212

213
def execute_sync(
214
    schema: GraphQLSchema,
215
    document: DocumentNode,
216
    root_value: Any = None,
217
    context_value: Any = None,
218
    variable_values: Optional[Dict[str, Any]] = None,
219
    operation_name: Optional[str] = None,
220
    field_resolver: Optional[GraphQLFieldResolver] = None,
221
    type_resolver: Optional[GraphQLTypeResolver] = None,
222
    middleware: Optional[Middleware] = None,
223
    execution_context_class: Optional[Type["ExecutionContext"]] = None,
224
    check_sync: bool = False,
225
) -> ExecutionResult
226

227
class ExecutionResult:
228
    data: Optional[Dict[str, Any]]
229
    errors: Optional[List[GraphQLError]]
230
    extensions: Optional[Dict[str, Any]]
231
```
232

233
[Query Execution](./execution-engine.md)
234

235
### Schema Utilities and Introspection
236

237
Build schemas from SDL, perform introspection, compare schemas, and manipulate GraphQL type information for tooling and development.
238

239
```python { .api }
240
def build_schema(
241
    source: Union[str, Source],
242
    assume_valid: bool = False,
243
    assume_valid_sdl: bool = False,
244
    no_location: bool = False,
245
    allow_legacy_fragment_variables: bool = False,
246
) -> GraphQLSchema
247
def build_ast_schema(document_ast: DocumentNode) -> GraphQLSchema
248
def build_client_schema(introspection: Dict[str, Any]) -> GraphQLSchema
249
def extend_schema(schema: GraphQLSchema, document_ast: DocumentNode) -> GraphQLSchema
250
def print_schema(schema: GraphQLSchema) -> str
251
def get_introspection_query(description: bool = True) -> str
252
def introspection_from_schema(schema: GraphQLSchema) -> Dict[str, Any]
253
def find_breaking_changes(old_schema: GraphQLSchema, new_schema: GraphQLSchema) -> List[BreakingChange]
254
def find_dangerous_changes(old_schema: GraphQLSchema, new_schema: GraphQLSchema) -> List[DangerousChange]
255

256
class TypeInfo:
257
    def __init__(self, schema: GraphQLSchema, initial_type: Optional[GraphQLType] = None)
258
```
259

260
[Schema Utilities](./utilities.md)
261

262
### Error Handling and Debugging
263

264
Handle GraphQL errors with location information, formatted error responses, and extensible error reporting.
265

266
```python { .api }
267
class GraphQLError(Exception):
268
    def __init__(
269
        self,
270
        message: str,
271
        nodes: Optional[Union[Node, Sequence[Node]]] = None,
272
        source: Optional[Source] = None,
273
        positions: Optional[Sequence[int]] = None,
274
        path: Optional[Sequence[Union[str, int]]] = None,
275
        original_error: Optional[Exception] = None,
276
        extensions: Optional[Dict[str, Any]] = None,
277
    )
278

279
class GraphQLSyntaxError(GraphQLError):
280
    pass
281

282
def located_error(original_error: Exception, nodes: Optional[Union[Node, Sequence[Node]]] = None, path: Optional[Sequence[Union[str, int]]] = None) -> GraphQLError
283

284
# Type definitions
285
GraphQLFormattedError = Dict[str, Any]
286
GraphQLErrorExtensions = Dict[str, Any]
287
```
288

289
[Error Handling](./error-handling.md)
290

291
## Types
292

293
### Core Types
294

295
```python { .api }
296
# Built-in scalar types
297
GraphQLInt: GraphQLScalarType
298
GraphQLFloat: GraphQLScalarType
299
GraphQLString: GraphQLScalarType
300
GraphQLBoolean: GraphQLScalarType
301
GraphQLID: GraphQLScalarType
302

303
# Type system types
304
GraphQLType = Union[GraphQLScalarType, GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList, GraphQLNonNull]
305
GraphQLInputType = Union[GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList, GraphQLNonNull]
306
GraphQLOutputType = Union[GraphQLScalarType, GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType, GraphQLEnumType, GraphQLList, GraphQLNonNull]
307

308
# Schema types
309
from typing import Any, Dict, List, Optional, Union, Sequence, Callable, Type
310
from graphql.pyutils import Undefined, UndefinedType
311

312
# Resolver function types
313
GraphQLFieldResolver = Callable[..., Any]
314
GraphQLTypeResolver = Callable[..., Any]
315
GraphQLIsTypeOfFn = Callable[..., bool]
316

317
# Execution types
318
class ExecutionResult:
319
    data: Optional[Dict[str, Any]]
320
    errors: Optional[List[GraphQLError]]
321
    extensions: Optional[Dict[str, Any]]
322

323
# AST node types
324
class DocumentNode:
325
    kind: str
326
    definitions: List[DefinitionNode]
327

328
class OperationDefinitionNode:
329
    kind: str
330
    operation: OperationType
331
    name: Optional[NameNode]
332
    variable_definitions: Optional[List[VariableDefinitionNode]]
333
    directives: Optional[List[DirectiveNode]]
334
    selection_set: SelectionSetNode
335

336
# Version information
337
version: str
338
version_info: VersionInfo
339
version_js: str
340
version_info_js: VersionInfo
341

342
class VersionInfo:
343
    major: int
344
    minor: int
345
    micro: int
346
    releaselevel: str
347
    serial: int
348
```