repository·main·Indexed 19 days ago
https://github.com/graphql-python/graphql-coreA Python 3.7+ port of the GraphQL.js reference implementation. graphql-core provides the core machinery for building GraphQL schemas and executing queries in Python, featuring support for both synchronous (graphql_sync) and asynchronous (graphql) execution, custom middleware, and a Pythonic API for accessing GraphQL type properties.
GraphQL-core is designed to provide two primary capabilities for GraphQL implementations:
A resolver function in GraphQL-core is responsible for returning a value, a coroutine, or a list of these. It accepts two positional arguments:
obj: The root or the resolved parent field.info: A GraphQLResolveInfo object containing the execution state, including a context attribute for per-request state (like authentication or database sessions).Any GraphQL arguments defined on the field are passed to the resolver as individual keyword arguments.
Note: This signature differs from GraphQL.js; in GraphQL.js, context is a separate argument and arguments are passed as a single object.
GraphQL-core 3 allows for easy conversion between three primary schema representations using the graphql.utilities module:
get_introspection_query to create a query, then execute it via graphql_sync.build_client_schema on the query result's .data dictionary.print_schema to generate the SDL string.from graphql import get_introspection_query, graphql_sync, build_client_schema, print_schema
# 1. Generate query
query = get_introspection_query(descriptions=True)
# 2. Execute against an existing schema to get introspection data
introspection_query_result = graphql_sync(schema, query)
# 3. Reconstruct a schema from the data
client_schema = build_client_schema(introspection_query_result.data)
# 4. Convert reconstructed schema to SDL
sdl = print_schema(client_schema)To use GraphQL-core, you first define a GraphQLSchema. This involves creating a GraphQLObjectType for your root query and defining GraphQLField objects. Each field can have a resolve function that handles the data fetching logic.
from graphql import (
GraphQLSchema, GraphQLObjectType, GraphQLField, GraphQLString)
schema = GraphQLSchema(
query=GraphQLObjectType(
name='RootQueryType',
fields={
'hello': GraphQLField(
GraphQLString,
resolve=lambda obj, info: 'world')
}))GraphQL-core 3 is a Python port of the JavaScript reference implementation and follows the GraphQL specification. It is organized into sub-packages that correspond to the specification's sections:
Most functionality can be accessed via the top-level graphql package, which acts as a proxy to these sub-packages.
The Visitor pattern allows you to traverse the AST and perform actions on specific nodes. You can implement a custom visitor by subclassing Visitor or ParallelVisitor and overriding the relevant visit methods.
To control the traversal flow, your visitor methods should return a value from VisitorActionEnum (or its direct exported values):
BREAK (or True): Stop all further node visitation immediately.SKIP (or False): Skip the children of the current node but continue with the rest of the tree.REMOVE (or ...): Signal that the current node should be deleted from the tree.IDLE (or None): No additional action is taken; continue normal traversal.from graphql.language import Visitor, BREAK
class MyVisitor(Visitor):
def enter_field(self, node, key, parent, child):
if node.name.value == 'secret':
return BREAK # Stop everything if we find a 'secret' field
return None
# Use visit(ast, visitor_instance)Unlike GraphQL.js which uses getter methods, graphql-core allows direct attribute access for several key properties on GraphQL types. This makes the API more Pythonic.
Use direct attribute access for:
GraphQLObjectType, GraphQLInterfaceType, and GraphQLInputObjectType (e.g., obj.fields instead of obj.getFields()).GraphQLObjectType.GraphQLUnionType.GraphQLEnumType.GraphQLSchema.GraphQL-core does not follow SemVer in the same way as GraphQL.js. Major version changes in GraphQL.js are reflected as minor version changes in GraphQL-core. Consequently, breaking changes can occur during minor version updates.
To ensure stability, it is recommended to use a compatible version specifier such as ~= 3.2.0 in your dependencies.
TypeInfo and TypeInfoVisitor classes. These provide context about the types being visited during the traversal.The experimental_execute_incrementally function provides a way to execute queries that can return results in chunks (incremental execution). This is useful for streaming large datasets or using @defer directives. The API uses several specialized classes to manage these states:
InitialIncrementalExecutionResult: The first part of an incremental response.SubsequentIncrementalExecutionResult: Parts of the response that follow the initial result.IncrementalResult: A container for the various parts of the incremental stream.IncrementalDeferResult: Specifically handles results related to @defer directives.When defining GraphQL types (like GraphQLInterfaceType or GraphQLObjectType), you may encounter situations where a field refers to a type that is still being defined (e.g., a Character interface having a field friends that returns a list of Character).
To resolve this circular dependency, you must pass the dictionary of fields as a thunk (a lambda function) rather than a direct dictionary. This allows the GraphQL-core engine to evaluate the fields only after the types have been initialized.
# Using a lambda (thunk) to allow the interface to refer to itself
character_interface = GraphQLInterfaceType('Character', lambda: {
'id': GraphQLField(GraphQLNonNull(GraphQLString)),
'friends': GraphQLField(GraphQLList(character_interface)), # Recursive reference
# ... other fields
}, resolve_type=get_character_type)Validation in graphql-core is driven by ValidationRule objects.
ValidationRule: The base class for all validation rules.ValidationContext: The base class for managing the state and execution of validation rules.ASTValidationContext: A context specifically designed for validating an Abstract Syntax Tree (AST).SDLValidationContext: A context specifically designed for validating Schema Definition Language (SDL).You can extend or customize validation by implementing your own ValidationRule or by providing a specific ValidationContext to the validate function.