Skip to main content
Version: 0.15

Types reference

Ariadne uses type annotations in its codebase.

Many parts of its API share or rely on common types, importable from ariadne.types module:

ContextValue​

Any
def get_context_value(request):

Context value that should be passed to [resolvers] through the info.context. Can be of any type.

If value is callable, it will be called with single argument:

  • request - representation of HTTP request specific to the web stack used by your API.

Return value will then be used as final context passed to resolvers.

ErrorFormatter​

def format_error(error, debug):

Callabe used to format errors into JSON-serializable form.

Should return a Python dict.

Required arguments​

error​

Instance of graphql.error.GraphQLError to be formatted.

debug​

Boolean controlling if debug information should be included in formatted data.

Extension​

class Extension()

Base class for extensions.

Methods​

format​

Extension.format(context)

Allows extensions to add data to extensions key in GraphQL response.

Should return a dict.

Note: Because creation of GraphQL response occurs before request handling finishes, format is called before request_finished and is last possible time to run extension's logic that requires it's result to be returned to the client.

Example​

Following extension will add timestamp entry with current timestamp to query's extensions:

from datetime import datetime


class TimestampExtension(Extension):
    def format(self, context):
        return {"timestamp": datetime.now().isoformat()}

Result:

{
  "data": {
    "hello": "world!"
  },
  "extensions": {
    "timestamp": "2019-06-28T18:34:31.171409"
  }
}

has_errors​

Extension.has_errors(errors, context)

Called with list of errors that occurred during query process. Not called if no errors were raised. Errors may come from validation, query parsing or query execution.

request_finished​

Extension.request_finished(context)

Called when query processing finishes.

request_started​

Extension.request_started(context)

Called when query processing starts.

resolve​

Extension.resolve(next_, parent, info[, **kwargs])

Used as middleware for fields resolver. Takes special next_ argument that is next resolver in resolvers chain that should be called.

Everything else is same as with regular resolvers.

ExtensionSync​

Synchronous counterpart of the Extension. All hooks are the same, but resolve hook can't be asynchronous.

GraphQLResult​

(success, response)

A tuple of two items:

  • success - web server should use status code 200 for response if this value is True and 400 if it wasn't.
  • response - response data that should be JSON-encoded and sent to client.

Resolver​

def resolver(obj, info[, **kwargs]):
class Resolver:
    def __call__(self, obj, info[, **kwargs]):
lambda obj, info[, **kwargs]:

A callable that query executor runs to resolve a specific field's value.

Returning None from resolver for field declared as non-nullable (eg.: field: Int!) will result in TypeError being raised by the query executor.

Required arguments​

obj​

Object from which the value should be resolved. Can be None for root resolvers (resolvers for Query, Mutation and Subscription fields) in server without set RootValue.

info​

Instance of the graphql.type.GraphQLResolveInfo. Is specific to the resolved field and query.

Has context attribute that contains ContextValue specific to the server implementation.

**kwargs​

If resolver's GraphQL field accepts any arguments, those arguments values will be passed to the field as kwargs:

type Query {
  sum(a: Int, b: Int): Int!
}
def resolve_users(obj, info, *, a=0, b=0):
    return a + b

If argument is declared required (eg.: a: Int!), default value is not required because value presence will be asserted by Query executor before resolver is called:

def resolve_users(obj, info, *, a, b=0):
    return a + b  # a is guaranteed to have a value

RootValue​

Any
def get_root_value(context, document):

The value that should be passed to the root-level resolvers as their obj. Can be of any type.

If value is callable, it will be called with two arguments:

  • context - containing current context_value.
  • document - graphql.ast.DocumentNode that was result of parsing current GraphQL query.

Return value will then be used as obj passed to root resolvers.

SchemaBindable​

class SchemaBindable()

Base class for bindables.

Methods​

bind_to_schema​

SchemaBindable.bind_to_schema(schema)

Method called by make_executable_schema with single argument being instance of GraphQL schema. Extending classes should override this method with custom logic that binds business mechanic to schema.

Subscriber​

async def source(value, info[, **kwargs])

Asynchronous generator that subscription field uses as data source for its resolver.

Required arguments​

root_value​

Root value set on the server.

info​

Instance of the graphql.type.GraphQLResolveInfo. Is specific to the resolved field and query.

Has context attribute that contains ContextValue specific to the server implementation.

**kwargs​

If subscriptions' GraphQL field accepts any arguments, those arguments values will be passed to the field as kwargs:

type Subscription {
  alerts(level: Int, age: Int): Int!
}
async def alerts_source(obj, info, *, level=0, age=0):
    yield from alerts.subscribe(level, age)

If argument is declared required (eg.: age: Int!), default value is not required because value presence will be asserted by Query executor before subscriber is called:

async def alerts_source(obj, info, *, level=0, age):
    yield from alerts.subscribe(level, age)

SubscriptionResult​

(success, response)

A tuple of two items:

  • success - web server should use status code 200 for response if this value is True and 400 if it wasn't.
  • response - asynchronous generator for response data that should be JSON-encoded and sent to client for the duration of the connection.