Type

GraphQL Type System

The graphql.type package is responsible for defining GraphQL types and schema.

Definition

Predicates

graphql.type.is_composite_type(type_: Any) TypeGuard[Union[GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType]]

Check whether this is a GraphQL composite type.

graphql.type.is_enum_type(type_: Any) TypeGuard[GraphQLEnumType]

Check whether this is a GraphQL enum type.

graphql.type.is_input_object_type(type_: Any) TypeGuard[GraphQLInputObjectType]

Check whether this is a GraphQL input type.

graphql.type.is_input_type(type_: Any) TypeGuard[Union[GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList, GraphQLNonNull[Union[GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList]]]]

Check whether this is a GraphQL input type.

graphql.type.is_interface_type(type_: Any) TypeGuard[GraphQLInterfaceType]

Check whether this is a GraphQL interface type.

graphql.type.is_leaf_type(type_: Any) TypeGuard[Union[GraphQLScalarType, GraphQLEnumType]]

Check whether this is a GraphQL leaf type.

graphql.type.is_list_type(type_: Any) TypeGuard[GraphQLList]

Check whether this is a GraphQL list type.

graphql.type.is_named_type(type_: Any) TypeGuard[GraphQLNamedType]

Check whether this is a named GraphQL type.

graphql.type.is_non_null_type(type_: Any) TypeGuard[GraphQLNonNull]

Check whether this is a non-null GraphQL type.

graphql.type.is_nullable_type(type_: Any) TypeGuard[Union[GraphQLScalarType, GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList]]

Check whether this is a nullable GraphQL type.

graphql.type.is_object_type(type_: Any) TypeGuard[GraphQLObjectType]

Check whether this is a graphql object type

graphql.type.is_output_type(type_: Any) TypeGuard[Union[GraphQLScalarType, GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType, GraphQLEnumType, GraphQLList, GraphQLNonNull[Union[GraphQLScalarType, GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType, GraphQLEnumType, GraphQLList]]]]

Check whether this is a GraphQL output type.

graphql.type.is_scalar_type(type_: Any) TypeGuard[GraphQLScalarType]

Check whether this is a GraphQL scalar type.

graphql.type.is_type(type_: Any) TypeGuard[GraphQLType]

Check whether this is a GraphQL type.

graphql.type.is_union_type(type_: Any) TypeGuard[GraphQLUnionType]

Check whether this is a GraphQL union type.

graphql.type.is_wrapping_type(type_: Any) TypeGuard[GraphQLWrappingType]

Check whether this is a GraphQL wrapping type.

Assertions

graphql.type.assert_abstract_type(type_: Any) Union[GraphQLInterfaceType, GraphQLUnionType]

Assert that this is a GraphQL abstract type.

graphql.type.assert_composite_type(type_: Any) Union[GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType]

Assert that this is a GraphQL composite type.

graphql.type.assert_enum_type(type_: Any) GraphQLEnumType

Assert that this is a GraphQL enum type.

graphql.type.assert_input_object_type(type_: Any) GraphQLInputObjectType

Assert that this is a GraphQL input type.

graphql.type.assert_input_type(type_: Any) Union[GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList, GraphQLNonNull[Union[GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList]]]

Assert that this is a GraphQL input type.

graphql.type.assert_interface_type(type_: Any) GraphQLInterfaceType

Assert that this is a GraphQL interface type.

graphql.type.assert_leaf_type(type_: Any) Union[GraphQLScalarType, GraphQLEnumType]

Assert that this is a GraphQL leaf type.

graphql.type.assert_list_type(type_: Any) GraphQLList

Assert that this is a GraphQL list type.

graphql.type.assert_named_type(type_: Any) GraphQLNamedType

Assert that this is a named GraphQL type.

graphql.type.assert_non_null_type(type_: Any) GraphQLNonNull

Assert that this is a non-null GraphQL type.

graphql.type.assert_nullable_type(type_: Any) Union[GraphQLScalarType, GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList]

Assert that this is a nullable GraphQL type.

graphql.type.assert_object_type(type_: Any) GraphQLObjectType

Assume that this is a graphql object type

graphql.type.assert_output_type(type_: Any) Union[GraphQLScalarType, GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType, GraphQLEnumType, GraphQLList, GraphQLNonNull[Union[GraphQLScalarType, GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType, GraphQLEnumType, GraphQLList]]]

Assert that this is a GraphQL output type.

graphql.type.assert_scalar_type(type_: Any) GraphQLScalarType

Assert that this is a GraphQL scalar type.

graphql.type.assert_type(type_: Any) GraphQLType

Assert that this is a GraphQL type.

graphql.type.assert_union_type(type_: Any) GraphQLUnionType

Assert that this is a GraphQL union type.

graphql.type.assert_wrapping_type(type_: Any) GraphQLWrappingType

Assert that this is a GraphQL wrapping type.

Un-modifiers

graphql.type.get_nullable_type(type_: None) None
graphql.type.get_nullable_type(type_: Union[GraphQLScalarType, GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList]) Union[GraphQLScalarType, GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList]
graphql.type.get_nullable_type(type_: GraphQLNonNull) Union[GraphQLScalarType, GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList]

Unwrap possible non-null type

graphql.type.get_named_type(type_: None) None
graphql.type.get_named_type(type_: GraphQLType) GraphQLNamedType

Unwrap possible wrapping type

Definitions

class graphql.type.GraphQLEnumType(name: str, *_args: Any, **_kwargs: Any)

Bases: GraphQLNamedType

Enum Type Definition

Some leaf values of requests and input values are Enums. GraphQL serializes Enum values as strings, however internally Enums can be represented by any kind of type, often integers. They can also be provided as a Python Enum. In this case, the flag names_as_values determines what will be used as internal representation. The default value of False will use the enum values, the value True will use the enum names, and the value None will use the members themselves.

Example:

RGBType = GraphQLEnumType('RGB', {
    'RED': 0,
    'GREEN': 1,
    'BLUE': 2
})

Example using a Python Enum:

class RGBEnum(enum.Enum):
    RED = 0
    GREEN = 1
    BLUE = 2

RGBType = GraphQLEnumType('RGB', enum.Enum)

Instead of raw values, you can also specify GraphQLEnumValue objects with more detail like description or deprecation information.

Note: If a value is not provided in a definition, the name of the enum value will be used as its internal value when the value is serialized.

__init__(name: str, values: Union[Dict[str, GraphQLEnumValue], Mapping[str, Any], type[enum.Enum]], names_as_values: bool | None = False, description: Optional[str] = None, extensions: Optional[dict[str, Any]] = None, ast_node: Optional[EnumTypeDefinitionNode] = None, extension_ast_nodes: Optional[Collection[EnumTypeExtensionNode]] = None) None
ast_node: graphql.language.ast.EnumTypeDefinitionNode | None
description: str | None
extension_ast_nodes: tuple[graphql.language.ast.EnumTypeExtensionNode, ...]
extensions: dict[str, Any]
name: str
parse_literal(value_node: ValueNode, _variables: Optional[dict[str, Any]] = None) Any

Parse literal value.

parse_value(input_value: str) Any

Parse an enum value.

reserved_types: Mapping[str, GraphQLNamedType] = {'Boolean': <GraphQLScalarType 'Boolean'>, 'Float': <GraphQLScalarType 'Float'>, 'ID': <GraphQLScalarType 'ID'>, 'Int': <GraphQLScalarType 'Int'>, 'String': <GraphQLScalarType 'String'>, '__Directive': <GraphQLObjectType '__Directive'>, '__DirectiveLocation': <GraphQLEnumType '__DirectiveLocation'>, '__EnumValue': <GraphQLObjectType '__EnumValue'>, '__Field': <GraphQLObjectType '__Field'>, '__InputValue': <GraphQLObjectType '__InputValue'>, '__Schema': <GraphQLObjectType '__Schema'>, '__Type': <GraphQLObjectType '__Type'>, '__TypeKind': <GraphQLEnumType '__TypeKind'>}
serialize(output_value: Any) str

Serialize an output value.

to_kwargs() GraphQLEnumTypeKwargs

Get corresponding arguments.

values: Dict[str, GraphQLEnumValue]
class graphql.type.GraphQLInputObjectType(name: str, *_args: Any, **_kwargs: Any)

Bases: GraphQLNamedType

Input Object Type Definition

An input object defines a structured collection of fields which may be supplied to a field argument.

Using NonNull will ensure that a value must be provided by the query.

Example:

NonNullFloat = GraphQLNonNull(GraphQLFloat())

class GeoPoint(GraphQLInputObjectType):
    name = 'GeoPoint'
    fields = {
        'lat': GraphQLInputField(NonNullFloat),
        'lon': GraphQLInputField(NonNullFloat),
        'alt': GraphQLInputField(
                  GraphQLFloat(), default_value=0)
    }

The outbound values will be Python dictionaries by default, but you can have them converted to other types by specifying an out_type function or class.

__init__(name: str, fields: Union[Callable[[], Mapping[str, GraphQLInputField]], Mapping[str, GraphQLInputField]], description: Optional[str] = None, out_type: Optional[Callable[[Dict[str, Any]], Any]] = None, extensions: Optional[dict[str, Any]] = None, ast_node: Optional[InputObjectTypeDefinitionNode] = None, extension_ast_nodes: Optional[Collection[InputObjectTypeExtensionNode]] = None) None
ast_node: graphql.language.ast.InputObjectTypeDefinitionNode | None
description: str | None
extension_ast_nodes: tuple[graphql.language.ast.InputObjectTypeExtensionNode, ...]
extensions: dict[str, Any]
property fields: Dict[str, GraphQLInputField]

Get provided fields, wrap them as GraphQLInputField if needed.

name: str
static out_type(value: dict[str, Any]) Any

Transform outbound values (this is an extension of GraphQL.js).

This default implementation passes values unaltered as dictionaries.

reserved_types: Mapping[str, GraphQLNamedType] = {'Boolean': <GraphQLScalarType 'Boolean'>, 'Float': <GraphQLScalarType 'Float'>, 'ID': <GraphQLScalarType 'ID'>, 'Int': <GraphQLScalarType 'Int'>, 'String': <GraphQLScalarType 'String'>, '__Directive': <GraphQLObjectType '__Directive'>, '__DirectiveLocation': <GraphQLEnumType '__DirectiveLocation'>, '__EnumValue': <GraphQLObjectType '__EnumValue'>, '__Field': <GraphQLObjectType '__Field'>, '__InputValue': <GraphQLObjectType '__InputValue'>, '__Schema': <GraphQLObjectType '__Schema'>, '__Type': <GraphQLObjectType '__Type'>, '__TypeKind': <GraphQLEnumType '__TypeKind'>}
to_kwargs() GraphQLInputObjectTypeKwargs

Get corresponding arguments.

class graphql.type.GraphQLInterfaceType(name: str, *_args: Any, **_kwargs: Any)

Bases: GraphQLNamedType

Interface Type Definition

When a field can return one of a heterogeneous set of types, an Interface type is used to describe what types are possible, what fields are in common across all types, as well as a function to determine which type is actually used when the field is resolved.

Example:

EntityType = GraphQLInterfaceType('Entity', {
        'name': GraphQLField(GraphQLString),
    })
__init__(name: str, fields: Union[Callable[[], Mapping[str, GraphQLField]], Mapping[str, GraphQLField]], interfaces: Optional[Union[Callable[[], Collection[GraphQLInterfaceType]], Collection[GraphQLInterfaceType]]] = None, resolve_type: Optional[Callable[[Any, GraphQLResolveInfo, Union[GraphQLInterfaceType, GraphQLUnionType]], Optional[Union[Awaitable[Optional[str]], str]]]] = None, description: Optional[str] = None, extensions: Optional[dict[str, Any]] = None, ast_node: Optional[InterfaceTypeDefinitionNode] = None, extension_ast_nodes: Optional[Collection[InterfaceTypeExtensionNode]] = None) None
ast_node: graphql.language.ast.InterfaceTypeDefinitionNode | None
description: str | None
extension_ast_nodes: tuple[graphql.language.ast.InterfaceTypeExtensionNode, ...]
extensions: dict[str, Any]
property fields: Dict[str, GraphQLField]

Get provided fields, wrapping them as GraphQLFields if needed.

property interfaces: tuple[graphql.type.definition.GraphQLInterfaceType, ...]

Get provided interfaces.

name: str
reserved_types: Mapping[str, GraphQLNamedType] = {'Boolean': <GraphQLScalarType 'Boolean'>, 'Float': <GraphQLScalarType 'Float'>, 'ID': <GraphQLScalarType 'ID'>, 'Int': <GraphQLScalarType 'Int'>, 'String': <GraphQLScalarType 'String'>, '__Directive': <GraphQLObjectType '__Directive'>, '__DirectiveLocation': <GraphQLEnumType '__DirectiveLocation'>, '__EnumValue': <GraphQLObjectType '__EnumValue'>, '__Field': <GraphQLObjectType '__Field'>, '__InputValue': <GraphQLObjectType '__InputValue'>, '__Schema': <GraphQLObjectType '__Schema'>, '__Type': <GraphQLObjectType '__Type'>, '__TypeKind': <GraphQLEnumType '__TypeKind'>}
resolve_type: Optional[Callable[[Any, GraphQLResolveInfo, Union[GraphQLInterfaceType, GraphQLUnionType]], Optional[Union[Awaitable[Optional[str]], str]]]]
to_kwargs() GraphQLInterfaceTypeKwargs

Get corresponding arguments.

class graphql.type.GraphQLObjectType(name: str, *_args: Any, **_kwargs: Any)

Bases: GraphQLNamedType

Object Type Definition

Almost all the GraphQL types you define will be object types. Object types have a name, but most importantly describe their fields.

Example:

AddressType = GraphQLObjectType('Address', {
    'street': GraphQLField(GraphQLString),
    'number': GraphQLField(GraphQLInt),
    'formatted': GraphQLField(GraphQLString,
        lambda obj, info, **args: f'{obj.number} {obj.street}')
})

When two types need to refer to each other, or a type needs to refer to itself in a field, you can use a lambda function with no arguments (a so-called “thunk”) to supply the fields lazily.

Example:

PersonType = GraphQLObjectType('Person', lambda: {
    'name': GraphQLField(GraphQLString),
    'bestFriend': GraphQLField(PersonType)
})
__init__(name: str, fields: Union[Callable[[], Mapping[str, GraphQLField]], Mapping[str, GraphQLField]], interfaces: Optional[Union[Callable[[], Collection[GraphQLInterfaceType]], Collection[GraphQLInterfaceType]]] = None, is_type_of: Optional[Callable[[Any, GraphQLResolveInfo], Union[Awaitable[bool], bool]]] = None, extensions: Optional[dict[str, Any]] = None, description: Optional[str] = None, ast_node: Optional[ObjectTypeDefinitionNode] = None, extension_ast_nodes: Optional[Collection[ObjectTypeExtensionNode]] = None) None
ast_node: graphql.language.ast.ObjectTypeDefinitionNode | None
description: str | None
extension_ast_nodes: tuple[graphql.language.ast.ObjectTypeExtensionNode, ...]
extensions: dict[str, Any]
property fields: Dict[str, GraphQLField]

Get provided fields, wrapping them as GraphQLFields if needed.

property interfaces: tuple[graphql.type.definition.GraphQLInterfaceType, ...]

Get provided interfaces.

is_type_of: Optional[Callable[[Any, GraphQLResolveInfo], Union[Awaitable[bool], bool]]]
name: str
reserved_types: Mapping[str, GraphQLNamedType] = {'Boolean': <GraphQLScalarType 'Boolean'>, 'Float': <GraphQLScalarType 'Float'>, 'ID': <GraphQLScalarType 'ID'>, 'Int': <GraphQLScalarType 'Int'>, 'String': <GraphQLScalarType 'String'>, '__Directive': <GraphQLObjectType '__Directive'>, '__DirectiveLocation': <GraphQLEnumType '__DirectiveLocation'>, '__EnumValue': <GraphQLObjectType '__EnumValue'>, '__Field': <GraphQLObjectType '__Field'>, '__InputValue': <GraphQLObjectType '__InputValue'>, '__Schema': <GraphQLObjectType '__Schema'>, '__Type': <GraphQLObjectType '__Type'>, '__TypeKind': <GraphQLEnumType '__TypeKind'>}
to_kwargs() GraphQLObjectTypeKwargs

Get corresponding arguments.

class graphql.type.GraphQLScalarType(name: str, *_args: Any, **_kwargs: Any)

Bases: GraphQLNamedType

Scalar Type Definition

The leaf values of any request and input values to arguments are Scalars (or Enums) and are defined with a name and a series of functions used to parse input from ast or variables and to ensure validity.

If a type’s serialize function returns None, then an error will be raised and a None value will be returned in the response. It is always better to validate.

Example:

def serialize_odd(value: Any) -> int:
    try:
        value = int(value)
    except ValueError:
        raise GraphQLError(
            f"Scalar 'Odd' cannot represent '{value}'"
            " since it is not an integer.")
    if not value % 2:
        raise GraphQLError(
            f"Scalar 'Odd' cannot represent '{value}' since it is even.")
    return value

odd_type = GraphQLScalarType('Odd', serialize=serialize_odd)
__init__(name: str, serialize: Optional[Callable[[Any], Any]] = None, parse_value: Optional[Callable[[Any], Any]] = None, parse_literal: Optional[Callable[[ValueNode, Optional[Dict[str, Any]]], Any]] = None, description: Optional[str] = None, specified_by_url: Optional[str] = None, extensions: Optional[dict[str, Any]] = None, ast_node: Optional[ScalarTypeDefinitionNode] = None, extension_ast_nodes: Optional[Collection[ScalarTypeExtensionNode]] = None) None
ast_node: graphql.language.ast.ScalarTypeDefinitionNode | None
description: str | None
extension_ast_nodes: tuple[graphql.language.ast.ScalarTypeExtensionNode, ...]
extensions: dict[str, Any]
name: str
parse_literal(node: ValueNode, variables: Optional[dict[str, Any]] = None) Any

Parses an externally provided literal value to use as an input.

This default method uses the parse_value method and should be replaced with a more specific version when creating a scalar type.

static parse_value(value: Any) Any

Parses an externally provided value to use as an input.

This default method just passes the value through and should be replaced with a more specific version when creating a scalar type.

reserved_types: Mapping[str, GraphQLNamedType] = {'Boolean': <GraphQLScalarType 'Boolean'>, 'Float': <GraphQLScalarType 'Float'>, 'ID': <GraphQLScalarType 'ID'>, 'Int': <GraphQLScalarType 'Int'>, 'String': <GraphQLScalarType 'String'>, '__Directive': <GraphQLObjectType '__Directive'>, '__DirectiveLocation': <GraphQLEnumType '__DirectiveLocation'>, '__EnumValue': <GraphQLObjectType '__EnumValue'>, '__Field': <GraphQLObjectType '__Field'>, '__InputValue': <GraphQLObjectType '__InputValue'>, '__Schema': <GraphQLObjectType '__Schema'>, '__Type': <GraphQLObjectType '__Type'>, '__TypeKind': <GraphQLEnumType '__TypeKind'>}
static serialize(value: Any) Any

Serializes an internal value to include in a response.

This default method just passes the value through and should be replaced with a more specific version when creating a scalar type.

specified_by_url: str | None
to_kwargs() GraphQLScalarTypeKwargs

Get corresponding arguments.

class graphql.type.GraphQLUnionType(name: str, *_args: Any, **_kwargs: Any)

Bases: GraphQLNamedType

Union Type Definition

When a field can return one of a heterogeneous set of types, a Union type is used to describe what types are possible as well as providing a function to determine which type is actually used when the field is resolved.

Example:

def resolve_type(obj, _info, _type):
    if isinstance(obj, Dog):
        return DogType()
    if isinstance(obj, Cat):
        return CatType()

PetType = GraphQLUnionType('Pet', [DogType, CatType], resolve_type)
__init__(name: str, types: Union[Callable[[], Collection[GraphQLObjectType]], Collection[GraphQLObjectType]], resolve_type: Optional[Callable[[Any, GraphQLResolveInfo, Union[GraphQLInterfaceType, GraphQLUnionType]], Optional[Union[Awaitable[Optional[str]], str]]]] = None, description: Optional[str] = None, extensions: Optional[dict[str, Any]] = None, ast_node: Optional[UnionTypeDefinitionNode] = None, extension_ast_nodes: Optional[Collection[UnionTypeExtensionNode]] = None) None
ast_node: graphql.language.ast.UnionTypeDefinitionNode | None
description: str | None
extension_ast_nodes: tuple[graphql.language.ast.UnionTypeExtensionNode, ...]
extensions: dict[str, Any]
name: str
reserved_types: Mapping[str, GraphQLNamedType] = {'Boolean': <GraphQLScalarType 'Boolean'>, 'Float': <GraphQLScalarType 'Float'>, 'ID': <GraphQLScalarType 'ID'>, 'Int': <GraphQLScalarType 'Int'>, 'String': <GraphQLScalarType 'String'>, '__Directive': <GraphQLObjectType '__Directive'>, '__DirectiveLocation': <GraphQLEnumType '__DirectiveLocation'>, '__EnumValue': <GraphQLObjectType '__EnumValue'>, '__Field': <GraphQLObjectType '__Field'>, '__InputValue': <GraphQLObjectType '__InputValue'>, '__Schema': <GraphQLObjectType '__Schema'>, '__Type': <GraphQLObjectType '__Type'>, '__TypeKind': <GraphQLEnumType '__TypeKind'>}
resolve_type: Optional[Callable[[Any, GraphQLResolveInfo, Union[GraphQLInterfaceType, GraphQLUnionType]], Optional[Union[Awaitable[Optional[str]], str]]]]
to_kwargs() GraphQLUnionTypeKwargs

Get corresponding arguments.

property types: tuple[graphql.type.definition.GraphQLObjectType, ...]

Get provided types.

Type Wrappers

class graphql.type.GraphQLList(type_: GT)

Bases: GraphQLWrappingType[GT]

List Type Wrapper

A list is a wrapping type which points to another type. Lists are often created within the context of defining the fields of an object type.

Example:

class PersonType(GraphQLObjectType):
    name = 'Person'

    @property
    def fields(self):
        return {
            'parents': GraphQLField(GraphQLList(PersonType())),
            'children': GraphQLField(GraphQLList(PersonType())),
        }
__init__(type_: GT) None
of_type: GT
class graphql.type.GraphQLNonNull(type_: GNT)

Bases: GraphQLWrappingType[GNT]

Non-Null Type Wrapper

A non-null is a wrapping type which points to another type. Non-null types enforce that their values are never null and can ensure an error is raised if this ever occurs during a request. It is useful for fields which you can make a strong guarantee on non-nullability, for example usually the id field of a database row will never be null.

Example:

class RowType(GraphQLObjectType):
    name = 'Row'
    fields = {
        'id': GraphQLField(GraphQLNonNull(GraphQLString()))
    }

Note: the enforcement of non-nullability occurs within the executor.

__init__(type_: GNT) None
of_type: GT

Types

graphql.type.GraphQLAbstractType

alias of Union[GraphQLInterfaceType, GraphQLUnionType]

class graphql.type.GraphQLArgument(type_: Union[GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList, GraphQLNonNull[Union[GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList]]], default_value: Any = Undefined, description: Optional[str] = None, deprecation_reason: Optional[str] = None, out_name: Optional[str] = None, extensions: Optional[dict[str, Any]] = None, ast_node: Optional[InputValueDefinitionNode] = None)

Bases: object

Definition of a GraphQL argument

__init__(type_: Union[GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList, GraphQLNonNull[Union[GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList]]], default_value: Any = Undefined, description: Optional[str] = None, deprecation_reason: Optional[str] = None, out_name: Optional[str] = None, extensions: Optional[dict[str, Any]] = None, ast_node: Optional[InputValueDefinitionNode] = None) None
ast_node: graphql.language.ast.InputValueDefinitionNode | None
default_value: Any
deprecation_reason: str | None
description: str | None
extensions: dict[str, Any]
out_name: str | None
to_kwargs() GraphQLArgumentKwargs

Get corresponding arguments.

type: Union[GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList, GraphQLNonNull[Union[GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList]]]
graphql.type.GraphQLArgumentMap

alias of Dict[str, GraphQLArgument]

graphql.type.GraphQLCompositeType

alias of Union[GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType]

class graphql.type.GraphQLEnumValue(value: Optional[Any] = None, description: Optional[str] = None, deprecation_reason: Optional[str] = None, extensions: Optional[dict[str, Any]] = None, ast_node: Optional[EnumValueDefinitionNode] = None)

Bases: object

A GraphQL enum value.

__init__(value: Optional[Any] = None, description: Optional[str] = None, deprecation_reason: Optional[str] = None, extensions: Optional[dict[str, Any]] = None, ast_node: Optional[EnumValueDefinitionNode] = None) None
ast_node: graphql.language.ast.EnumValueDefinitionNode | None
deprecation_reason: str | None
description: str | None
extensions: dict[str, Any]
to_kwargs() GraphQLEnumValueKwargs

Get corresponding arguments.

value: Any
graphql.type.GraphQLEnumValueMap

alias of Dict[str, GraphQLEnumValue]

class graphql.type.GraphQLField(type_: Union[GraphQLScalarType, GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType, GraphQLEnumType, GraphQLList, GraphQLNonNull[Union[GraphQLScalarType, GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType, GraphQLEnumType, GraphQLList]]], args: Optional[Dict[str, GraphQLArgument]] = None, resolve: Optional[Callable[[...], Any]] = None, subscribe: Optional[Callable[[...], Any]] = None, description: Optional[str] = None, deprecation_reason: Optional[str] = None, extensions: Optional[dict[str, Any]] = None, ast_node: Optional[FieldDefinitionNode] = None)

Bases: object

Definition of a GraphQL field

__init__(type_: Union[GraphQLScalarType, GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType, GraphQLEnumType, GraphQLList, GraphQLNonNull[Union[GraphQLScalarType, GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType, GraphQLEnumType, GraphQLList]]], args: Optional[Dict[str, GraphQLArgument]] = None, resolve: Optional[Callable[[...], Any]] = None, subscribe: Optional[Callable[[...], Any]] = None, description: Optional[str] = None, deprecation_reason: Optional[str] = None, extensions: Optional[dict[str, Any]] = None, ast_node: Optional[FieldDefinitionNode] = None) None
args: Dict[str, GraphQLArgument]
ast_node: graphql.language.ast.FieldDefinitionNode | None
deprecation_reason: str | None
description: str | None
extensions: dict[str, Any]
resolve: Optional[Callable[[...], Any]]
subscribe: Optional[Callable[[...], Any]]
to_kwargs() GraphQLFieldKwargs

Get corresponding arguments.

type: Union[GraphQLScalarType, GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType, GraphQLEnumType, GraphQLList, GraphQLNonNull[Union[GraphQLScalarType, GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType, GraphQLEnumType, GraphQLList]]]
graphql.type.GraphQLFieldMap

alias of Dict[str, GraphQLField]

class graphql.type.GraphQLInputField(type_: Union[GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList, GraphQLNonNull[Union[GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList]]], default_value: Any = Undefined, description: Optional[str] = None, deprecation_reason: Optional[str] = None, out_name: Optional[str] = None, extensions: Optional[dict[str, Any]] = None, ast_node: Optional[InputValueDefinitionNode] = None)

Bases: object

Definition of a GraphQL input field

__init__(type_: Union[GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList, GraphQLNonNull[Union[GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList]]], default_value: Any = Undefined, description: Optional[str] = None, deprecation_reason: Optional[str] = None, out_name: Optional[str] = None, extensions: Optional[dict[str, Any]] = None, ast_node: Optional[InputValueDefinitionNode] = None) None
ast_node: graphql.language.ast.InputValueDefinitionNode | None
default_value: Any
deprecation_reason: str | None
description: str | None
extensions: dict[str, Any]
out_name: str | None
to_kwargs() GraphQLInputFieldKwargs

Get corresponding arguments.

type: Union[GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList, GraphQLNonNull[Union[GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList]]]
graphql.type.GraphQLInputFieldMap

alias of Dict[str, GraphQLInputField]

graphql.type.GraphQLInputType

alias of Union[GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList, GraphQLNonNull[Union[GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList]]]

graphql.type.GraphQLLeafType

alias of Union[GraphQLScalarType, GraphQLEnumType]

class graphql.type.GraphQLNamedType(name: str, *_args: Any, **_kwargs: Any)

Bases: GraphQLType

Base class for all GraphQL named types

__init__(name: str, description: Optional[str] = None, extensions: Optional[dict[str, Any]] = None, ast_node: Optional[TypeDefinitionNode] = None, extension_ast_nodes: Optional[Collection[TypeExtensionNode]] = None) None
ast_node: graphql.language.ast.TypeDefinitionNode | None
description: str | None
extension_ast_nodes: tuple[graphql.language.ast.TypeExtensionNode, ...]
extensions: dict[str, Any]
name: str
reserved_types: Mapping[str, GraphQLNamedType] = {'Boolean': <GraphQLScalarType 'Boolean'>, 'Float': <GraphQLScalarType 'Float'>, 'ID': <GraphQLScalarType 'ID'>, 'Int': <GraphQLScalarType 'Int'>, 'String': <GraphQLScalarType 'String'>, '__Directive': <GraphQLObjectType '__Directive'>, '__DirectiveLocation': <GraphQLEnumType '__DirectiveLocation'>, '__EnumValue': <GraphQLObjectType '__EnumValue'>, '__Field': <GraphQLObjectType '__Field'>, '__InputValue': <GraphQLObjectType '__InputValue'>, '__Schema': <GraphQLObjectType '__Schema'>, '__Type': <GraphQLObjectType '__Type'>, '__TypeKind': <GraphQLEnumType '__TypeKind'>}
to_kwargs() GraphQLNamedTypeKwargs

Get corresponding arguments.

graphql.type.GraphQLNullableType

alias of Union[GraphQLScalarType, GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList]

graphql.type.GraphQLOutputType

alias of Union[GraphQLScalarType, GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType, GraphQLEnumType, GraphQLList, GraphQLNonNull[Union[GraphQLScalarType, GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType, GraphQLEnumType, GraphQLList]]]

class graphql.type.GraphQLType

Bases: object

Base class for all GraphQL types

__init__()
class graphql.type.GraphQLWrappingType(type_: GT)

Bases: GraphQLType, Generic[GT]

Base class for all GraphQL wrapping types

__init__(type_: GT) None
of_type: GT
graphql.type.Thunk

alias of Union[Callable[[], T], T]

graphql.type.ThunkCollection

alias of Union[Callable[[], Collection[T]], Collection[T]]

graphql.type.ThunkMapping

alias of Union[Callable[[], Mapping[str, T]], Mapping[str, T]]

Resolvers

graphql.type.GraphQLFieldResolver

alias of Callable[[…], Any]

graphql.type.GraphQLIsTypeOfFn

alias of Callable[[Any, GraphQLResolveInfo], Union[Awaitable[bool], bool]]

class graphql.type.GraphQLResolveInfo(field_name: str, field_nodes: list[FieldNode], return_type: GraphQLOutputType, parent_type: GraphQLObjectType, path: Path, schema: GraphQLSchema, fragments: dict[str, FragmentDefinitionNode], root_value: Any, operation: OperationDefinitionNode, variable_values: dict[str, Any], context: Any, is_awaitable: Callable[[Any], bool])

Bases: NamedTuple

Collection of information passed to the resolvers.

This is always passed as the first argument to the resolvers.

Note that contrary to the JavaScript implementation, the context (commonly used to represent an authenticated user, or request-specific caches) is included here and not passed as an additional argument.

__init__()
context: Any

Alias for field number 10

count(value, /)

Return number of occurrences of value.

field_name: str

Alias for field number 0

field_nodes: list[FieldNode]

Alias for field number 1

fragments: dict[str, FragmentDefinitionNode]

Alias for field number 6

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

is_awaitable: Callable[[Any], bool]

Alias for field number 11

operation: OperationDefinitionNode

Alias for field number 8

parent_type: GraphQLObjectType

Alias for field number 3

path: Path

Alias for field number 4

return_type: GraphQLOutputType

Alias for field number 2

root_value: Any

Alias for field number 7

schema: GraphQLSchema

Alias for field number 5

variable_values: dict[str, Any]

Alias for field number 9

graphql.type.GraphQLTypeResolver

alias of Callable[[Any, GraphQLResolveInfo, GraphQLAbstractType], Optional[Union[Awaitable[Optional[str]], str]]]

Directives

Predicates

graphql.type.is_directive(directive: Any) TypeGuard[GraphQLDirective]

Check whether this is a GraphQL directive.

graphql.type.is_specified_directive(directive: GraphQLDirective) bool

Check whether the given directive is one of the specified directives.

Definitions

class graphql.type.GraphQLDirective(name: str, locations: Collection[DirectiveLocation], args: Optional[dict[str, graphql.type.definition.GraphQLArgument]] = None, is_repeatable: bool = False, description: Optional[str] = None, extensions: Optional[dict[str, Any]] = None, ast_node: Optional[DirectiveDefinitionNode] = None)

Bases: object

GraphQL Directive

Directives are used by the GraphQL runtime as a way of modifying execution behavior. Type system creators will usually not create these directly.

__init__(name: str, locations: Collection[DirectiveLocation], args: Optional[dict[str, graphql.type.definition.GraphQLArgument]] = None, is_repeatable: bool = False, description: Optional[str] = None, extensions: Optional[dict[str, Any]] = None, ast_node: Optional[DirectiveDefinitionNode] = None) None
args: dict[str, graphql.type.definition.GraphQLArgument]
ast_node: graphql.language.ast.DirectiveDefinitionNode | None
description: str | None
extensions: dict[str, Any]
is_repeatable: bool
locations: tuple[graphql.language.directive_locations.DirectiveLocation, ...]
name: str
to_kwargs() GraphQLDirectiveKwargs

Get corresponding arguments.

graphql.type.GraphQLIncludeDirective

alias of <GraphQLDirective(@include)>

graphql.type.GraphQLSkipDirective

alias of <GraphQLDirective(@skip)>

graphql.type.GraphQLDeferDirective

alias of <GraphQLDirective(@defer)>

graphql.type.GraphQLStreamDirective

alias of <GraphQLDirective(@stream)>

graphql.type.GraphQLDeprecatedDirective

alias of <GraphQLDirective(@deprecated)>

graphql.type.GraphQLSpecifiedByDirective

alias of <GraphQLDirective(@specifiedBy)>

graphql.type.specified_directives

A tuple with all directives from the GraphQL specification

graphql.type.DEFAULT_DEPRECATION_REASON = 'No longer supported'

String constant that can be used as the default value for deprecation_reason.

Introspection

Predicates

graphql.type.is_introspection_type(type_: GraphQLNamedType) bool

Check whether the given named GraphQL type is an introspection type.

Definitions

class graphql.type.TypeKind(value)

Bases: Enum

Kinds of types

ENUM = 'enum'
INPUT_OBJECT = 'input object'
INTERFACE = 'interface'
LIST = 'list'
NON_NULL = 'non-null'
OBJECT = 'object'
SCALAR = 'scalar'
UNION = 'union'
graphql.type.TypeMetaFieldDef

alias of <GraphQLField <GraphQLObjectType ‘__Type’>>

graphql.type.TypeNameMetaFieldDef

alias of <GraphQLField <GraphQLNonNull <GraphQLScalarType ‘String’>>>

graphql.type.SchemaMetaFieldDef

alias of <GraphQLField <GraphQLNonNull <GraphQLObjectType ‘__Schema’>>>

graphql.type.introspection_types

This is a mapping containing all introspection types with their names as keys

Scalars

Predicates

graphql.type.is_specified_scalar_type(type_: GraphQLNamedType) TypeGuard[GraphQLScalarType]

Check whether the given named GraphQL type is a specified scalar type.

Definitions

graphql.type.GraphQLBoolean

alias of <GraphQLScalarType ‘Boolean’>

graphql.type.GraphQLFloat

alias of <GraphQLScalarType ‘Float’>

graphql.type.GraphQLID

alias of <GraphQLScalarType ‘ID’>

graphql.type.GraphQLInt

alias of <GraphQLScalarType ‘Int’>

graphql.type.GraphQLString

alias of <GraphQLScalarType ‘String’>

graphql.type.GRAPHQL_MAX_INT

Maximum possible Int value as per GraphQL Spec (32-bit signed integer)

graphql.type.GRAPHQL_MIN_INT

Minimum possible Int value as per GraphQL Spec (32-bit signed integer)

Schema

Predicates

graphql.type.is_schema(schema: Any) TypeGuard[GraphQLSchema]

Check whether this is a GraphQL schema.

Definitions

class graphql.type.GraphQLSchema(query: GraphQLObjectType | None = None, mutation: GraphQLObjectType | None = None, subscription: GraphQLObjectType | None = None, types: Collection[GraphQLNamedType] | None = None, directives: Collection[GraphQLDirective] | None = None, description: str | None = None, extensions: dict[str, Any] | None = None, ast_node: ast.SchemaDefinitionNode | None = None, extension_ast_nodes: Collection[ast.SchemaExtensionNode] | None = None, assume_valid: bool = False)

Bases: object

Schema Definition

A Schema is created by supplying the root types of each type of operation, query and mutation (optional). A schema definition is then supplied to the validator and executor.

Schemas should be considered immutable once they are created. If you want to modify a schema, modify the result of the to_kwargs() method and recreate the schema.

Example:

MyAppSchema = GraphQLSchema(
  query=MyAppQueryRootType,
  mutation=MyAppMutationRootType)

Note: When the schema is constructed, by default only the types that are reachable by traversing the root types are included, other types must be explicitly referenced.

Example:

character_interface = GraphQLInterfaceType('Character', ...)

human_type = GraphQLObjectType(
    'Human', interfaces=[character_interface], ...)

droid_type = GraphQLObjectType(
    'Droid', interfaces: [character_interface], ...)

schema = GraphQLSchema(
    query=GraphQLObjectType('Query',
        fields={'hero': GraphQLField(character_interface, ....)}),
    ...
    # Since this schema references only the `Character` interface it's
    # necessary to explicitly list the types that implement it if
    # you want them to be included in the final schema.
    types=[human_type, droid_type])

Note: If a list of directives is provided to GraphQLSchema, that will be the exact list of directives represented and allowed. If directives is not provided, then a default set of the specified directives (e.g. @include and @skip) will be used. If you wish to provide additional directives to these specified directives, you must explicitly declare them. Example:

MyAppSchema = GraphQLSchema(
  ...
  directives=specified_directives + [my_custom_directive])
__init__(query: GraphQLObjectType | None = None, mutation: GraphQLObjectType | None = None, subscription: GraphQLObjectType | None = None, types: Collection[GraphQLNamedType] | None = None, directives: Collection[GraphQLDirective] | None = None, description: str | None = None, extensions: dict[str, Any] | None = None, ast_node: ast.SchemaDefinitionNode | None = None, extension_ast_nodes: Collection[ast.SchemaExtensionNode] | None = None, assume_valid: bool = False) None

Initialize GraphQL schema.

If this schema was built from a source known to be valid, then it may be marked with assume_valid to avoid an additional type system validation.

ast_node: ast.SchemaDefinitionNode | None
description: str | None
directives: tuple[GraphQLDirective, ...]
extension_ast_nodes: tuple[ast.SchemaExtensionNode, ...]
extensions: dict[str, Any]
get_directive(name: str) graphql.type.directives.GraphQLDirective | None

Get the directive with the given name.

get_field(parent_type: Union[GraphQLObjectType, GraphQLInterfaceType, GraphQLUnionType], field_name: str) graphql.type.definition.GraphQLField | None

Get field of a given type with the given name.

This method looks up the field on the given type definition. It has special casing for the three introspection fields, __schema, __type and __typename.

__typename is special because it can always be queried as a field, even in situations where no other fields are allowed, like on a Union.

__schema and __type could get automatically added to the query type, but that would require mutating type definitions, which would cause issues.

get_implementations(interface_type: GraphQLInterfaceType) InterfaceImplementations

Get implementations for the given interface type.

get_possible_types(abstract_type: Union[GraphQLInterfaceType, GraphQLUnionType]) list[graphql.type.definition.GraphQLObjectType]

Get list of all possible concrete types for given abstract type.

get_root_type(operation: OperationType) GraphQLObjectType | None

Get the root type.

get_type(name: str) graphql.type.definition.GraphQLNamedType | None

Get the type with the given name.

is_sub_type(abstract_type: Union[GraphQLInterfaceType, GraphQLUnionType], maybe_sub_type: GraphQLNamedType) bool

Check whether a type is a subtype of a given abstract type.

mutation_type: GraphQLObjectType | None
query_type: GraphQLObjectType | None
subscription_type: GraphQLObjectType | None
to_kwargs() GraphQLSchemaKwargs

Get corresponding arguments.

type_map: TypeMap
property validation_errors: list[GraphQLError] | None

Get validation errors.

Validate

Functions

graphql.type.validate_schema(schema: GraphQLSchema) list[graphql.error.graphql_error.GraphQLError]

Validate a GraphQL schema.

Implements the “Type Validation” sub-sections of the specification’s “Type System” section.

Validation runs synchronously, returning a list of encountered errors, or an empty list if no errors were encountered and the Schema is valid.

Assertions

graphql.type.assert_valid_schema(schema: GraphQLSchema) None

Utility function which asserts a schema is valid.

Throws a TypeError if the schema is invalid.

Other

Thunk Handling

graphql.type.resolve_thunk(thunk: Union[Callable[[], T], T]) T

Resolve the given thunk.

Used while defining GraphQL types to allow for circular references in otherwise immutable type definitions.

Assertions

graphql.type.assert_name(name: str) str

Uphold the spec rules about naming.

graphql.type.assert_enum_value_name(name: str) str

Uphold the spec rules about naming enum values.