Version: 0.22

API reference

Following items are importable directly from ariadne package:

`EnumType`

class EnumType(SchemaBindable):
    ...

Bindable mapping Python values to enumeration members in a GraphQL schema.

Constructor

def __init__(
    self,
    name: str,
    values: Union[Dict[str, Any], Type[enum.Enum], Type[enum.IntEnum]],
):
    ...

Initializes the EnumType with name and values mapping.

Required arguments

name: a str with the name of GraphQL enum type in GraphQL schema to bind to.

values: a dict or enums.Enum with values to use to represent GraphQL enum's in Python logic.

Methods

`bind_to_schema`

def bind_to_schema(self, schema: GraphQLSchema) -> None:
    ...

Binds this EnumType instance to the instance of GraphQL schema.

`bind_to_default_values`

def bind_to_default_values(self, _schema: GraphQLSchema) -> None:
    ...

Populates default values of input fields and args in the GraphQL schema.

This step is required because GraphQL query executor doesn't perform a lookup for default values defined in schema. Instead it simply pulls the value from fields and arguments default_value attribute, which is None by default.

Deprecated: Ariadne versions before 0.22 used EnumType.bind_to_default_values method to fix default enum values embedded in the GraphQL schema. Ariadne 0.22 release introduces universal repair_schema_default_enum_values utility in its place.

`validate_graphql_type`

def validate_graphql_type(
    self,
    graphql_type: Optional[GraphQLNamedType],
) -> None:
    ...

Validates that schema's GraphQL type associated with this EnumType is an enum.

Example

Given following GraphQL enum:

enum UserRole {
  MEMBER
  MODERATOR
  ADMIN
}

You can use EnumType to map it's members to Python Enum:

user_role_type = EnumType(
    "UserRole",
    {
        "MEMBER": 0,
        "MODERATOR": 1,
        "ADMIN": 2,
    }
)

EnumType also works with dictionaries:

user_role_type = EnumType(
    "UserRole",
    {
        "MEMBER": 0,
        "MODERATOR": 1,
        "ADMIN": 2,
    }
)

`Extension`

class Extension:
    ...

Base class for extensions.

Subclasses of this class should override default methods to run custom logic during Query execution.

Methods

`request_started`

def request_started(self, context: ContextValue) -> None:
    ...

Extension hook executed at request's start.

`request_finished`

def request_finished(self, context: ContextValue) -> None:
    ...

Extension hook executed at request's end.

`resolve`

def resolve(
    self,
    next_: Resolver,
    obj: Any,
    info: GraphQLResolveInfo,
    **kwargs,
) -> Any:
    ...

Extension hook wrapping field's value resolution.

Arguments

next_: a resolver or next extension's resolve method.

obj: a Python data structure to resolve value from.

info: a GraphQLResolveInfo instance for executed resolver.

**kwargs: extra arguments from GraphQL to pass to resolver.

Example

resolve should handle both sync and async next_:

from inspect import iscoroutinefunction
from time import time

from ariadne.types import Extension, Resolver
from graphql import GraphQLResolveInfo
from graphql.pyutils import is_awaitable

class MyExtension(Extension):
    def __init__(self):
        self.paths = []

    def resolve(
        self, next_: Resolver, obj: Any, info: GraphQLResolveInfo, **kwargs
    ) -> Any:
        path = ".".join(map(str, info.path.as_list()))

        # Fast implementation for synchronous resolvers
        if not iscoroutinefunction(next_):
            start_time = time()
            result = next_(obj, info, **kwargs)
            self.paths.append((path, time() - start_time))
            return result

        # Create async closure for async `next_` that GraphQL
        # query executor will handle for us.
        async def async_my_extension():
            start_time = time()
            result = await next_(obj, info, **kwargs)
            if is_awaitable(result):
                result = await result
            self.paths.append((path, time() - start_time))
            return result

        # GraphQL query executor will execute this closure for us
        return async_my_extension()

`has_errors`

def has_errors(
    self,
    errors: List[GraphQLError],
    context: ContextValue,
) -> None:
    ...

Extension hook executed when GraphQL encountered errors.

`format`

def format(self, context: ContextValue) -> Optional[dict]:
    ...

Extension hook executed to retrieve extra data to include in result's extensions data.

`ExtensionManager`

class ExtensionManager:
    ...

Container and runner for extensions and middleware, used by the GraphQL servers.

Attributes

context: the ContextValue of type specific to the server.

extensions: a tuple with instances of initialized extensions.

extensions_reversed: a tuple created from reversing extensions.

Constructor

def __init__(
    self,
    extensions: Optional[ExtensionList] = None,
    context: Optional[ContextValue] = None,
):
    ...

Initializes extensions and stores them with context on instance.

Optional arguments

extensions: a list of Extension types to initialize.

context: the ContextValue of type specific to the server.

Methods

`as_middleware_manager`

def as_middleware_manager(
    self,
    middleware: MiddlewareList = None,
    manager_class: Optional[Type[MiddlewareManager]] = None,
) -> Optional[MiddlewareManager]:
    ...

Creates middleware manager instance combining middleware and extensions.

Returns instance of the type passed in manager_class argument or MiddlewareManager that query executor then uses.

Optional arguments

middleware: a list of Middleware instances

manager_class a type of middleware manager to use. MiddlewareManager is used if this argument is passed None or omitted.

`request`

def request(self) -> None:
    ...

A context manager that should wrap request processing.

Runs request_started hook at beginning and request_finished at the end of request processing, enabling APM extensions like ApolloTracing.

`has_errors`

def has_errors(self, errors: List[GraphQLError]) -> None:
    ...

Propagates GraphQL errors returned by GraphQL server to extensions.

Should be called only when there are errors.

`format`

def format(self) -> dict:
    ...

Gathers data from extensions for inclusion in server's response JSON.

This data can be retrieved from the extensions key in response JSON.

Returns dict with JSON-serializable data.

`FallbackResolversSetter`

class FallbackResolversSetter(SchemaBindable):
    ...

Bindable that recursively scans GraphQL schema for fields and explicitly sets their resolver to graphql.default_field_resolver package if they don't have any resolver set yet.

Deprecated: This class doesn't provide any utility for developers and only serves as a base for SnakeCaseFallbackResolversSetter which is being replaced by what we believe to be a better solution.

Because of this we are deprecating this utility. It will be removed in future Ariadne release.

Methods

`bind_to_schema`

def bind_to_schema(self, schema: GraphQLSchema) -> None:
    ...

Scans GraphQL schema for types with fields that don't have set resolver.

`add_resolvers_to_object_fields`

def add_resolvers_to_object_fields(
    self,
    type_object: GraphQLObjectType,
) -> None:
    ...

Sets explicit default resolver on a fields of an object that don't have any.

`add_resolver_to_field`

def add_resolver_to_field(self, _: str, field_object: GraphQLField) -> None:
    ...

Sets default_field_resolver as a resolver on a field that doesn't have any.

`InputType`

class InputType(SchemaBindable):
    ...

Bindable populating input types in a GraphQL schema with Python logic.

Constructor

def __init__(
    self,
    name: str,
    out_type: Optional[GraphQLInputFieldOutType] = None,
    out_names: Optional[Dict[str, str]] = None,
):
    ...

Initializes the InputType with a name and optionally out type and out names.

Required arguments

name: a str with the name of GraphQL object type in GraphQL schema to bind to.

Optional arguments

out_type: a GraphQLInputFieldOutType, Python callable accepting single argument, a dict with data from GraphQL query, required to return a Python representation of input type.

out_names: a Dict[str, str] with mappings from GraphQL field names to dict keys in a Python dictionary used to contain a data passed as input.

Methods

`bind_to_schema`

def bind_to_schema(self, schema: GraphQLSchema) -> None:
    ...

Binds this InputType instance to the instance of GraphQL schema.

if it has an out type function, it assigns it to GraphQL type's out_type attribute. If type already has other function set on it's out_type attribute, this type is replaced with new one.

If it has any out names set, it assigns those to GraphQL type's fields out_name attributes. If field already has other out name set on its out_name attribute, this name is replaced with the new one.

`validate_graphql_type`

def validate_graphql_type(
    self,
    graphql_type: Optional[GraphQLNamedType],
) -> None:
    ...

Validates that schema's GraphQL type associated with this InputType is an input.

Example input value represented as dataclass

Following code creates a GraphQL schema with object type named Query with single field which has an argument of an input type. It then uses the InputType to set ExampleInput dataclass as Python representation of this GraphQL type:

from dataclasses import dataclass

from ariadne import InputType, QueryType, make_executable_schema

@dataclass
class ExampleInput:
    id: str
    message: str

query_type = QueryType()

@query_type.field("repr")
def resolve_repr(*_, input: ExampleInput):
    return repr(input)

schema = make_executable_schema(
    """
    type Query {
        repr(input: ExampleInput): String!
    }

    input ExampleInput {
        id: ID!
        message: String!
    }
    """,
    query_type,
    # Lambda is used because out type (second argument of InputType)
    # is called with single dict and dataclass requires each value as
    # separate argument.
    InputType("ExampleInput", lambda data: ExampleInput(**data)),
)

Example input with its fields mapped to custom dict keys

Following code creates a GraphQL schema with object type named Query with single field which has an argument of an input type. It then uses the InputType to set custom "out names" values, mapping GraphQL shortMessage to message key in Python dict:

from ariadne import InputType, QueryType, make_executable_schema

query_type = QueryType()

@query_type.field("repr")
def resolve_repr(*_, input: dict):
    # Dict will have `id` and `message` keys
    input_id = input["id"]
    input_message = input["message"]
    return f"id: {input_id}, message: {input_message}"

schema = make_executable_schema(
    """
    type Query {
        repr(input: ExampleInput): String!
    }

    input ExampleInput {
        id: ID!
        shortMessage: String!
    }
    """,
    query_type,
    InputType("ExampleInput", out_names={"shortMessage": "message"}),
)

Example input value as dataclass with custom named fields

from dataclasses import dataclass

from ariadne import InputType, QueryType, make_executable_schema

@dataclass
class ExampleInput:
    id: str
    message: str

query_type = QueryType()

@query_type.field("repr")
def resolve_repr(*_, input: ExampleInput):
    return repr(input)

schema = make_executable_schema(
    """
    type Query {
        repr(input: ExampleInput): String!
    }

    input ExampleInput {
        id: ID!
        shortMessage: String!
    }
    """,
    query_type,
    InputType(
        "ExampleInput",
        lambda data: ExampleInput(**data),
        {"shortMessage": "message"},
    ),
)

`InterfaceType`

class InterfaceType(ObjectType):
    ...

Bindable populating interfaces in a GraphQL schema with Python logic.

Extends ObjectType, providing field decorator and set_field and set_alias methods. If those are used to set resolvers for interface's fields, those resolvers will instead be set on fields of GraphQL types implementing this interface, but only if those fields don't already have resolver of their own set by the ObjectType.

Type resolver

Because GraphQL fields using interface as their returning type can return any Python value from their resolver, GraphQL interfaces require special type of resolver called "type resolver" to function.

This resolver is called with the value returned by field's resolver and is required to return a string with a name of GraphQL type represented by Python value from the field:

def example_type_resolver(obj: Any, *_) -> str:
    if isinstance(obj, PythonReprOfUser):
        return "User"

    if isinstance(obj, PythonReprOfComment):
        return "Comment"

    raise ValueError(f"Don't know GraphQL type for '{obj}'!")

This resolver is not required if the GraphQL field returns a value that has the __typename attribute or dict key with a name of the GraphQL type:

user_data_dict = {"__typename": "User", ...}

# or...

class UserRepr:
    __typename: str = "User"

Constructor

def __init__(
    self,
    name: str,
    type_resolver: Optional[Resolver] = None,
):
    ...

Initializes the InterfaceType with a name and optional type_resolver.

Type resolver is required by InterfaceType to function properly, but can be set later using either set_type_resolver(type_resolver) setter or type_resolver decorator.

Required arguments

name: a str with the name of GraphQL interface type in GraphQL schema to bind to.

Optional arguments

type_resolver: a Resolver used to resolve a str with name of GraphQL type from it's Python representation.

Methods

`set_type_resolver`

def set_type_resolver(self, type_resolver: Resolver) -> Resolver:
    ...

Sets function as type resolver for this interface.

Can be used as a decorator. Also available through type_resolver alias:

interface_type = InterfaceType("MyInterface")

@interface_type.type_resolver
def type_resolver(obj: Any, *_) -> str:
    ...

`bind_to_schema`

def bind_to_schema(self, schema: GraphQLSchema) -> None:
    ...

Binds this InterfaceType instance to the instance of GraphQL schema.

Sets resolve_type attribute on GraphQL interface. If this attribute was previously set, it will be replaced to new value.

If this interface has any resolvers set, it also scans GraphQL schema for types implementing this interface and sets those resolvers on those types fields, but only if those fields don't already have other resolver set.

`validate_graphql_type`

def validate_graphql_type(
    self,
    graphql_type: Optional[GraphQLNamedType],
) -> None:
    ...

Validates that schema's GraphQL type associated with this InterfaceType is an interface.

Example

Following code creates a GraphQL schema with a field that returns random result of either User or Post GraphQL type. It also supports dict with __typename key that explicitly declares its GraphQL type:

import random
from dataclasses import dataclass
from ariadne import QueryType, InterfaceType, make_executable_schema

@dataclass
class UserModel:
    id: str
    name: str

@dataclass
class PostModel:
    id: str
    message: str

results = (
    UserModel(id=1, name="Bob"),
    UserModel(id=2, name="Alice"),
    UserModel(id=3, name="Jon"),
    PostModel(id=1, message="Hello world!"),
    PostModel(id=2, message="How's going?"),
    PostModel(id=3, message="Sure thing!"),
    {"__typename": "User", "id": 4, "name": "Polito"},
    {"__typename": "User", "id": 5, "name": "Aerith"},
    {"__typename": "Post", "id": 4, "message": "Good day!"},
    {"__typename": "Post", "id": 5, "message": "Whats up?"},
)

query_type = QueryType()

@query_type.field("result")
def resolve_random_result(*_):
    return random.choice(results)


result_type = InterfaceType("Result")

@result_type.type_resolver
def resolve_result_type(obj: UserModel | PostModel | dict, *_) -> str:
    if isinstance(obj, UserModel):
        return "User"

    if isinstance(obj, PostModel):
        return "Post"

    if isinstance(obj, dict) and obj.get("__typename"):
        return obj["__typename"]

    raise ValueError(f"Don't know GraphQL type for '{obj}'!")


schema = make_executable_schema(
    """
    type Query {
        result: Result!
    }

    interface Result {
        id: ID!
    }

    type User implements Result {
        id: ID!
        name: String!
    }

    type Post implements Result {
        id: ID!
        message: String!
    }
    """,
    query_type,
    result_type,
)

`MutationType`

class MutationType(ObjectType):
    ...

An convenience class for defining Mutation type.

Constructor

def __init__(self):
    ...

Initializes the MutationType with a GraphQL name set to Mutation.

Example

Both of those code samples have same result:

mutation_type = MutationType()

mutation_type = ObjectType("Mutation")

`ObjectType`

class ObjectType(SchemaBindable):
    ...

Bindable populating object types in a GraphQL schema with Python logic.

Constructor

def __init__(self, name: str):
    ...

Initializes the ObjectType with a name.

Required arguments

name: a str with the name of GraphQL object type in GraphQL schema to bind to.

Methods

`field`

def field(self, name: str) -> Callable[[Resolver], Resolver]:
    ...

Return a decorator that sets decorated function as a resolver for named field.

Wrapper for create_register_resolver that on runtime validates name to be a string.

Required arguments

name: a str with a name of the GraphQL object's field in GraphQL schema to bind decorated resolver to.

`create_register_resolver`

def create_register_resolver(
    self,
    name: str,
) -> Callable[[Resolver], Resolver]:
    ...

Return a decorator that sets decorated function as a resolver for named field.

Required arguments

name: a str with a name of the GraphQL object's field in GraphQL schema to bind decorated resolver to.

`set_field`

def set_field(self, name, resolver: Resolver) -> Resolver:
    ...

Set a resolver for the field name.

Required arguments

name: a str with a name of the GraphQL object's field in GraphQL schema to set this resolver for.

resolver: a Resolver function to use.

`set_alias`

def set_alias(self, name: str, to: str) -> None:
    ...

Set an alias resolver for the field name to given Python name.

Required arguments

name: a str with a name of the GraphQL object's field in GraphQL schema to set this resolver for.

to: a str of an attribute or dict key to resolve this field to.

`bind_to_schema`

def bind_to_schema(self, schema: GraphQLSchema) -> None:
    ...

Binds this ObjectType instance to the instance of GraphQL schema.

If it has any resolver functions set, it assigns those to GraphQL type's fields resolve attributes. If field already has other resolver set on its resolve attribute, this resolver is replaced with the new one.

`validate_graphql_type`

def validate_graphql_type(
    self,
    graphql_type: Optional[GraphQLNamedType],
) -> None:
    ...

Validates that schema's GraphQL type associated with this ObjectType is a type.

`bind_resolvers_to_graphql_type`

def bind_resolvers_to_graphql_type(
    self,
    graphql_type,
    replace_existing = True,
) -> None:
    ...

Binds this ObjectType instance to the instance of GraphQL schema.

Example

Following code creates a GraphQL schema with single object type named Query and uses ObjectType to set resolvers on its fields:

import random
from datetime import datetime

from ariadne import ObjectType, make_executable_schema

query_type = ObjectType("Query")

@query_type.field("diceRoll")
def resolve_dice_roll(*_):
    return random.int(1, 6)


@query_type.field("year")
def resolve_year(*_):
    return datetime.today().year


schema = make_executable_schema(
    """
    type Query {
        diceRoll: Int!
        year: Int!
    }
    """,
    query_type,
)

Example with objects in objects

When a field in the schema returns other GraphQL object, this object's resolvers are called with value returned from field's resolver. For example if there's an user field on the Query type that returns the User type, you don't have to resolve User fields in user resolver. In below example fullName field on User type is resolved from data on UserModel object that user field resolver on Query type returned:

import dataclasses
from ariadne import ObjectType, make_executable_schema

@dataclasses.dataclass
class UserModel:
    id: int
    username: str
    first_name: str
    last_name: str


users = [
    UserModel(
        id=1,
        username="Dany",
        first_name="Daenerys",
        last_name="Targaryen",
    ),
    UserModel(
        id=2,
        username="BlackKnight19",
        first_name="Cahir",
        last_name="Mawr Dyffryn aep Ceallach",
    ),
    UserModel(
        id=3,
        username="TheLady",
        first_name="Dorotea",
        last_name="Senjak",
    ),
]


# Query type resolvers return users, but don't care about fields
# of User type
query_type = ObjectType("Query")

@query_type.field("users")
def resolve_users(*_) -> list[UserModel]:
    # In real world applications this would be a database query
    # returning iterable with user results
    return users


@query_type.field("user")
def resolve_user(*_, id: str) -> UserModel | None:
    # In real world applications this would be a database query
    # returning single user or None

    try:
        # GraphQL ids are always strings
        clean_id = int(id)
    except (ValueError, TypeError):
        # We could raise "ValueError" instead
        return None

    for user in users:
        if user.id == id:
            return user

    return None


# User type resolvers don't know how to retrieve User, but know how to
# resolve User type fields from UserModel instance
user_type = ObjectType("User")

# Resolve "name" GraphQL field to "username" attribute
user_type.set_alias("name", "username")

# Resolve "fullName" field to combined first and last name
# `obj` argument will be populated by GraphQL with a value from
# resolver for field returning "User" type
@user_type.field("fullName")
def resolve_user_full_name(obj: UserModel, *_):
    return f"{obj.first_name} {obj.last_name}"


schema = make_executable_schema(
    """
    type Query {
        users: [User!]!
        user(id: ID!): User
    }

    type User {
        id: ID!
        name: String!
        fullName: String!
    }
    """,
    query_type,
    user_type,
)

`QueryType`

class QueryType(ObjectType):
    ...

An convenience class for defining Query type.

Constructor

def __init__(self):
    ...

Initializes the QueryType with a GraphQL name set to Query.

Example

Both of those code samples have same effect:

query_type = QueryType()

query_type = ObjectType("Query")

`ScalarType`

class ScalarType(SchemaBindable):
    ...

Bindable populating scalars in a GraphQL schema with Python logic.

GraphQL scalars implement default serialization and deserialization logic. This class is only useful when custom logic is needed, most commonly when Python representation of scalar's value is not JSON-serializable by default.

This logic can be customized for three steps:

Serialization

Serialization step converts Python representation of scalar's value to a JSON serializable format.

Serializer function takes single argument and returns a single, JSON serializable value:

def serialize_date(value: date) -> str:
    # Serialize dates as "YYYY-MM-DD" string
    return date.strftime("%Y-%m-%d")

Value parsing

Value parsing step converts value from deserialized JSON to Python representation.

Value parser function takes single argument and returns a single value:

def parse_date_str(value: str) -> date:
    try:
        # Parse "YYYY-MM-DD" string into date
        return datetime.strptime(value, "%Y-%m-%d").date()
    except (ValueError, TypeError):
        raise ValueError(
            f'"{value}" is not a date string in YYYY-MM-DD format.'
        )

Literal parsing

Literal parsing step converts value from GraphQL abstract syntax tree (AST) to Python representation.

Literal parser function takes two arguments, an AST node and a dict with query's variables and returns Python value:

def parse_date_literal(
    value: str, variable_values: dict[str, Any] = None
) -> date:
    if not isinstance(ast, StringValueNode):
        raise ValueError()

    try:
        # Parse "YYYY-MM-DD" string into date
        return datetime.strptime(ast.value, "%Y-%m-%d").date()
    except (ValueError, TypeError):
        raise ValueError(
            f'"{value}" is not a date string in YYYY-MM-DD format.'
        )

When scalar has custom value parser set, but not the literal parser, the GraphQL query executor will use default literal parser, and then call the value parser with it's return value. This mechanism makes custom literal parser unnecessary for majority of scalar implementations.

Scalar literals are always parsed twice: on query validation and during query execution.

Constructor

def __init__(
    self,
    name: str,
    *,
    serializer: Optional[GraphQLScalarSerializer],
    value_parser: Optional[GraphQLScalarValueParser],
    literal_parser: Optional[GraphQLScalarLiteralParser],
):
    ...

Initializes the ScalarType with a name.

Required arguments

name: a str with the name of GraphQL scalar in GraphQL schema to bind to.

Optional arguments

serializer: a function called to convert Python representation of scalar's value to JSON serializable format.

value_parser: a function called to convert a JSON deserialized value from query's "variables" JSON into scalar's Python representation.

literal_parser: a function called to convert an AST value from parsed query into scalar's Python representation.

Methods

`set_serializer`

def set_serializer(
    self,
    f: GraphQLScalarSerializer,
) -> GraphQLScalarSerializer:
    ...

Sets function as serializer for this scalar.

Can be used as a decorator. Also available through serializer alias:

date_scalar = ScalarType("Date")

@date_scalar.serializer
def serialize_date(value: date) -> str:
    # Serialize dates as "YYYY-MM-DD" string
    return date.strftime("%Y-%m-%d")

`set_value_parser`

def set_value_parser(
    self,
    f: GraphQLScalarValueParser,
) -> GraphQLScalarValueParser:
    ...

Sets function as value parser for this scalar.

Can be used as a decorator. Also available through value_parser alias:

date_scalar = ScalarType("Date")

@date_scalar.value_parser
def parse_date_str(value: str) -> date:
    try:
        # Parse "YYYY-MM-DD" string into date
        return datetime.strptime(value, "%Y-%m-%d").date()
    except (ValueError, TypeError):
        raise ValueError(
            f'"{value}" is not a date string in YYYY-MM-DD format.'
        )

`set_literal_parser`

def set_literal_parser(
    self,
    f: GraphQLScalarLiteralParser,
) -> GraphQLScalarLiteralParser:
    ...

Sets function as literal parser for this scalar.

Can be used as a decorator. Also available through literal_parser alias:

date_scalar = ScalarType("Date")

@date_scalar.literal_parser
def parse_date_literal(
    value: str, variable_values: Optional[dict[str, Any]] = None
) -> date:
    if not isinstance(ast, StringValueNode):
        raise ValueError()

    try:
        # Parse "YYYY-MM-DD" string into date
        return datetime.strptime(ast.value, "%Y-%m-%d").date()
    except (ValueError, TypeError):
        raise ValueError(
            f'"{value}" is not a date string in YYYY-MM-DD format.'
        )

`bind_to_schema`

def bind_to_schema(self, schema: GraphQLSchema) -> None:
    ...

Binds this ScalarType instance to the instance of GraphQL schema.

If it has serializer or parser functions set, it assigns those to GraphQL scalar's attributes. If scalar's attribute already has other function set, this function is replaced with the new one.

`validate_graphql_type`

def validate_graphql_type(
    self,
    graphql_type: Optional[GraphQLNamedType],
) -> None:
    ...

Validates that schema's GraphQL type associated with this ScalarType is a scalar.

Example datetime scalar

Following code defines a datetime scalar which converts Python datetime object to and from a string. Note that it without custom literal scalar:

from datetime import datetime

from ariadne import QueryType, ScalarType, make_executable_schema

scalar_type = ScalarType("DateTime")

@scalar_type.serializer
def serialize_value(val: datetime) -> str:
    return datetime.strftime(val, "%Y-%m-%d %H:%M:%S")


@scalar_type.value_parser
def parse_value(val) -> datetime:
    if not isinstance(val, str):
        raise ValueError(
            f"'{val}' is not a valid JSON representation "
        )

    return datetime.strptime(val, "%Y-%m-%d %H:%M:%S")


query_type = QueryType()

@query_type.field("now")
def resolve_now(*_):
    return datetime.now()


@query_type.field("diff")
def resolve_diff(*_, value):
    delta = datetime.now() - value
    return int(delta.total_seconds())


schema = make_executable_schema(
    """
    scalar DateTime

    type Query {
        now: DateTime!
        diff(value: DateTime): Int!
    }
    """,
    scalar_type,
    query_type,
)

Example generic scalar

Generic scalar is a pass-through scalar that doesn't perform any value conversion. Most common use case for those is for GraphQL fields that return unstructured JSON to the client. To create a scalar like this, you can simply include scalar Generic in your GraphQL schema:

from ariadne import QueryType, make_executable_schema

query_type = QueryType()

@query_type.field("rawJSON")
def resolve_raw_json(*_):
    # Note: this value needs to be JSON serializable
    return {
        "map": {
            "0": "Hello!",
            "1": "World!",
        },
        "list": [
            2,
            1,
            3,
            7,
        ],
    }


schema = make_executable_schema(
    """
    scalar Generic

    type Query {
        rawJSON: Generic!
    }
    """,
    query_type,
)

`SchemaBindable`

class SchemaBindable(Protocol):
    ...

Base class for bindable types.

Subclasses should extend the bind_to_schema method with custom logic for populating an instance of GraphQL schema with Python logic and values.

Methods

`bind_to_schema`

def bind_to_schema(self, schema: GraphQLSchema) -> None:
    ...

Binds this Schema[Bindable](bindables.md) instance to the instance of GraphQL schema.

Example

Example InputType bindable that sets Python names for fields of GraphQL input:

from ariadne import SchemaBindable
from graphql import GraphQLInputType

class InputType(SchemaBindable):
    _name: str
    _fields: dict[str, str]

    def __init__(self, name: str, fields: dict[str, str] | None):
        self._name = name
        self._fields = fields or {}

    def set_field_out_name(self, field: str, out_name: str):
        self._fields[field] = out_name

    def bind_to_schema(self, schema: GraphQLSchema) -> None:
        graphql_type = schema.get_type(self._name)
        if not graphql_type:
            raise ValueError(
                "Type %s is not defined in the schema" % self.name
            )
        if not isinstance(graphql_type, GraphQLInputType):
            raise ValueError(
                "%s is defined in the schema, but it is instance of %s (expected %s)"
                % (self.name, type(graphql_type).__name__, GraphQLInputType.__name__)
            )

        for field, out_name in self._fields.items():
            schema_field = graphql_type.fields.get(field)
            if not schema_field:
                raise ValueError(
                    "Type %s does not define the %s field" % (self.name, field)
                )

            schema_field.out_name = out_name

Usage:

from ariadne import QueryType, make_executable_schema

from .input_type import InputType
from .users.models import User

input_type = InputType(
    "UserInput",
    {
        "fullName": "full_name",
        "yearOfBirth": "year_of_birth",
    }
)

query_type = QueryType()

@query_type.field("countUsers")
def resolve_count_users(*_, input):
    qs = User.objects

    if input:
        if input["full_name"]:
            qs = qs.filter(full_name__ilike=input["full_name"])
        if input["year_of_birth"]:
            qs = qs.filter(dob__year=input["year_of_birth"])

    return qs.count()


schema = make_executable_schema(
    """
    type Query {
        countUsers(input: UserInput!): Int!
    }

    input UserInput {
        fullName: String
        yearOfBirth: Int
    }
    """,
    query_type,
    input_type,
)

`SchemaDirectiveVisitor`

class SchemaDirectiveVisitor(SchemaVisitor):
    ...

Base class for custom GraphQL directives.

Also implements class methods with container and management logic for directives at schema creation time, used by make_executable_schema.

Lifecycle

Separate instances of the GraphQL directive are created for each GraphQL schema item with the directive set on it. If directive is set on two fields, two separate instances of a directive will be created.

Constructor

def __init__(self, name, args, visited_type, schema, context):
    ...

Instantiates the directive for schema object.

Required arguments

name: a str with directive's name.

args: a dict with directive's arguments.

visited_type: an GraphQL type this directive is set on.

schema: the GraphQL schema instance.

context: None, unused but present for historic reasons.

Methods

`get_directive_declaration`

def get_directive_declaration(
    cls,
    directive_name: str,
    schema: GraphQLSchema,
) -> Optional[GraphQLDirective]:
    ...

Get GraphQL directive declaration from GraphQL schema by it's name.

Returns GraphQLDirective object or None.

Required arguments

directive_name: a str with name of directive in the GraphQL schema.

schema: a GraphQLSchema instance to retrieve the directive declaration from.

`get_declared_directives`

def get_declared_directives(
    cls,
    schema: GraphQLSchema,
    directive_visitors: Dict[str, Type['SchemaDirectiveVisitor']],
) -> Dict[str, GraphQLDirective]:
    ...

Get GraphQL directives declaration from GraphQL schema by their names.

Returns a dict where keys are strings with directive names in schema and values are GraphQLDirective objects with their declarations in the GraphQL schema.

Required arguments

directive_name: a str with name of directive in the GraphQL schema.

schema: a GraphQLSchema instance to retrieve the directive declaration from.

`visit_schema_directives`

def visit_schema_directives(
    cls,
    schema: GraphQLSchema,
    directive_visitors: Dict[str, Type['SchemaDirectiveVisitor']],
    *,
    context: Optional[Dict[str, Any]],
) -> Mapping[str, List['SchemaDirectiveVisitor']]:
    ...

Apply directives to the GraphQL schema.

Applied directives mutate the GraphQL schema in place.

Returns dict with names of GraphQL directives as keys and list of directive instances created for each directive name.

Required arguments

schema: a GraphQL schema to which directives should be applied.

directive_visitors: a dict with str and Type[SchemaDirectiveVisitor] pairs defining mapping of SchemaDirectiveVisitor types to their names in the GraphQL schema.

Optional arguments

context: None, unused but present for historic reasons.

Example schema visitors

SchemaDirectiveVisitor subclasses can implement any of below methods that will be called when directive is applied to different elements of GraphQL schema:

from ariadne import SchemaDirectiveVisitor
from graphql import (
    GraphQLArgument,
    GraphQLEnumType,
    GraphQLEnumValue,
    GraphQLField,
    GraphQLInputField,
    GraphQLInputObjectType,
    GraphQLInterfaceType,
    GraphQLObjectType,
    GraphQLScalarType,
    GraphQLSchema,
    GraphQLUnionType,
)

class MyDirective(SchemaDirectiveVisitor):
    def visit_schema(self, schema: GraphQLSchema) -> None:
        pass

    def visit_scalar(self, scalar: GraphQLScalarType) -> GraphQLScalarType:
        pass

    def visit_object(self, object_: GraphQLObjectType) -> GraphQLObjectType:
        pass

    def visit_field_definition(
        self,
        field: GraphQLField,
        object_type: Union[GraphQLObjectType, GraphQLInterfaceType],
    ) -> GraphQLField:
        pass

    def visit_argument_definition(
        self,
        argument: GraphQLArgument,
        field: GraphQLField,
        object_type: Union[GraphQLObjectType, GraphQLInterfaceType],
    ) -> GraphQLArgument:
        pass

    def visit_interface(self, interface: GraphQLInterfaceType) -> GraphQLInterfaceType:
        pass

    def visit_union(self, union: GraphQLUnionType) -> GraphQLUnionType:
        pass

    def visit_enum(self, type_: GraphQLEnumType) -> GraphQLEnumType:
        pass

    def visit_enum_value(
        self, value: GraphQLEnumValue, enum_type: GraphQLEnumType
    ) -> GraphQLEnumValue:
        pass

    def visit_input_object(
        self, object_: GraphQLInputObjectType
    ) -> GraphQLInputObjectType:
        pass

    def visit_input_field_definition(
        self, field: GraphQLInputField, object_type: GraphQLInputObjectType
    ) -> GraphQLInputField:
        pass

`SchemaNameConverter`

SchemaNameConverter = Callable[[str, GraphQLSchema, Tuple[str, ...]], str]

A type of a function implementing a strategy for names conversion in schema. Passed as an option to make_executable_schema and convert_schema_names functions.

Takes three arguments:

name: a str with schema name to convert.

schema: the GraphQL schema in which names are converted.

path: a tuple of str representing a path to the schema item which name is being converted.

Returns a string with the Python name to use.

`SnakeCaseFallbackResolversSetter`

class SnakeCaseFallbackResolversSetter(FallbackResolversSetter):
    ...

Subclass of FallbackResolversSetter that uses case-converting resolver instead of default_field_resolver.

Deprecated: Use convert_names_case from make_executable_schema instead.

Methods

`add_resolver_to_field`

def add_resolver_to_field(
    self,
    field_name: str,
    field_object: GraphQLField,
) -> None:
    ...

Sets case converting resolver on a field that doesn't have any.

`SubscriptionType`

class SubscriptionType(ObjectType):
    ...

Bindable populating the Subscription type in a GraphQL schema with Python logic.

Extends ObjectType, providing source decorator and set_source method, used to set subscription sources for it's fields.

Subscription sources ("subscribers")

Subscription source is a function that is an async generator. This function is used to subscribe to source of events or messages. It can also filter the messages by not yielding them.

Its signature is same as resolver:

async def source_fn(
    root_value: Any, info: GraphQLResolveInfo, **field_args
) -> Any:
    yield ...

Subscription resolvers

Subscription resolvers are called with message returned from the source. Their role is to convert this message into Python representation of a type associated with subscription's field in GraphQL schema. Its called with message yielded from source function as first argument.

def resolver_fn(
    message: Any, info: GraphQLResolveInfo, **field_args
) -> Any:
    # Subscription resolver can be sync and async.
    return ...

GraphQL arguments

When subscription field has arguments those arguments values are passed to both source and resolver functions.

Constructor

def __init__(self):
    ...

Initializes the SubscriptionType with a GraphQL name set to Subscription.

Methods

`source`

def source(self, name: str) -> Callable[[Subscriber], Subscriber]:
    ...

Return a decorator that sets decorated function as a source for named field.

Wrapper for create_register_subscriber that on runtime validates name to be a string.

Required arguments

name: a str with a name of the GraphQL object's field in GraphQL schema to bind decorated source to.

`create_register_subscriber`

def create_register_subscriber(
    self,
    name: str,
) -> Callable[[Subscriber], Subscriber]:
    ...

Return a decorator that sets decorated function as a source for named field.

Required arguments

name: a str with a name of the GraphQL object's field in GraphQL schema to bind decorated source to.

`set_source`

def set_source(self, name, generator: Subscriber) -> Subscriber:
    ...

Set a source for the field name.

Required arguments

name: a str with a name of the GraphQL object's field in GraphQL schema to set this source for.

generator: a Subscriber function to use as an source.

`bind_to_schema`

def bind_to_schema(self, schema: GraphQLSchema) -> None:
    ...

Binds this SubscriptionType instance to the instance of GraphQL schema.

If it has any previously set subscription resolvers or source functions, those will be replaced with new ones from this instance.

`bind_subscribers_to_graphql_type`

def bind_subscribers_to_graphql_type(self, graphql_type) -> None:
    ...

Binds this SubscriptionType instance's source functions.

Source functions are set to fields subscribe attributes.

Example source and resolver

from ariadne import SubscriptionType, make_executable_schema
from broadcast import broadcast

from .models import Post


subscription_type = SubscriptionType()


@subscription_type.source("post")
async def source_post(*_, category: Optional[str] = None) -> dict:
    async with broadcast.subscribe(channel="NEW_POSTS") as subscriber:
        async for event in subscriber:
            message = json.loads(event.message)
            # Send message to resolver if we don't filter
            if not category or message["category"] == category:
                yield message


@subscription_type.field("post")
async def resolve_post(
    message: dict, *_, category: Optional[str] = None
) -> Post:
    # Convert message to Post object that resolvers for Post type in
    # GraphQL schema understand.
    return await Post.get_one(id=message["post_id"])


schema = make_executable_schema(
    """
    type Query {
        "Valid schema must define the Query type"
        none: Int
    }

    type Subscription {
        post(category: ID): Post!
    }

    type Post {
        id: ID!
        author: String!
        text: String!
    }
    """,
    subscription_type
)

Example chat

Ariadne GraphQL Chat Example is the Github repository with GraphQL chat application, using Redis message backend, Broadcaster library for publishing and subscribing to messages and React.js client using Apollo-Client subscriptions.

`UnionType`

class UnionType(SchemaBindable):
    ...

Bindable populating interfaces in a GraphQL schema with Python logic.

Type resolver

Because GraphQL fields using union as their returning type can return any Python value from their resolver, GraphQL unions require special type of resolver called "type resolver" to function.

This resolver is called with the value returned by field's resolver and is required to return a string with a name of GraphQL type represented by Python value from the field:

def example_type_resolver(obj: Any, *_) -> str:
    if isinstance(obj, PythonReprOfUser):
        return "USer"

    if isinstance(obj, PythonReprOfComment):
        return "Comment"

    raise ValueError(f"Don't know GraphQL type for '{obj}'!")

This resolver is not required if the GraphQL field returns a value that has the __typename attribute or dict key with a name of the GraphQL type:

user_data_dict = {"__typename": "User", ...}

# or...

class UserRepr:
    __typename: str = "User"

Constructor

def __init__(
    self,
    name: str,
    type_resolver: Optional[Resolver] = None,
):
    ...

Initializes the UnionType with a name and optional type_resolver.

Type resolver is required by UnionType to function properly, but can be set later using either set_type_resolver(type_resolver) setter or type_resolver decorator.

Required arguments

name: a str with the name of GraphQL union type in GraphQL schema to bind to.

Optional arguments

type_resolver: a Resolver used to resolve a str with name of GraphQL type from it's Python representation.

Methods

`set_type_resolver`

def set_type_resolver(self, type_resolver: Resolver) -> Resolver:
    ...

Sets function as type resolver for this union.

Can be used as a decorator. Also available through type_resolver alias:

union_type = UnionType("MyUnion")

@union_type.type_resolver
def type_resolver(obj: Any, *_) -> str:
    ...

`bind_to_schema`

def bind_to_schema(self, schema: GraphQLSchema) -> None:
    ...

Binds this UnionType instance to the instance of GraphQL schema.

Sets resolve_type attribute on GraphQL union. If this attribute was previously set, it will be replaced to new value.

`validate_graphql_type`

def validate_graphql_type(
    self,
    graphql_type: Optional[GraphQLNamedType],
) -> None:
    ...

Validates that schema's GraphQL type associated with this UnionType is an union.

Example

import random
from dataclasses import dataclass
from ariadne import QueryType, UnionType, make_executable_schema

@dataclass
class UserModel:
    id: str
    name: str

@dataclass
class PostModel:
    id: str
    message: str

results = (
    UserModel(id=1, name="Bob"),
    UserModel(id=2, name="Alice"),
    UserModel(id=3, name="Jon"),
    PostModel(id=1, message="Hello world!"),
    PostModel(id=2, message="How's going?"),
    PostModel(id=3, message="Sure thing!"),
    {"__typename": "User", "id": 4, "name": "Polito"},
    {"__typename": "User", "id": 5, "name": "Aerith"},
    {"__typename": "Post", "id": 4, "message": "Good day!"},
    {"__typename": "Post", "id": 5, "message": "Whats up?"},
)

query_type = QueryType()

@query_type.field("result")
def resolve_random_result(*_):
    return random.choice(results)


result_type = UnionType("Result")

@result_type.type_resolver
def resolve_result_type(obj: UserModel | PostModel | dict, *_) -> str:
    if isinstance(obj, UserModel):
        return "User"

    if isinstance(obj, PostModel):
        return "Post"

    if isinstance(obj, dict) and obj.get("__typename"):
        return obj["__typename"]

    raise ValueError(f"Don't know GraphQL type for '{obj}'!")


schema = make_executable_schema(
    """
    type Query {
        result: Result!
    }

    union Result = User | Post

    type User {
        id: ID!
        name: String!
    }

    type Post {
        id: ID!
        message: String!
    }
    """,
    query_type,
    result_type,
)

`combine_multipart_data`

def combine_multipart_data(
    operations: Union[dict, list],
    files_map: dict,
    files: FilesDict,
) -> Union[dict, list]:
    ...

Populates operations variables with files using the files_map.

Utility function for integration developers.

Mutates operations in place, but also returns it.

Requires arguments

operations: a list or dict with GraphQL operations to populate the file variables in. It contains operationName, query and variables keys, but implementation only cares about variables being present.

files_map: a dict with mapping of files to operations. Keys correspond to keys in files dict, values are lists of strings with paths (eg.: variables.key.0 maps to operations["variables"]["key"]["0"]).

files: a dict of files. Keys are strings, values are environment specific representations of uploaded files.

Example

Following example uses combine_multipart_data to populate the image variable with file object from files, using the files_map to know which variable to replace.

# Single GraphQL operation
operations = {
    "operationName": "AvatarUpload",
    "query": """
        mutation AvatarUpload($type: String!, $image: Upload!) {
            avatarUpload(type: $type, image: $image) {
                success
                errors
            }
        }
    """,
    "variables": {"type": "SQUARE", "image": None}
}
files_map = {"0": ["variables.image"]}
files = {"0": UploadedFile(....)}

combine_multipart_data(operations, files_map, files

assert operations == {
    "variables": {"type": "SQUARE", "image": UploadedFile(....)}
}

`convert_camel_case_to_snake`

def convert_camel_case_to_snake(graphql_name: str) -> str:
    ...

Converts a string with camelCase name to snake_case.

Utility function used by Ariadne's name conversion logic for mapping GraphQL names using the camelCase convention to Python counterparts in snake_case.

Returns a string with converted name.

Required arguments

graphql_name: a str with name to convert.

Example

All characters in converted name are lowercased:

assert convert_camel_case_to_snake("URL") == "url"

_ is inserted before every uppercase character that's not first and is not preceded by other uppercase character:

assert convert_camel_case_to_snake("testURL") == "test_url"

_ is inserted before every uppercase character succeeded by lowercased character:

assert convert_camel_case_to_snake("URLTest") == "url_test"

_ is inserted before every digit that's not first and is not preceded by other digit:

assert convert_camel_case_to_snake("Rfc123") == "rfc_123"

`convert_kwargs_to_snake_case`

def convert_kwargs_to_snake_case(func: Callable) -> Callable:
    ...

Decorator for resolvers recursively converting their kwargs to snake_case.

Converts keys in kwargs dict from camelCase to snake_case using the convert_camel_case_to_snake function. Walks values recursively, applying same conversion to keys of nested dicts and dicts in lists of elements.

Returns decorated resolver function.

Deprecated: This decorator is deprecated and will be deleted in future version of Ariadne. Set out_names explicitly in your GraphQL schema or use the convert_schema_names option on make_executable_schema.

`convert_schema_names`

def convert_schema_names(
    schema: GraphQLSchema,
    name_converter: Optional[SchemaNameConverter],
) -> None:
    ...

Set mappings in GraphQL schema from camelCase names to snake_case.

This function scans GraphQL schema and:

If objects field has name in camelCase and this field doesn't have a resolver already set on it, new resolver is assigned to it that resolves it's value from object attribute or dict key named like snake_case version of field's name.

If object's field has argument in camelCase and this argument doesn't have the out_name attribute already set, this attribute is populated with argument's name converted to snake_case

If input's field has name in camelCase and it's out_name attribute is not already set, this attribute is populated with field's name converted to snake_case.

Schema is mutated in place.

Generally you shouldn't call this function yourself, as its part of make_executable_schema logic, but its part of public API for other libraries to use.

Required arguments

schema: a GraphQL schema to update.

name_converter: an SchemaNameConverter function to use to convert the names from camelCase to snake_case. If not provided, default one based on convert_camel_case_to_snake is used.

`fallback_resolvers`

fallback_resolvers = FallbackResolversSetter()

Bindable instance of FallbackResolversSetter.

Deprecated: This utility will be removed in future Ariadne release.

See FallbackResolversSetter for details.

`format_error`

def format_error(error: GraphQLError, debug: bool = False) -> dict:
    ...

Format the GraphQL error into JSON serializable format.

If debug is set to True, error's JSON will also include the extensions key with exception object containing error's context and stacktrace.

Returns a JSON-serializable dict with error representation.

Required arguments

error: an GraphQLError to convert into JSON serializable format.

Optional arguments

debug: a bool that controls if debug data should be included in result dict. Defaults to False.

`get_error_extension`

def get_error_extension(error: GraphQLError) -> Optional[dict]:
    ...

Get a JSON-serializable dict containing error's stacktrace and context.

Returns a JSON-serializable dict with stacktrace and context to include under error's extensions key in JSON response. Returns None if error has no stacktrace or wraps no exception.

Required arguments

error: an GraphQLError to return context and stacktrace for.

`get_formatted_error_context`

def get_formatted_error_context(error: Exception) -> Optional[dict]:
    ...

Get JSON-serializable context from Exception.

Returns a dict of strings, with every key being value name and value being repr() of it's Python value. Returns None if context is not available.

Required arguments

error: an Exception to return formatted context for.

`get_formatted_error_traceback`

def get_formatted_error_traceback(error: Exception) -> List[str]:
    ...

Get JSON-serializable stacktrace from Exception.

Returns list of strings, with every item being separate line from stacktrace.

This approach produces better results in GraphQL explorers which display every line under previous one but not always format linebreak characters for blocks of text.

Required arguments

error: an Exception to return formatted stacktrace for.

`gql`

def gql(value: str) -> str:
    ...

Verifies that given string is a valid GraphQL.

Provides definition time validation for GraphQL strings. Returns unmodified string. Some IDEs provide GraphQL syntax for highlighting those strings.

Examples

Python string in this code snippet will use GraphQL's syntax highlighting when viewed in VSCode:

type_defs = gql(
    """
    type Query {
        hello: String!
    }
    """
)

This code will raise a GraphQL parsing error:

type_defs = gql(
    """
    type Query {
        hello String!
    }
    """
)

`graphql`

async def graphql(
    schema: GraphQLSchema,
    data: Any,
    *,
    context_value: Optional[Any],
    root_value: Optional[RootValue],
    query_parser: Optional[QueryParser],
    query_validator: Optional[QueryValidator],
    query_document: Optional[DocumentNode],
    debug: bool,
    introspection: bool,
    logger: Union[None, str, Logger, LoggerAdapter],
    validation_rules: Optional[ValidationRules],
    error_formatter: ErrorFormatter,
    middleware: MiddlewareList,
    middleware_manager_class: Optional[Type[MiddlewareManager]],
    extensions: Optional[ExtensionList],
    execution_context_class: Optional[Type[ExecutionContext]],
    **kwargs,
) -> GraphQLResult:
    ...

Execute GraphQL query asynchronously.

Returns a tuple with two items:

bool: True when no errors occurred, False otherwise.

dict: an JSON-serializable dict with query result (defining either data, error, or both keys) that should be returned to client.

Required arguments

schema: a GraphQL schema instance that defines Query type.

data: a dict with query data (query string, optionally operationName string and variables dictionary).

Optional arguments

context_value: a context value to make accessible as 'context' attribute of second argument (info) passed to resolvers.

root_value: a RootValue to pass as first argument to resolvers set on Query and Mutation types.

query_parser: a QueryParser to use instead of default one. Is called with two arguments: context_value, and data dict.

query_validator: a QueryValidator to use instead of default one. Is called with five arguments: schema, 'document_ast', 'rules', 'max_errors' and 'type_info'.

query_document: an already parsed GraphQL query. Setting this option will prevent graphql from parsing query string from data second time.

debug: a bool for enabling debug mode. Controls presence of debug data in errors reported to client.

introspection: a bool for disabling introspection queries.

logger: a str with name of logger or logger instance to use for logging errors.

validation_rules: a list of or callable returning list of custom validation rules to use to validate query before it's executed.

error_formatter: an ErrorFormatter callable to use to convert GraphQL errors encountered during query execution to JSON-serializable format.

middleware: a list of or callable returning list of GraphQL middleware to use by query executor.

middleware_manager_class: a MiddlewareManager class to use by query executor.

extensions: a list of or callable returning list of extensions to use during query execution.

execution_context_class: ExecutionContext class to use by query executor.

**kwargs: any kwargs not used by graphql are passed to graphql.graphql.

`graphql_sync`

def graphql_sync(
    schema: GraphQLSchema,
    data: Any,
    *,
    context_value: Optional[Any],
    root_value: Optional[RootValue],
    query_parser: Optional[QueryParser],
    query_validator: Optional[QueryValidator],
    query_document: Optional[DocumentNode],
    debug: bool,
    introspection: bool,
    logger: Union[None, str, Logger, LoggerAdapter],
    validation_rules: Optional[ValidationRules],
    error_formatter: ErrorFormatter,
    middleware: MiddlewareList,
    middleware_manager_class: Optional[Type[MiddlewareManager]],
    extensions: Optional[ExtensionList],
    execution_context_class: Optional[Type[ExecutionContext]],
    **kwargs,
) -> GraphQLResult:
    ...

Execute GraphQL query synchronously.

Returns a tuple with two items:

bool: True when no errors occurred, False otherwise.

dict: an JSON-serializable dict with query result (defining either data, error, or both keys) that should be returned to client.

Required arguments

schema: a GraphQL schema instance that defines Query type.

data: a dict with query data (query string, optionally operationName string and variables dictionary).

Optional arguments

context_value: a context value to make accessible as 'context' attribute of second argument (info) passed to resolvers.

root_value: a RootValue to pass as first argument to resolvers set on Query and Mutation types.

query_parser: a QueryParser to use instead of default one. Is called with two arguments: context_value, and data dict.

query_validator: a QueryValidator to use instead of default one. Is called with five arguments: schema, 'document_ast', 'rules', 'max_errors' and 'type_info'.

query_document: an already parsed GraphQL query. Setting this option will prevent graphql_sync from parsing query string from data second time.