Skip to main content
Version: 0.10.0

API reference

Following items are importable directly from ariadne package:

EnumType​

EnumType(name, values)

Bindable used for mapping python values to enumeration members defined in GraphQL schema.

Required arguments​

name​

str with name of enumeration type defined in schema.

values​

dict, enum.Enum or enum.IntEnum instance that defines mappings between Enum members and values

Example​

Enum defined in schema:

enum ErrorType {
  NOT_FOUND
  PERMISSION_DENIED
  VALIDATION_ERROR
}

Python mapping using dict:

from ariadne import EnumType


error_type_enum = EnumType(
    "ErrorType",
    {
      "NOT_FOUND": "NotFound",
      "PERMISSION_DENIED": "PermissionDenied",
      "VALIDATION_ERROR": "ValidationError",
    }
)

Python mapping using enum.Enum:

from enum import Enum

from ariadne import EnumType


class ErrorType(Enum):
    NOT_FOUND = "NotFound"
    PERMISSION_DENIED = "PermissionDenied"
    VALIDATION_ERROR = "ValidationError"


error_type_enum = EnumType("ErrorType", ErrorType)

FallbackResolversSetter​

FallbackResolversSetter()

Bindable used for setting default resolvers on schema object types.

Use fallback_resolvers instead of instantiating FallbackResolversSetter.

Custom default resolver example​

You can create custom class extending FallbackResolversSetter to set custom default resolver on your GraphQL object types:

from ariadne import FallbackResolversSetter


def custom_resolver(obj, info, **kwargs) -> Any:
    try:
        return obj.get(info.field_name)
    except AttributeError:
        return getattr(obj, info.field_name, None)


class CustomFallbackResolversSetter(FallbackResolversSetter):
    def add_resolver_to_field(self, field_name, field_object):
        if field_object.resolve is None:
            field_object.resolve = custom_resolver

InterfaceType​

InterfaceType(name, type_resolver=None)

Bindable used for setting Python logic for GraphQL interfaces. Extends ObjectType.

Because InterfaceType extends ObjectType, it can also be used to set field resolvers.

InterfaceType will set its resolvers on fields of GraphQL types implementing the interface, but only if there is no resolver already set on the field.

Required arguments​

name​

str with name of interface type defined in schema.

Optional arguments​

type_resolver​

Valid resolver that is used to resolve the GraphQL type to which obj belongs. It should return a str with the name of the type. Not needed if obj contains a __typename key or attribute.

Methods​

set_type_resolver​

InterfaceType.set_type_resolver(type_resolver)

Sets type resolver used to resolve the str with name of GraphQL type to which obj belongs to.

Returns value passed to type_resolver argument.

type_resolver​

Decorator counterpart of set_type_resolver:

search_result = InterfaceType("SearchResult")


@search_result.type_resolver
def resolve_search_result_type(obj, info):
    ...

Decorator doesn't change or wrap the decorated function into any additional logic.

Example​

Interface type for search result that can be User or Thread, that defines the url field and sets default resolver for it:

interface SearchResult {
  url: String!
}
search_result = InterfaceType("SearchResult")


@search_result.type_resolver
def resolve_search_result_type(obj, info):
    if isinstance(obj, User):
        return "User"
    if isinstance(obj, Thread):
        return "Thread"


@search_result.field("url")
def resolve_search_result_url(obj, info):
    return obj.get_absolute_url()

MutationType​

MutationType()

Bindable used for setting Python logic for GraphQL mutation type. Has the same API as ObjectType, but has GraphQL type name hardcoded to Mutation.

This is an convenience utility that can be used in place of of ObjectType("Mutation").

ObjectType​

ObjectType(name)

Bindable used for setting Python logic for GraphQL object types.

Required arguments​

name​

str with name of an object type defined in schema.

Methods​

field​

Decorator that takes single parameter, name of GraphQL field, and sets decorated callable as a resolver for it:

user = ObjectType("User")


@user.field("posts")
def resolve_posts(obj, info):
    ...

Decorator doesn't change or wrap the decorated function into any additional logic.

set_alias​

ObjectType.set_alias(name, to)

Makes a field name defined in the schema resolve to property to of an object.

For example, if you want field username from schema resolve to attribute user_name of Python object, you can set an alias:

user = ObjectType("User")


user.set_alias("username", "user_name")

set_field​

ObjectType.set_field(name, resolver)

Sets resolver as resolver that will be used to resolve the GraphQL field named name.

Returns value passed to resolver argument.

QueryType​

QueryType()

Bindable used for setting Python logic for GraphQL mutation type. Has the same API as ObjectType, but has GraphQL type name hardcoded to Query.

This is an convenience utility that can be used in place of of ObjectType("Query").

ScalarType​

ScalarType(name, *, serializer=None, value_parser=None, literal_parser=None)

Bindable used for setting Python logic for GraphQL scalar type.

Required arguments​

name​

str with name of scalar type defined in schema.

serializer​

Callable that is called to convert scalar value into JSON-serializable form.

value_parser​

Callable that is called to convert JSON-serialized value back into Python form.

literal_parser​

Callable that is called to convert AST ValueNode value into Python form.

Methods​

literal_parser​

Decorator that sets decorated callable as literal parser for the scalar:

datetime = ScalarType("DateTime")


@datetime.literal_parser
def parse_datetime_literal(ast):
    ...

Decorator doesn't change or wrap the decorated function into any additional logic.

serializer​

Decorator that sets decorated callable as serializer for the scalar:

datetime = ScalarType("DateTime")


@datetime.serializer
def serialize_datetime(value):
    ...

Decorator doesn't change or wrap the decorated function into any additional logic.

set_serializer​

ScalarType.set_serializer(serializer)

Sets serializer callable as serializer for the scalar.

set_literal_parser​

ScalarType.set_value_parser(literal_parser)

Sets literal_parser callable as literal parser for the scalar.

set_value_parser​

ScalarType.set_value_parser(value_parser)

Sets value_parser callable as value parser for the scalar.

As convenience, this function will also set literal parser, if none was set already.

value_parser​

Decorator that sets decorated callable as value parser for the scalar:

datetime = ScalarType("DateTime")


@datetime.value_parser
def parse_datetime_value(value):
    ...

Decorator doesn't change or wrap the decorated function into any additional logic.

As convenience, this decorator will also set literal parser, if none was set already.

Example​

Read-only scalar that converts datetime object to string containing ISO8601 formatted date:

datetime = ScalarType("DateTime")


@datetime.serializer
def serialize_datetime(value):
    return value.isoformat()

Bidirectional scalar that converts date object to ISO8601 formatted date and reverses it back:

from datetime import date

date_scalar = ScalarType("Date")


@date_scalar.serializer
def serialize_datetime(value):
    return value.isoformat()


@date_scalar.value_parser
def serialize_datetime(value):
    return date.strptime(value, "%Y-%m-%d")

SchemaDirectiveVisitor​

SchemaDirectiveVisitor()

Base class for implementing schema directives.

Attributes​

args​

dict with arguments passed to the directive.

name​

str with name of the directive in the schema.

schema​

Instance of the GraphQLSchema, in which this directive is used.

Methods​

visit_argument_definition​

SchemaDirectiveVisitor.visit_argument_definition(argument, field, object_type)

Called during the executable schema creation for directives supporting the ARGUMENT_DEFINITION location set on schema fields arguments:

directive @example on ARGUMENT_DEFINITION

type Mutation {
    rotateToken(token: String @example): String
}

Takes following arguments:

  • argument - an instance of the GraphQLArgument.
  • field - an instance of the GraphQLField.
  • object_type - an instance of the GraphQLObjectType or GraphQLInterfaceType.

Must return an instance of the GraphQLArgument.

visit_enum​

SchemaDirectiveVisitor.visit_enum(enum)

Called during the executable schema creation for directives supporting the ENUM location set on enums:

directive @example on ENUM

enum ErrorType @example {
    NOT_FOUND
    PERMISSION_DENIED
    EXPIRED
}

Takes single argument, an instance GraphQLEnumType.

Must return an instance of the GraphQLEnumType.

visit_enum_value​

SchemaDirectiveVisitor.visit_enum_value(value, enum_type)

Called during the executable schema creation for directives supporting the ENUM_VALUE location set on enum values:

directive @example on ENUM

enum ErrorType {
    NOT_FOUND
    PERMISSION_DENIED @example
    EXPIRED
}

Takes two arguments:

  • value - an instance the GraphQLEnumValue.
  • enum_type - instance of the GraphQLEnumType to which this value belongs.

Must return an instance of the GraphQLEnumValue.

visit_field_definition​

SchemaDirectiveVisitor.visit_field_definition(field, object_type)

Called during the executable schema creation for directives supporting the FIELD_DEFINITION location set on objects and interfaces fields:

directive @example on FIELD_DEFINITION

type User {
    id: ID
    username: String @example
}

interface Searchable {
    document: String @example
}

Takes two arguments:

  • field - an instance the GraphQLField.
  • object_type - an instance of the GraphQLObjectType or GraphQLInterfaceType to which this field belongs.

Must return an instance of the GraphQLField.

visit_input_field_definition​

SchemaDirectiveVisitor.visit_input_field_definition(field, object_type)

Called during the executable schema creation for directives supporting the INPUT_FIELD_DEFINITION location set on inputs fields:

directive @example on INPUT_FIELD_DEFINITION

input UserInput {
    username: String @example
    email: String
}

Takes two arguments:

  • field - an instance the GraphQLInputField.
  • object_type - an instance of the GraphQLInputObjectType to which this field belongs.

Must return an instance of the GraphQLInputField.

visit_input_object​

SchemaDirectiveVisitor.visit_input_object(object_)

Called during the executable schema creation for directives supporting the INPUT_OBJECT location set on input types:

directive @example on INPUT_OBJECT

input UserInput @example {
    username: String
    email: String
}

Takes single argument, an instance GraphQLInputObjectType.

Must return an instance of the GraphQLInputObjectType.

visit_interface​

SchemaDirectiveVisitor.visit_interface(interface)

Called during the executable schema creation for directives supporting the INTERFACE location set on interfaces:

directive @example on INTERFACE

interface Searchable @example {
    document: String
}

Takes single argument, an instance GraphQLInterfaceType.

Must return an instance of the GraphQLInterfaceType.

visit_object​

SchemaDirectiveVisitor.visit_object(object_)

Called during the executable schema creation for directives supporting the OBJECT location set on objects:

directive @example on OBJECT

type User @example {
    id: ID
    username: String
}

Takes single argument, an instance GraphQLObjectType.

Must return an instance of the GraphQLObjectType.

visit_scalar​

SchemaDirectiveVisitor.visit_scalar(scalar)

Called during the executable schema creation for directives supporting the SCALAR location set on scalars:

directive @example on SCALAR

scalar Datetime @example

Takes single argument, an instance GraphQLScalarType.

Must return an instance of the GraphQLScalarType.

visit_schema​

SchemaDirectiveVisitor.visit_schema(schema)

Called during the executable schema creation for directives supporting the SCHEMA location set on schema:

directive @example on SCHEMA

schema @example {
    query: Query
}

Takes single argument, an instance of current GraphQLSchema. Should mutate this instance in place - returning anything from this method causes an ValueError to be raised.

visit_union​

SchemaDirectiveVisitor.visit_union(union)

Called during the executable schema creation for directives supporting the UNION location set on unions:

directive @example on UNION

union SearchResult = User | Thread @example

Takes single argument, an instance GraphQLUnionType.

Must return an instance of the GraphQLUnionType.

SnakeCaseFallbackResolversSetter​

SnakeCaseFallbackResolversSetter()

Bindable used for setting default resolvers on schema object types. Subclasses FallbackResolversSetter and sets default resolver that performs case conversion between GraphQL's camelCase and Python's snake_case:

type User {
  "Default resolver for this field will read value from contact_address"
  contactAddress: String
}

Use fallback_resolvers instead of instantiating SnakeCaseFallbackResolversSetter.

SubscriptionType​

SubscriptionType()

Bindable used for setting Python logic for GraphQL subscription type.

Like QueryType and MutationType this type is hardcoded to bind only to Subscription type in schema.

Methods​

field​

Decorator that takes single parameter, name of GraphQL field, and sets decorated callable as resolver for it.

subscription = SubscriptionType()


@subscription.field("alerts")
def resolve_alerts(obj, info):
    ...

Decorator doesn't change or wrap the decorated function into any additional logic.

Root resolvers set on subscription type are called with value returned by field's source resolver as first argument.

set_field​

SubscriptionType.set_field(name, resolver)

Sets resolver callable as resolver that will be used to resolve the GraphQL field named name.

Returns value passed to resolver argument.

Root resolvers set on subscription type are called with value returned by field's source resolver as first argument.

set_source​

SubscriptionType.set_source(name, generator)

Sets generator generator as source that will be used to resolve the GraphQL field named name.

Returns value passed to generator argument.

source​

Decorator that takes single parameter, name of GraphQL field, and sets decorated generator as source for it.

subscription = SubscriptionType()


@subscription.source("alerts")
async def alerts_generator(obj, info):
    ...

Decorator doesn't change or wrap the decorated function into any additional logic.

Example​

Simple counter API that counts to 5 and ends subscription:

type Subscription {
  counter: Int
}
import asyncio


subscription = SubscriptionType()


@subscription.source("counter")
async def counter_generator(obj, info):
    for i in range(5):
        await asyncio.sleep(1)
        yield i


@subscription.field("counter")
def counter_resolver(count, info):
    return count

UnionType​

UnionType(name, type_resolver=None)

Bindable used for setting Python logic for GraphQL union type.

Required arguments​

name​

str with name of union type defined in schema.

Optional arguments​

type_resolver​

Valid resolver that is used to resolve the GraphQL type to which obj belongs. It should return a str with the name of the type. Not needed if obj contains a __typename key or attribute.

Methods​

set_type_resolver​

UnionType.set_type_resolver(type_resolver)

Sets type resolver used to resolve the str with name of GraphQL type to which obj belongs to.

Returns value passed to type_resolver argument.

type_resolver​

Decorator counterpart of set_type_resolver:

search_result = UnionType("SearchResult")


@search_result.type_resolver
def resolve_search_result_type(obj, info):
    ...

Decorator doesn't change or wrap the decorated function into any additional logic.

Example​

Union type for search result that can be User or Thread:

union SearchResult = User | Thread
search_result = UnionType("SearchResult")


@search_result.type_resolver
def resolve_search_result_type(obj, info):
    if isinstance(obj, User):
        return "User"
    if isinstance(obj, Thread):
        return "Thread"

combine_multipart_data​

combine_multipart_data(operations, files_map, files)

Combines data from GraphQL multipart request into a query data.

Required arguments​

operations​

dict containing GraphQL query data or list of those.

files_map​

dict containing data mapping files to Query variables.

files​

dict (or object implementing __getitem__) containing uploaded files.

convert_camel_case_to_snake​

convert_camel_case_to_snake(graphql_name)

Utility function that converts GraphQL name written in camelCase to its Python snake_case counterpart.

convert_kwargs_to_snake_case​

@convert_kwargs_to_snake_case

Decorator for Resolver that recursively converts arguments case from camelCase to snake_case.

Example​

user field in schema defines firstName and lastName arguments which are converted by the decorator to first_name and last_name before being passed to the resolver:

from ariadne import QueryType, convert_kwargs_to_snake_case

query = QueryType()

type_defs = """
  type Query {
    user(firstName: String, lastName: String): User
  }
"""


@query.field("user")
@convert_kwargs_to_snake_case
def resolve_user(*_, first_name=None, last_name=None):
    ...

default_resolver​

def default_resolver(parent, info)

Default resolver used by Ariadne. If parent is dict, will use dict.get(info.field_name) to resolve the value. Uses getattr(parent, info.field_name, None) otherwise.

fallback_resolvers​

fallback_resolvers

Bindable instance of FallbackResolversSetter.

format_error​

def format_error(error, debug=False)

Default error formatter used by Ariadne. Takes instance of GraphQLError as first argument and debug flag as second.

Returns dict containing formatted error data ready for returning to API client.

If debug is True, updates returned data extensions key with exception dict that contains traceback to original Python exception and its context variables.

get_error_extension​

def get_error_extension(error)

Takes GraphQLError instance as only argument and returns dict with traceback and context of original Python exception. If error was not caused by exception in resolver, returns None instead.

get_formatted_error_context​

def get_formatted_error_context(error)

Takes exception instance as only argument and returns context values for it that are JSON-serializeable and can be included in the error result JSON.

Used by get_error_extension to include context in the exception JSON that Ariadne's default error formatter returns in debug mode.

get_formatted_error_traceback​

def get_formatted_error_traceback(error)

Takes exception instance as only argument and returns traceback (stacktrace) for it that is JSON-serializeable and can be included in the error result JSON.

Used by get_error_extension to include stacktrace in the exception JSON that Ariadne's default error formatter returns in debug mode.

gql​

def gql(value)

Utility function that takes GraphQL string as only argument, validates it and returns same string unchanged or raises GraphQLError if string was invalid.

Wrapping GraphQL strings declarations with this utility will make errors easier to track down and debug, as their traceback will point to place of declaration instead of Ariadne internals:

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

graphql​

async def graphql(schema, data, *, root_value=None, context_value=None, logger=None, debug=False, validation_rules, error_formatter, extensions=None, middleware, **kwargs)

Asynchronously executes query against the schema.

Returns GraphQLResult instance.

This function is an asynchronous coroutine so you will need to await on the returned value.

Coroutines will not work under WSGI. If your server uses WSGI (Django and Flask do), use graphql_sync instead.

Required arguments​

schema​

An executable schema created using make_executable_schema.

data​

Decoded input data sent by the client (eg. for POST requests in JSON format, pass in the structure decoded from JSON). Exact shape of data depends on the query type and protocol.

Configuration options​

context_value​

Context value to be passed to resolvers.

If context_value is callable, it should be evaluated on higher level of abstraction (in server integration) before passing to graphql().

root_value​

Root value to be passed to root resolvers.

logger​

String with the name of logger that should be used to log GraphQL errors. Defaults to ariadne.

debug​

If True will cause the server to include debug information in error responses.

validation_rules​

optional additional validators (as defined by graphql.validation.rules) to run before attempting to execute the query (the standard validators defined by the GraphQL specification are always used and There's no need to provide them here).

extensions​

List of classes extending Extension that will be used during query processing.

If extensions is callable, it should be evaluated on higher level of abstraction (in server integration) before passing to graphql().

error_formatter​

Error formatter that should be used to format errors.

Defaults to format_error.

middleware​

List of middleware that should be used during the query execution.

graphql_sync​

def graphql(schema, data, *, root_value=None, context_value=None, debug=False, validation_rules, error_formatter, middleware, **kwargs)

Synchronously executes query against schema.

Returns GraphQLResult instance.

Use this function instead of graphql to run queries in synchronous servers (WSGI, Django, Flask).

Required arguments​

See graphql required arguments.

Configuration options​

See graphql configuration options

load_schema_from_path​

def load_schema_from_path(path)

Loads GraphQL schema from path using different strategy depending on path's type:

  • If path is single file, reads it.
  • If path is directory, walks it recursively loading all .graphql files within it.

Files are validated using the same logic that gql uses, concatenated into single string and returned.

Raises GraphQLFileSyntaxError if any of the loaded files contained syntax errors.

make_executable_schema​

def make_executable_schema(type_defs, *bindables, directives=None)

Construct executable schema - GraphQL schema against which queries can be executed.

Returns GraphQLSchema instance that can be used to run queries on.

Required arguments​

type_defs​

string or list of strings with valid GraphQL types definitions.

Optional arguments​

bindables​

Bindable or list of bindables with Python logic to add to schema:

type_defs = ...  # valid type defs string

# Bindables can be passed as *args
schema = make_executable_schema(type_defs, query, user, datetime_scalar)

# ...or as list of types...
schema = make_executable_schema(type_defs, [query, user, datetime_scalar])

# ...or mixed!
third_party_bindables = [likes, likes_stats]
schema = make_executable_schema(type_defs, query, user, datetime_scalar, third_party_bindables)

Note

Passing bindables as list is supported for backwards-compatibility with Ariadne versions pre-0.8, and will be removed in future version of Ariadne. To future-proof your code, unpack lists of bindables using explicit syntax:

schema = make_executable_schema(type_defs, query, user, datetime_scalar, *third_party_bindables)

Configuration options​

directives​

dict that maps schema directives to their Python implementations. See schema directives documentation for more information and examples.

resolve_to​

def resolve_to(name)

Returns default_resolver that always resolves to named attribute. Used to create aliases by ObjectType.set_alias.

snake_case_fallback_resolvers​

snake_case_fallback_resolvers

Bindable instance of SnakeCaseFallbackResolversSetter.

subscribe​

async def subscribe(schema, data, *, root_value=None, context_value=None, debug=False, validation_rules, error_formatter, **kwargs)

Asynchronously executes subscription query against schema, usually made over the websocket. Takes same arguments and options as graphql except middleware.

This function is an asynchronous coroutine so you will need to await on the returned value.

Coroutines will not work under WSGI. If your server uses WSGI (Django and Flask do), use graphql_sync instead.

This function doesn't support extensions option.

unwrap_graphql_error​

def unwrap_graphql_error(error)

Unwraps GraphQLError recursively, returning its original_error attribute value until non-GraphQLError instance is found, or original_error attribute has no value.

upload_scalar​

upload_scalar

Instance of ScalarType that represents uploaded file.

See file uploads documentation for information about limitations and implementation specific differences in behaviour.