Graphene¶

Definition¶

You can create an Enum using classes:

import graphene

class Episode(graphene.Enum):
    NEWHOPE = 4
    EMPIRE = 5
    JEDI = 6

But also using instances of Enum:

Episode = graphene.Enum('Episode', [('NEWHOPE', 4), ('EMPIRE', 5), ('JEDI', 6)])

Value descriptions¶

It’s possible to add a description to a enum value, for that the the enum value needs to have the description property on it.

class Episode(graphene.Enum):
    NEWHOPE = 4
    EMPIRE = 5
    JEDI = 6

    @property
    def description(self):
        if self == Episode.NEWHOPE:
            return 'New Hope Episode'
        return 'Other episode'

Usage with Python Enums¶

In case the Enums are already defined it’s possible to reuse them using the Enum.from_enum function.

graphene.Enum.from_enum(AlreadyExistingPyEnum)

Notes¶

graphene.Enum uses enum.Enum internally (or a backport if that’s not available) and can be used in a similar way, with the exception of member getters.

In the Python Enum implementation you can access a member by initing the Enum.

from enum import Enum
class Color(Enum):
    RED = 1
    GREEN = 2
    BLUE = 3

assert Color(1) == Color.RED

However, in Graphene Enum you need to call get to have the same effect:

from graphene import Enum
class Color(Enum):
    RED = 1
    GREEN = 2
    BLUE = 3

assert Color.get(1) == Color.RED

Custom scalars¶

You can create custom scalars for your schema. The following is an example for creating a DateTime scalar:

import datetime
from graphene.types import Scalar
from graphql.language import ast

class DateTime(Scalar):
    '''DateTime Scalar Description'''

    @staticmethod
    def serialize(dt):
        return dt.isoformat()

    @staticmethod
    def parse_literal(node):
        if isinstance(node, ast.StringValue):
            return datetime.datetime.strptime(
                node.value, "%Y-%m-%dT%H:%M:%S.%f")

    @staticmethod
    def parse_value(value):
        return datetime.datetime.strptime(value, "%Y-%m-%dT%H:%M:%S.%f")

Mounting Scalars¶

Scalars mounted in a ObjectType, Interface or Mutation act as Fields.

class Person(graphene.ObjectType):
    name = graphene.String()

# Is equivalent to:
class Person(graphene.ObjectType):
    name = graphene.Field(graphene.String)

Note: when using the Field constructor directly, pass the type and not an instance.

Types mounted in a Field act as Arguments.

graphene.Field(graphene.String, to=graphene.String())

# Is equivalent to:
graphene.Field(graphene.String, to=graphene.Argument(graphene.String))

NonNull¶

import graphene

class Character(graphene.ObjectType):
    name = graphene.NonNull(graphene.String)

Here, we’re using a String type and marking it as Non-Null by wrapping it using the NonNull class. This means that our server always expects to return a non-null value for this field, and if it ends up getting a null value that will actually trigger a GraphQL execution error, letting the client know that something has gone wrong.

The previous NonNull code snippet is also equivalent to:

import graphene

class Character(graphene.ObjectType):
    name = graphene.String(required=True)

List¶

import graphene

class Character(graphene.ObjectType):
    appears_in = graphene.List(graphene.String)

Lists work in a similar way: We can use a type modifier to mark a type as a List, which indicates that this field will return a list of that type. It works the same for arguments, where the validation step will expect a list for that value.

Quick example¶

This example model defines a Character interface with a name. Human and Droid are two implementations of that interface.

import graphene

class Character(graphene.Interface):
    name = graphene.String()

# Human is a Character implementation
class Human(graphene.ObjectType):
    class Meta:
        interfaces = (Character, )

    born_in = graphene.String()

# Droid is a Character implementation
class Droid(graphene.ObjectType):
    class Meta:
        interfaces = (Character, )

    function = graphene.String()

name is a field on the Character interface that will also exist on both the Human and Droid ObjectTypes (as those implement the Character interface). Each ObjectType may define additional fields.

The above types have the following representation in a schema:

interface Character {
  name: String
}

type Droid implements Character {
  name: String
  function: String
}

type Human implements Character {
  name: String
  bornIn: String
}

Quick example¶

In this example UserFields is an AbstractType with a name. User and UserInput are two types that have their own fields plus the ones defined in UserFields.

import graphene

class UserFields(graphene.AbstractType):
    name = graphene.String()

class User(graphene.ObjectType, UserFields):
    pass

class UserInput(graphene.InputObjectType, UserFields):
    pass

type User {
  name: String
}

inputtype UserInput {
  name: String
}

Quick example¶

This example model defines a Person, with a first and a last name:

import graphene

class Person(graphene.ObjectType):
    first_name = graphene.String()
    last_name = graphene.String()
    full_name = graphene.String()

    def resolve_full_name(self, args, context, info):
        return '{} {}'.format(self.first_name, self.last_name)

first_name and last_name are fields of the ObjectType. Each field is specified as a class attribute, and each attribute maps to a Field.

The above Person ObjectType has the following schema representation:

type Person {
  firstName: String
  lastName: String
  fullName: String
}

Resolvers¶

A resolver is a method that resolves certain fields within a ObjectType. If not specififed otherwise, the resolver of a field is the resolve_{field_name} method on the ObjectType.

By default resolvers take the arguments args, context and info.

NOTE: The resolvers on a ObjectType are always treated as staticmethod``s, so the first argument to the resolver method ``self (or root) need not be an actual instance of the ObjectType.

import graphene

class Query(graphene.ObjectType):
    reverse = graphene.String(word=graphene.String())

    def resolve_reverse(self, args, context, info):
        word = args.get('word')
        return word[::-1]

import graphene

def reverse(root, args, context, info):
    word = args.get('word')
    return word[::-1]

class Query(graphene.ObjectType):
    reverse = graphene.String(word=graphene.String(), resolver=reverse)

Instances as data containers¶

Graphene ObjectTypes can act as containers too. So with the previous example you could do:

peter = Person(first_name='Peter', last_name='Griffin')

peter.first_name # prints "Peter"
peter.last_name # prints "Griffin"

Types¶

There are some cases where the schema cannot access all of the types that we plan to have. For example, when a field returns an Interface, the schema doesn’t know about any of the implementations.

In this case, we need to use the types argument when creating the Schema.

my_schema = Schema(
    query=MyRootQuery,
    types=[SomeExtraObjectType, ]
)

Querying¶

To query a schema, call the execute method on it.

my_schema.execute('{ lastName }')

Auto CamelCase field names¶

By default all field and argument names (that are not explicitly set with the name arg) will be converted from snake_case to camelCase (as the API is usually being consumed by a js/mobile client)

For example with the ObjectType

class Person(graphene.ObjectType):
    last_name = graphene.String()
    other_name = graphene.String(name='_other_Name')

the last_name field name is converted to lastName.

In case you don’t want to apply this transformation, provide a name argument to the field constructor. other_name converts to _other_Name (without further transformations).

Your query should look like

{
    lastName
    _other_Name
}

To disable this behavior, set the auto_camelcase to False upon schema instantiation.

my_schema = Schema(
    query=MyRootQuery,
    auto_camelcase=False,
)

Quick example¶

This example defines a Mutation:

import graphene

class CreatePerson(graphene.Mutation):
    class Input:
        name = graphene.String()

    ok = graphene.Boolean()
    person = graphene.Field(lambda: Person)

    @staticmethod
    def mutate(root, args, context, info):
        person = Person(name=args.get('name'))
        ok = True
        return CreatePerson(person=person, ok=ok)

person and ok are the output fields of the Mutation when is resolved.

Input attributes are the arguments that the Mutation CreatePerson needs for resolving, in this case name will be the only argument for the mutation.

mutate is the function that will be applied once the mutation is called.

So, we can finish our schema like this:

# ... the Mutation Class

class Person(graphene.ObjectType):
    name = graphene.String()
    age = graphene.Int()

class MyMutations(graphene.ObjectType):
    create_person = CreatePerson.Field()

# We must define a query for our schema
class Query(graphene.ObjectType):
    person = graphene.Field(Person)

schema = graphene.Schema(query=Query, mutation=MyMutations)

Executing the Mutation¶

Then, if we query (schema.execute(query_str)) the following:

mutation myFirstMutation {
    createPerson(name:"Peter") {
        person {
            name
        }
        ok
    }
}

We should receive:

{
    "createPerson": {
        "person" : {
            name: "Peter"
        },
        "ok": true
    }
}

InputFields and InputObjectTypes¶

InputFields are used in mutations to allow nested input data for mutations

To use an InputField you define an InputObjectType that specifies the structure of your input data

import graphene

class PersonInput(graphene.InputObjectType):
    name = graphene.String()
    age = graphene.Int()

class CreatePerson(graphene.Mutation):
    class Input:
        person_data = graphene.Argument(PersonInput)

    person = graphene.Field(lambda: Person)

    @staticmethod
    def mutate(root, args, context, info):
        p_data = args.get('person_data')

        name = p_data.get('name')
        age = p_data.get('age')

        person = Person(name=name, age=age)
        return CreatePerson(person=person)

Note that name and age are part of person_data now

Using the above mutation your new query would look like this:

mutation myFirstMutation {
    createPerson(personData: {name:"Peter", age: 24}) {
        person {
            name,
            age
        }
    }
}

InputObjectTypes can also be fields of InputObjectTypes allowing you to have as complex of input data as you need

import graphene

class LatLngInput(graphene.InputObjectType):
    lat = graphene.Float()
    lng = graphene.Float()

#A location has a latlng associated to it
class LocationInput(graphene.InputObjectType):
    name = graphene.String()
    latlng = graphene.InputField(LatLngInput)

Context¶

You can pass context to a query via context_value.

class Query(graphene.ObjectType):
    name = graphene.String()

    def resolve_name(self, args, context, info):
        return context.get('name')

schema = graphene.Schema(Query)
result = schema.execute('{ name }', context_value={'name': 'Syrus'})

Resolve arguments¶

Middlewares resolve is invoked with several arguments:

• next represents the execution chain. Call next to continue evalution.
• root is the root value object passed throughout the query.
• args is the hash of arguments passed to the field.
• context is the context object passed throughout the query.
• info is the resolver info.

Example¶

This middleware only continues evaluation if the field_name is not 'user'

class AuthorizationMiddleware(object):
    def resolve(self, next, root, args, context, info):
        if info.field_name == 'user':
            return None
        return next(root, args, context, info)

And then execute it with:

result = schema.execute('THE QUERY', middleware=[AuthorizationMiddleware()])

Batching¶

Batching is not an advanced feature, it’s DataLoader’s primary feature. Create loaders by providing a batch loading function.

from promise import Promise
from promise.dataloader import DataLoader

class UserLoader(DataLoader):
    def batch_load_fn(self, keys):
        # Here we return a promise that will result on the
        # corresponding user for each key in keys
        return Promise.resolve([get_user(id=key) for key in keys])

A batch loading function accepts an list of keys, and returns a Promise which resolves to an list of values.

Then load individual values from the loader. DataLoader will coalesce all individual loads which occur within a single frame of execution (executed once the wrapping promise is resolved) and then call your batch function with all requested keys.

user_loader = UserLoader()

user_loader.load(1).then(lambda user: user_loader.load(user.best_friend_id))

user_loader.load(2).then(lambda user: user_loader.load(user.best_friend_id))

A naive application may have issued four round-trips to a backend for the required information, but with DataLoader this application will make at most two.

DataLoader allows you to decouple unrelated parts of your application without sacrificing the performance of batch data-loading. While the loader presents an API that loads individual values, all concurrent requests will be coalesced and presented to your batch loading function. This allows your application to safely distribute data fetching requirements throughout your application and maintain minimal outgoing data requests.

Using with Graphene¶

DataLoader pairs nicely well with Graphene/GraphQL. GraphQL fields are designed to be stand-alone functions. Without a caching or batching mechanism, it’s easy for a naive GraphQL server to issue new database requests each time a field is resolved.

Consider the following GraphQL request:

{
  me {
    name
    bestFriend {
      name
    }
    friends(first: 5) {
      name
      bestFriend {
        name
      }
    }
  }
}

Naively, if me, bestFriend and friends each need to request the backend, there could be at most 13 database requests!

When using DataLoader, we could define the User type using our previous example with leaner code and at most 4 database requests, and possibly fewer if there are cache hits.

class User(graphene.ObjectType):
    name = graphene.String()
    best_friend = graphene.Field(lambda: User)
    friends = graphene.List(lambda: User)

    def resolve_best_friend(self, args, context, info):
        return user_loader.load(self.best_friend_id)

    def resolve_friends(self, args, context, info):
        return user_loader.load_many(self.friend_ids)

Quick example¶

Example usage (taken from the Starwars Relay example):

class Ship(graphene.ObjectType):
    '''A ship in the Star Wars saga'''
    class Meta:
        interfaces = (relay.Node, )

    name = graphene.String(description='The name of the ship.')

    @classmethod
    def get_node(cls, id, context, info):
        return get_ship(id)

The id returned by the Ship type when you query it will be a scalar which contains enough info for the server to know its type and its id.

For example, the instance Ship(id=1) will return U2hpcDox as the id when you query it (which is the base64 encoding of Ship:1), and which could be useful later if we want to query a node by its id.

Custom Nodes¶

You can use the predefined relay.Node or you can subclass it, defining custom ways of how a node id is encoded (using the to_global_id method in the class) or how we can retrieve a Node given a encoded id (with the get_node_from_global_id method).

Example of a custom node:

class CustomNode(Node):

    class Meta:
        name = 'Node'

    @staticmethod
    def to_global_id(type, id):
        return '{}:{}'.format(type, id)

    @staticmethod
    def get_node_from_global_id(global_id, context, info, only_type=None):
        type, id = global_id.split(':')
        if only_node:
            # We assure that the node type that we want to retrieve
            # is the same that was indicated in the field type
            assert type == only_node._meta.name, 'Received not compatible node.'

        if type == 'User':
            return get_user(id)
        elif type == 'Photo':
            return get_photo(id)

The get_node_from_global_id method will be called when CustomNode.Field is resolved.

Accessing node types¶

If we want to retrieve node instances from a global_id (scalar that identifies an instance by it’s type name and id), we can simply do Node.get_node_from_global_id(global_id, context, info).

In the case we want to restrict the instance retrieval to a specific type, we can do: Node.get_node_from_global_id(global_id, context, info, only_type=Ship). This will raise an error if the global_id doesn’t correspond to a Ship type.

Node Root field¶

As is required in the Relay specification, the server must implement a root field called node that returns a Node Interface.

For this reason, graphene provides the field relay.Node.Field, which links to any type in the Schema which implements Node. Example usage:

class Query(graphene.ObjectType):
    # Should be CustomNode.Field() if we want to use our custom Node
    node = relay.Node.Field()

Quick example¶

If we want to create a custom Connection on a given node, we have to subclass the Connection class.

In the following example, extra will be an extra field in the connection, and other an extra field in the Connection Edge.

class ShipConnection(Connection):
    extra = String()

    class Meta:
        node = Ship

    class Edge:
        other = String()

The ShipConnection connection class, will have automatically a pageInfo field, and a edges field (which is a list of ShipConnection.Edge). This Edge will have a node field linking to the specified node (in ShipConnection.Meta) and the field other that we defined in the class.

Connection Field¶

You can create connection fields in any Connection, in case any ObjectType that implements Node will have a default Connection.

class Faction(graphene.ObjectType):
    name = graphene.String()
    ships = relay.ConnectionField(ShipConnection)

    def resolve_ships(self, args, context, info):
        return []

Accepting Files¶

Mutations can also accept files, that’s how it will work with different integrations:

class UploadFile(graphene.ClientIDMutation):
     class Input:
         pass
         # nothing needed for uploading file

     # your return fields
     success = graphene.String()

    @classmethod
    def mutate_and_get_payload(cls, input, context, info):
        # When using it in Django, context will be the request
        files = context.FILES
        # Or, if used in Flask, context will be the flask global request
        # files = context.files

        # do something with files

        return UploadFile(success=True)