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.
← ariadne.exceptionsAriadne logo →