Language

GraphQL Language

The graphql.language package is responsible for parsing and operating on the GraphQL language.

AST

class graphql.language.Location(start_token: Token, end_token: Token, source: Source)

Bases: object

AST Location

Contains a range of UTF-8 character offsets and token references that identify the region of the source from which the AST derived.

Parameters:

start_token – The start token.
end_token – The end token.
source – Source document used to derive error locations.

>>> from graphql.language import Location, Source, Token, TokenKind
>>> source = Source('{ hello }')
>>> start_token = Token(TokenKind.BRACE_L, 0, 1, 1, 1)
>>> end_token = Token(TokenKind.BRACE_R, 8, 9, 1, 9)
>>> location = Location(start_token, end_token, source)
>>> location.start
0
>>> location.end
9
>>> location.source.body
'{ hello }'

The location of a parsed document:

>>> from graphql import parse
>>> parse('{ hello }').loc
<Location 0:9>

end: int: The character offset at which this Node ends.

end_token: Token: The Token at which this Node ends.

source: Source: The Source document the AST represents.

start: int: The character offset at which this Node begins.

start_token: Token: The Token at which this Node begins.

class graphql.language.Node(*, loc: Location | None = None)

Bases: object

Base class for all AST nodes.

Parameters:: loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import NameNode
>>> node = NameNode(value='hello')
>>> node.kind
'name'
>>> node.keys
('loc', 'value')

keys: ClassVar[tuple[str, ...]] = ('loc',): The names of the attributes of this node.

kind: ClassVar[str] = 'ast': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

Each kind of AST node has its own class:

class graphql.language.ArgumentNode(*, loc: Location | None = None, name: NameNode, value: ValueNode)

Bases: Node

An argument supplied to a field or directive.

Parameters:

name – Name node identifying this AST node.
value – Parsed value represented by this node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import ArgumentNode, NameNode, VariableNode, print_ast
>>> value = VariableNode(name=NameNode(value='id'))
>>> print_ast(ArgumentNode(name=NameNode(value='id'), value=value))
'id: $id'

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'value'): The names of the attributes of this node.

kind: ClassVar[str] = 'argument': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

value: ValueNode: Parsed value represented by this node.

class graphql.language.BooleanValueNode(*, loc: Location | None = None, value: bool)

Bases: ValueNode

A boolean value literal.

Parameters:

value – Parsed value represented by this node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import BooleanValueNode, print_ast
>>> print_ast(BooleanValueNode(value=True))
'true'

keys: ClassVar[tuple[str, ...]] = ('loc', 'value'): The names of the attributes of this node.

kind: ClassVar[str] = 'boolean_value': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

value: bool: Parsed value represented by this node.

Bases: ArgumentNode

An argument node whose value is guaranteed to be constant.

Parameters:

name – Name node identifying this AST node.
value – Parsed value represented by this node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     ConstArgumentNode, IntValueNode, NameNode, print_ast,
... )
>>> value = IntValueNode(value='4')
>>> print_ast(ConstArgumentNode(name=NameNode(value='id'), value=value))
'id: 4'

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'value'): The names of the attributes of this node.

kind: ClassVar[str] = 'argument': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

value: IntValueNode | FloatValueNode | StringValueNode | BooleanValueNode | NullValueNode | EnumValueNode | ConstListValueNode | ConstObjectValueNode: Parsed value represented by this node.

class graphql.language.ConstDirectiveNode(*, loc: Location | None = None, name: NameNode, arguments: tuple[ConstArgumentNode, ...] | None = None)

Bases: DirectiveNode

A directive whose arguments are all constant values.

Parameters:

name – Name node identifying this AST node.
arguments – Arguments supplied to this field, directive, or coordinate.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     ConstArgumentNode, ConstDirectiveNode, NameNode, StringValueNode, print_ast
... )
>>> value = StringValueNode(value='Use other')
>>> argument = ConstArgumentNode(name=NameNode(value='reason'), value=value)
>>> name = NameNode(value='deprecated')
>>> print_ast(ConstDirectiveNode(name=name, arguments=(argument,)))
'@deprecated(reason: "Use other")'

arguments: tuple[ConstArgumentNode, ...] | None = None: Arguments supplied to this field, directive, or coordinate.

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'arguments'): The names of the attributes of this node.

kind: ClassVar[str] = 'directive': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

Bases: ListValueNode

A list value literal whose elements are all constant values.

Parameters:

values – Values contained in this enum, list, or input-object definition.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import ConstListValueNode, IntValueNode, print_ast
>>> print_ast(ConstListValueNode(values=(IntValueNode(value='1'),)))
'[1]'

keys: ClassVar[tuple[str, ...]] = ('loc', 'values'): The names of the attributes of this node.

kind: ClassVar[str] = 'list_value': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

values: tuple[IntValueNode | FloatValueNode | StringValueNode | BooleanValueNode | NullValueNode | EnumValueNode | ConstListValueNode | ConstObjectValueNode, ...] = (): Values contained in this enum, list, or input-object definition.

Bases: ObjectFieldNode

A field inside a constant input object value literal.

Parameters:

name – Name node identifying this AST node.
value – Parsed value represented by this node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     ConstObjectFieldNode, IntValueNode, NameNode, print_ast,
... )
>>> value = IntValueNode(value='1')
>>> print_ast(ConstObjectFieldNode(name=NameNode(value='a'), value=value))
'a: 1'

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'value'): The names of the attributes of this node.

kind: ClassVar[str] = 'object_field': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

value: IntValueNode | FloatValueNode | StringValueNode | BooleanValueNode | NullValueNode | EnumValueNode | ConstListValueNode | ConstObjectValueNode: Parsed value represented by this node.

class graphql.language.ConstObjectValueNode(*, loc: Location | None = None, fields: tuple[ConstObjectFieldNode, ...] = ())

Bases: ObjectValueNode

An input object value literal whose fields are all constant values.

Parameters:

fields – Fields declared by this object, interface, input object, or literal.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     ConstObjectFieldNode, ConstObjectValueNode, IntValueNode, NameNode,
...     print_ast,
... )
>>> value = IntValueNode(value='1')
>>> field = ConstObjectFieldNode(name=NameNode(value='a'), value=value)
>>> print_ast(ConstObjectValueNode(fields=(field,)))
'{ a: 1 }'

fields: tuple[ConstObjectFieldNode, ...] = (): Fields declared by this object, interface, input object, or literal.

keys: ClassVar[tuple[str, ...]] = ('loc', 'fields'): The names of the attributes of this node.

kind: ClassVar[str] = 'object_value': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

graphql.language.ConstValueNode: alias of IntValueNode | FloatValueNode | StringValueNode | BooleanValueNode | NullValueNode | EnumValueNode | ConstListValueNode | ConstObjectValueNode

class graphql.language.DefinitionNode(*, loc: Location | None = None)

Bases: Node

Base class for all definition nodes.

Parameters:: loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import DefinitionNode, parse
>>> document = parse('{ hello } type Query { hello: String }')
>>> [isinstance(node, DefinitionNode) for node in document.definitions]
[True, True]

keys: ClassVar[tuple[str, ...]] = ('loc',): The names of the attributes of this node.

kind: ClassVar[str] = 'definition': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.DirectiveDefinitionNode(*, loc: Location | None = None, name: NameNode, locations: tuple[NameNode, ...], description: StringValueNode | None = None, arguments: tuple[InputValueDefinitionNode, ...] | None = None, directives: tuple[ConstDirectiveNode, ...] | None = None, repeatable: bool = False)

Bases: TypeSystemDefinitionNode

A directive definition in a type-system document.

Parameters:

description – The optional GraphQL description associated with this definition.
name – Name node identifying this AST node.
arguments – Arguments supplied to this field, directive, or coordinate.
directives – Directives available in this schema or applied to this AST node.
locations – Locations where this directive may be applied.
repeatable – Whether this directive may appear more than once at the same location.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import DirectiveDefinitionNode, NameNode, print_ast
>>> node = DirectiveDefinitionNode(
...     name=NameNode(value='tag'),
...     locations=(NameNode(value='FIELD'), NameNode(value='OBJECT')),
...     repeatable=True,
... )
>>> print_ast(node)
'directive @tag repeatable on FIELD | OBJECT'

arguments: tuple[InputValueDefinitionNode, ...] | None = None: Arguments supplied to this field, directive, or coordinate.

description: StringValueNode | None = None: The optional GraphQL description associated with this definition.

directives: tuple[ConstDirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'locations', 'description', 'arguments', 'directives', 'repeatable'): The names of the attributes of this node.

kind: ClassVar[str] = 'directive_definition': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

locations: tuple[NameNode, ...]: Locations where this directive may be applied.

name: NameNode: Name node identifying this AST node.

repeatable: bool = False: Whether this directive may appear more than once at the same location.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.DirectiveExtensionNode(*, loc: Location | None = None, name: NameNode, directives: tuple[ConstDirectiveNode, ...] | None = None)

Bases: Node

A directive extension.

Parameters:

name – Name node identifying this AST node.
directives – Directives available in this schema or applied to this AST node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     ConstDirectiveNode, DirectiveExtensionNode, NameNode, print_ast,
... )
>>> directive = ConstDirectiveNode(name=NameNode(value='deprecated'))
>>> node = DirectiveExtensionNode(
...     name=NameNode(value='tag'), directives=(directive,)
... )
>>> print_ast(node)
'extend directive @tag @deprecated'

directives: tuple[ConstDirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'directives'): The names of the attributes of this node.

kind: ClassVar[str] = 'directive_extension': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.DirectiveNode(*, loc: Location | None = None, name: NameNode, arguments: tuple[ArgumentNode, ...] | None = None)

Bases: Node

A directive applied to an executable or type-system location.

Parameters:

name – Name node identifying this AST node.
arguments – Arguments supplied to this field, directive, or coordinate.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     ArgumentNode, DirectiveNode, NameNode, VariableNode, print_ast,
... )
>>> value = VariableNode(name=NameNode(value='skip'))
>>> argument = ArgumentNode(name=NameNode(value='if'), value=value)
>>> print_ast(DirectiveNode(name=NameNode(value='skip'), arguments=(argument,)))
'@skip(if: $skip)'

arguments: tuple[ArgumentNode, ...] | None = None: Arguments supplied to this field, directive, or coordinate.

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'arguments'): The names of the attributes of this node.

kind: ClassVar[str] = 'directive': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.DocumentNode(*, loc: Location | None = None, definitions: tuple[DefinitionNode, ...] = ())

Bases: Node

The root AST node for a parsed GraphQL document.

Parameters:

definitions – Top-level executable and type-system definitions in this document.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import DocumentNode, parse, print_ast
>>> document = parse('{ hello }')
>>> document.token_count
3
>>> print(print_ast(DocumentNode(definitions=document.definitions)))
{
  hello
}

definitions: tuple[DefinitionNode, ...] = (): Top-level executable and type-system definitions in this document.

keys: ClassVar[tuple[str, ...]] = ('loc', 'definitions'): The names of the attributes of this node.

kind: ClassVar[str] = 'document': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

token_count: ClassVar[int] = 0: The number of lexical tokens parsed for this document.

class graphql.language.EnumTypeDefinitionNode(*, loc: Location | None = None, name: NameNode, description: StringValueNode | None = None, directives: tuple[ConstDirectiveNode, ...] | None = None, values: tuple[EnumValueDefinitionNode, ...] | None = None)

Bases: TypeDefinitionNode

An enum type definition in a type-system document.

Parameters:

description – The optional GraphQL description associated with this definition.
name – Name node identifying this AST node.
directives – Directives available in this schema or applied to this AST node.
values – Values contained in this enum, list, or input-object definition.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     EnumTypeDefinitionNode, EnumValueDefinitionNode, NameNode, print_ast
... )
>>> values = tuple(
...     EnumValueDefinitionNode(name=NameNode(value=name))
...     for name in ('RED', 'BLUE')
... )
>>> node = EnumTypeDefinitionNode(name=NameNode(value='Color'), values=values)
>>> print(print_ast(node))
enum Color {
  RED
  BLUE
}

description: StringValueNode | None = None: The optional GraphQL description associated with this definition.

directives: tuple[ConstDirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'description', 'directives', 'values'): The names of the attributes of this node.

kind: ClassVar[str] = 'enum_type_definition': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

values: tuple[EnumValueDefinitionNode, ...] | None = None: Values contained in this enum, list, or input-object definition.

class graphql.language.EnumTypeExtensionNode(*, loc: Location | None = None, name: NameNode, directives: tuple[ConstDirectiveNode, ...] | None = None, values: tuple[EnumValueDefinitionNode, ...] | None = None)

Bases: TypeExtensionNode

An enum type extension.

Parameters:

name – Name node identifying this AST node.
directives – Directives available in this schema or applied to this AST node.
values – Values contained in this enum, list, or input-object definition.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     EnumTypeExtensionNode, EnumValueDefinitionNode, NameNode, print_ast
... )
>>> values = (EnumValueDefinitionNode(name=NameNode(value='GREEN')),)
>>> node = EnumTypeExtensionNode(name=NameNode(value='Color'), values=values)
>>> print(print_ast(node))
extend enum Color {
  GREEN
}

directives: tuple[ConstDirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'directives', 'values'): The names of the attributes of this node.

kind: ClassVar[str] = 'enum_type_extension': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

values: tuple[EnumValueDefinitionNode, ...] | None = None: Values contained in this enum, list, or input-object definition.

class graphql.language.EnumValueDefinitionNode(*, loc: Location | None = None, name: NameNode, description: StringValueNode | None = None, directives: tuple[ConstDirectiveNode, ...] | None = None)

Bases: DefinitionNode

An enum value definition.

Parameters:

description – The optional GraphQL description associated with this definition.
name – Name node identifying this AST node.
directives – Directives available in this schema or applied to this AST node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     ConstDirectiveNode, EnumValueDefinitionNode, NameNode, print_ast
... )
>>> directive = ConstDirectiveNode(name=NameNode(value='deprecated'))
>>> node = EnumValueDefinitionNode(
...     name=NameNode(value='RED'), directives=(directive,)
... )
>>> print_ast(node)
'RED @deprecated'

description: StringValueNode | None = None: The optional GraphQL description associated with this definition.

directives: tuple[ConstDirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'description', 'directives'): The names of the attributes of this node.

kind: ClassVar[str] = 'enum_value_definition': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.EnumValueNode(*, loc: Location | None = None, value: str)

Bases: ValueNode

An enum value literal.

Parameters:

value – Parsed value represented by this node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import EnumValueNode, print_ast
>>> print_ast(EnumValueNode(value='RED'))
'RED'

keys: ClassVar[tuple[str, ...]] = ('loc', 'value'): The names of the attributes of this node.

kind: ClassVar[str] = 'enum_value': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

value: str: Parsed value represented by this node.

class graphql.language.ExecutableDefinitionNode(*, loc: Location | None = None, selection_set: SelectionSetNode, description: StringValueNode | None = None, name: NameNode | None = None, variable_definitions: tuple[VariableDefinitionNode, ...] | None = None, directives: tuple[DirectiveNode, ...] | None = None)

Bases: DefinitionNode

Base class for executable definition nodes.

Parameters:

selection_set – Selections made by this operation, field, or fragment.
description – The optional GraphQL description associated with this definition.
name – Name node identifying this AST node.
variable_definitions – Variable definitions declared by this operation or fragment.
directives – Directives available in this schema or applied to this AST node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import ExecutableDefinitionNode, parse
>>> document = parse('{ hello } type Query { hello: String }')
>>> [isinstance(node, ExecutableDefinitionNode) for node in document.definitions]
[True, False]

description: StringValueNode | None = None: The optional GraphQL description associated with this definition.

directives: tuple[DirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

keys: ClassVar[tuple[str, ...]] = ('loc', 'selection_set', 'description', 'name', 'variable_definitions', 'directives'): The names of the attributes of this node.

kind: ClassVar[str] = 'executable_definition': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode | None = None: Name node identifying this AST node.

selection_set: SelectionSetNode: Selections made by this operation, field, or fragment.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

variable_definitions: tuple[VariableDefinitionNode, ...] | None = None

Variable definitions declared by this operation or fragment.

Note: variable definitions on fragment definitions are experimental and may be changed or removed in the future.

class graphql.language.FieldDefinitionNode(*, loc: Location | None = None, name: NameNode, type: TypeNode, description: StringValueNode | None = None, arguments: tuple[InputValueDefinitionNode, ...] | None = None, directives: tuple[ConstDirectiveNode, ...] | None = None)

Bases: DefinitionNode

A field definition declared by an object or interface type.

Parameters:

description – The optional GraphQL description associated with this definition.
name – Name node identifying this AST node.
arguments – Arguments supplied to this field, directive, or coordinate.
type – The GraphQL type reference or runtime type for this element.
directives – Directives available in this schema or applied to this AST node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     FieldDefinitionNode, InputValueDefinitionNode, NamedTypeNode, NameNode,
...     print_ast,
... )
>>> argument = InputValueDefinitionNode(
...     name=NameNode(value='id'), type=NamedTypeNode(name=NameNode(value='ID'))
... )
>>> node = FieldDefinitionNode(
...     name=NameNode(value='user'),
...     arguments=(argument,),
...     type=NamedTypeNode(name=NameNode(value='User')),
... )
>>> print_ast(node)
'user(id: ID): User'

arguments: tuple[InputValueDefinitionNode, ...] | None = None: Arguments supplied to this field, directive, or coordinate.

description: StringValueNode | None = None: The optional GraphQL description associated with this definition.

directives: tuple[ConstDirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'type', 'description', 'arguments', 'directives'): The names of the attributes of this node.

kind: ClassVar[str] = 'field_definition': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

type: TypeNode: The GraphQL type reference or runtime type for this element.

class graphql.language.FieldNode(*, loc: Location | None = None, directives: tuple[DirectiveNode, ...] | None = None, name: NameNode, alias: NameNode | None = None, arguments: tuple[ArgumentNode, ...] | None = None, selection_set: SelectionSetNode | None = None)

Bases: SelectionNode

A field selected in an executable GraphQL document.

Parameters:

alias – The response-key alias for this field, if one was supplied.
name – Name node identifying this AST node.
arguments – Arguments supplied to this field, directive, or coordinate.
directives – Directives available in this schema or applied to this AST node.
selection_set – Selections made by this operation, field, or fragment.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import FieldNode, NameNode, print_ast
>>> node = FieldNode(name=NameNode(value='hello'), alias=NameNode(value='greeting'))
>>> print_ast(node)
'greeting: hello'

alias: NameNode | None = None: The response-key alias for this field, if one was supplied.

arguments: tuple[ArgumentNode, ...] | None = None: Arguments supplied to this field, directive, or coordinate.

directives: tuple[DirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

keys: ClassVar[tuple[str, ...]] = ('loc', 'directives', 'name', 'alias', 'arguments', 'selection_set'): The names of the attributes of this node.

kind: ClassVar[str] = 'field': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

selection_set: SelectionSetNode | None = None: Selections made by this operation, field, or fragment.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.FloatValueNode(*, loc: Location | None = None, value: str)

Bases: ValueNode

A floating-point value literal.

Parameters:

value – Parsed value represented by this node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import FloatValueNode, print_ast
>>> print_ast(FloatValueNode(value='3.14'))
'3.14'

keys: ClassVar[tuple[str, ...]] = ('loc', 'value'): The names of the attributes of this node.

kind: ClassVar[str] = 'float_value': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

value: str: Parsed value represented by this node.

class graphql.language.FragmentArgumentNode(*, loc: Location | None = None, name: NameNode, value: ValueNode)

Bases: Node

An argument supplied to a fragment spread (experimental).

Parameters:

name – Name of the fragment variable this argument is supplied for.
value – Parsed value represented by this node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     BooleanValueNode, FragmentArgumentNode, NameNode, print_ast,
... )
>>> value = BooleanValueNode(value=True)
>>> print_ast(FragmentArgumentNode(name=NameNode(value='var'), value=value))
'var: true'

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'value'): The names of the attributes of this node.

kind: ClassVar[str] = 'fragment_argument': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name of the fragment variable this argument is supplied for.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

value: ValueNode: Parsed value represented by this node.

class graphql.language.FragmentDefinitionNode(*, loc: Location | None = None, selection_set: SelectionSetNode, description: StringValueNode | None = None, name: NameNode = None, variable_definitions: tuple[VariableDefinitionNode, ...] | None = None, directives: tuple[DirectiveNode, ...] | None = None, type_condition: NamedTypeNode)

Bases: ExecutableDefinitionNode

A reusable fragment definition declared in an executable document.

Parameters:

description – The optional GraphQL description associated with this definition.
name – Name node identifying this AST node.
variable_definitions – Variable definitions declared by this operation or fragment.
type_condition – The type condition that limits where this fragment applies.
directives – Directives available in this schema or applied to this AST node.
selection_set – Selections made by this operation, field, or fragment.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     FieldNode, FragmentDefinitionNode, NamedTypeNode, NameNode,
...     SelectionSetNode, print_ast,
... )
>>> field = FieldNode(name=NameNode(value='name'))
>>> node = FragmentDefinitionNode(
...     name=NameNode(value='userFields'),
...     type_condition=NamedTypeNode(name=NameNode(value='User')),
...     selection_set=SelectionSetNode(selections=(field,)),
... )
>>> print(print_ast(node))
fragment userFields on User {
  name
}

description: StringValueNode | None = None: The optional GraphQL description associated with this definition.

directives: tuple[DirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

keys: ClassVar[tuple[str, ...]] = ('loc', 'selection_set', 'description', 'name', 'variable_definitions', 'directives', 'type_condition'): The names of the attributes of this node.

kind: ClassVar[str] = 'fragment_definition': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode = None: Name node identifying this AST node.

selection_set: SelectionSetNode: Selections made by this operation, field, or fragment.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

type_condition: NamedTypeNode: The type condition that limits where this fragment applies.

variable_definitions: tuple[VariableDefinitionNode, ...] | None = None

Variable definitions declared by this operation or fragment.

Note: variable definitions on fragment definitions are experimental and may be changed or removed in the future.

class graphql.language.FragmentSpreadNode(*, loc: Location | None = None, directives: tuple[DirectiveNode, ...] | None = None, name: NameNode, arguments: tuple[FragmentArgumentNode, ...] | None = None)

Bases: SelectionNode

A named fragment spread, such as ...userFields.

Parameters:

name – Name node identifying this AST node.
arguments – Argument values supplied to the referenced fragment.
directives – Directives available in this schema or applied to this AST node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import FragmentSpreadNode, NameNode, print_ast
>>> print_ast(FragmentSpreadNode(name=NameNode(value='userFields')))
'...userFields'

arguments: tuple[FragmentArgumentNode, ...] | None = None: Argument values supplied to the referenced fragment.

directives: tuple[DirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

keys: ClassVar[tuple[str, ...]] = ('loc', 'directives', 'name', 'arguments'): The names of the attributes of this node.

kind: ClassVar[str] = 'fragment_spread': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.InlineFragmentNode(*, loc: Location | None = None, directives: tuple[DirectiveNode, ...] | None = None, selection_set: SelectionSetNode, type_condition: NamedTypeNode | None = None)

Bases: SelectionNode

An inline fragment spread with an optional type condition.

Parameters:

type_condition – The type condition that limits where this fragment applies.
directives – Directives available in this schema or applied to this AST node.
selection_set – Selections made by this operation, field, or fragment.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     FieldNode, InlineFragmentNode, NamedTypeNode, NameNode, SelectionSetNode,
...     print_ast,
... )
>>> field = FieldNode(name=NameNode(value='a'))
>>> selection_set = SelectionSetNode(selections=(field,))
>>> type_condition = NamedTypeNode(name=NameNode(value='User'))
>>> node = InlineFragmentNode(
...     type_condition=type_condition, selection_set=selection_set
... )
>>> print_ast(node).splitlines()
['... on User {', '  a', '}']

directives: tuple[DirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

keys: ClassVar[tuple[str, ...]] = ('loc', 'directives', 'selection_set', 'type_condition'): The names of the attributes of this node.

kind: ClassVar[str] = 'inline_fragment': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

selection_set: SelectionSetNode: Selections made by this operation, field, or fragment.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

type_condition: NamedTypeNode | None = None: The type condition that limits where this fragment applies.

class graphql.language.InputObjectTypeDefinitionNode(*, loc: Location | None = None, name: NameNode, description: StringValueNode | None = None, directives: tuple[ConstDirectiveNode, ...] | None = None, fields: tuple[InputValueDefinitionNode, ...] | None = None)

Bases: TypeDefinitionNode

An input object type definition in a type-system document.

Parameters:

description – The optional GraphQL description associated with this definition.
name – Name node identifying this AST node.
directives – Directives available in this schema or applied to this AST node.
fields – Fields declared by this object, interface, input object, or literal.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     InputObjectTypeDefinitionNode, InputValueDefinitionNode, NamedTypeNode,
...     NameNode, print_ast,
... )
>>> field = InputValueDefinitionNode(
...     name=NameNode(value='name'),
...     type=NamedTypeNode(name=NameNode(value='String')),
... )
>>> node = InputObjectTypeDefinitionNode(
...     name=NameNode(value='UserInput'), fields=(field,)
... )
>>> print(print_ast(node))
input UserInput {
  name: String
}

description: StringValueNode | None = None: The optional GraphQL description associated with this definition.

directives: tuple[ConstDirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

fields: tuple[InputValueDefinitionNode, ...] | None = None: Fields declared by this object, interface, input object, or literal.

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'description', 'directives', 'fields'): The names of the attributes of this node.

kind: ClassVar[str] = 'input_object_type_definition': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.InputObjectTypeExtensionNode(*, loc: Location | None = None, name: NameNode, directives: tuple[ConstDirectiveNode, ...] | None = None, fields: tuple[InputValueDefinitionNode, ...] | None = None)

Bases: TypeExtensionNode

An input object type extension.

Parameters:

name – Name node identifying this AST node.
directives – Directives available in this schema or applied to this AST node.
fields – Fields declared by this object, interface, input object, or literal.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     InputObjectTypeExtensionNode, InputValueDefinitionNode, NamedTypeNode,
...     NameNode, print_ast,
... )
>>> field = InputValueDefinitionNode(
...     name=NameNode(value='age'), type=NamedTypeNode(name=NameNode(value='Int'))
... )
>>> node = InputObjectTypeExtensionNode(
...     name=NameNode(value='UserInput'), fields=(field,)
... )
>>> print(print_ast(node))
extend input UserInput {
  age: Int
}

directives: tuple[ConstDirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

fields: tuple[InputValueDefinitionNode, ...] | None = None: Fields declared by this object, interface, input object, or literal.

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'directives', 'fields'): The names of the attributes of this node.

kind: ClassVar[str] = 'input_object_type_extension': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

Bases: DefinitionNode

An argument or input-field definition.

Parameters:

description – The optional GraphQL description associated with this definition.
name – Name node identifying this AST node.
type – The GraphQL type reference or runtime type for this element.
default_value – Default value used when no explicit value is supplied.
directives – Directives available in this schema or applied to this AST node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     InputValueDefinitionNode, IntValueNode, NamedTypeNode, NameNode, print_ast
... )
>>> node = InputValueDefinitionNode(
...     name=NameNode(value='first'),
...     type=NamedTypeNode(name=NameNode(value='Int')),
...     default_value=IntValueNode(value='10'),
... )
>>> print_ast(node)
'first: Int = 10'

default_value: IntValueNode | FloatValueNode | StringValueNode | BooleanValueNode | NullValueNode | EnumValueNode | ConstListValueNode | ConstObjectValueNode | None = None: Default value used when no explicit value is supplied.

description: StringValueNode | None = None: The optional GraphQL description associated with this definition.

directives: tuple[ConstDirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'type', 'description', 'default_value', 'directives'): The names of the attributes of this node.

kind: ClassVar[str] = 'input_value_definition': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

type: TypeNode: The GraphQL type reference or runtime type for this element.

class graphql.language.IntValueNode(*, loc: Location | None = None, value: str)

Bases: ValueNode

An integer value literal.

Parameters:

value – Parsed value represented by this node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import IntValueNode, print_ast
>>> print_ast(IntValueNode(value='42'))
'42'

keys: ClassVar[tuple[str, ...]] = ('loc', 'value'): The names of the attributes of this node.

kind: ClassVar[str] = 'int_value': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

value: str: Parsed value represented by this node.

class graphql.language.InterfaceTypeDefinitionNode(*, loc: Location | None = None, name: NameNode, description: StringValueNode | None = None, directives: tuple[ConstDirectiveNode, ...] | None = None, interfaces: tuple[NamedTypeNode, ...] | None = None, fields: tuple[FieldDefinitionNode, ...] | None = None)

Bases: TypeDefinitionNode

An interface type definition in a type-system document.

Parameters:

description – The optional GraphQL description associated with this definition.
name – Name node identifying this AST node.
interfaces – Interfaces implemented by this object or interface type.
directives – Directives available in this schema or applied to this AST node.
fields – Fields declared by this object, interface, input object, or literal.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     FieldDefinitionNode, InterfaceTypeDefinitionNode, NamedTypeNode, NameNode,
...     NonNullTypeNode, print_ast,
... )
>>> field = FieldDefinitionNode(
...     name=NameNode(value='id'),
...     type=NonNullTypeNode(type=NamedTypeNode(name=NameNode(value='ID'))),
... )
>>> node = InterfaceTypeDefinitionNode(name=NameNode(value='Node'), fields=(field,))
>>> print(print_ast(node))
interface Node {
  id: ID!
}

description: StringValueNode | None = None: The optional GraphQL description associated with this definition.

directives: tuple[ConstDirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

fields: tuple[FieldDefinitionNode, ...] | None = None: Fields declared by this object, interface, input object, or literal.

interfaces: tuple[NamedTypeNode, ...] | None = None: Interfaces implemented by this object or interface type.

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'description', 'directives', 'interfaces', 'fields'): The names of the attributes of this node.

kind: ClassVar[str] = 'interface_type_definition': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.InterfaceTypeExtensionNode(*, loc: Location | None = None, name: NameNode, directives: tuple[ConstDirectiveNode, ...] | None = None, interfaces: tuple[NamedTypeNode, ...] | None = None, fields: tuple[FieldDefinitionNode, ...] | None = None)

Bases: TypeExtensionNode

An interface type extension.

Parameters:

name – Name node identifying this AST node.
interfaces – Interfaces implemented by this object or interface type.
directives – Directives available in this schema or applied to this AST node.
fields – Fields declared by this object, interface, input object, or literal.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     InterfaceTypeExtensionNode, NamedTypeNode, NameNode, print_ast,
... )
>>> interface = NamedTypeNode(name=NameNode(value='Node'))
>>> node = InterfaceTypeExtensionNode(
...     name=NameNode(value='Entity'), interfaces=(interface,)
... )
>>> print_ast(node)
'extend interface Entity implements Node'

directives: tuple[ConstDirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

fields: tuple[FieldDefinitionNode, ...] | None = None: Fields declared by this object, interface, input object, or literal.

interfaces: tuple[NamedTypeNode, ...] | None = None: Interfaces implemented by this object or interface type.

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'directives', 'interfaces', 'fields'): The names of the attributes of this node.

kind: ClassVar[str] = 'interface_type_extension': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.ListTypeNode(*, loc: Location | None = None, type: TypeNode)

Bases: TypeNode

A list type reference.

Parameters:

type – The GraphQL type reference or runtime type for this element.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import ListTypeNode, NameNode, NamedTypeNode, print_ast
>>> print_ast(ListTypeNode(type=NamedTypeNode(name=NameNode(value='String'))))
'[String]'

keys: ClassVar[tuple[str, ...]] = ('loc', 'type'): The names of the attributes of this node.

kind: ClassVar[str] = 'list_type': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

type: TypeNode: The GraphQL type reference or runtime type for this element.

class graphql.language.ListValueNode(*, loc: Location | None = None, values: tuple[ValueNode, ...] = ())

Bases: ValueNode

A list value literal.

Parameters:

values – Values contained in this enum, list, or input-object definition.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     IntValueNode, ListValueNode, NameNode, VariableNode, print_ast,
... )
>>> values = (IntValueNode(value='1'), VariableNode(name=NameNode(value='two')))
>>> print_ast(ListValueNode(values=values))
'[1, $two]'

keys: ClassVar[tuple[str, ...]] = ('loc', 'values'): The names of the attributes of this node.

kind: ClassVar[str] = 'list_value': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

values: tuple[ValueNode, ...] = (): Values contained in this enum, list, or input-object definition.

class graphql.language.NameNode(*, loc: Location | None = None, value: str)

Bases: Node

An identifier in a GraphQL document.

Parameters:

value – Parsed value represented by this node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import NameNode, print_ast
>>> print_ast(NameNode(value='hello'))
'hello'

keys: ClassVar[tuple[str, ...]] = ('loc', 'value'): The names of the attributes of this node.

kind: ClassVar[str] = 'name': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

value: str: Parsed value represented by this node.

class graphql.language.NamedTypeNode(*, loc: Location | None = None, name: NameNode)

Bases: TypeNode

A named type reference.

Parameters:

name – Name node identifying this AST node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import NameNode, NamedTypeNode, print_ast
>>> print_ast(NamedTypeNode(name=NameNode(value='String')))
'String'

keys: ClassVar[tuple[str, ...]] = ('loc', 'name'): The names of the attributes of this node.

kind: ClassVar[str] = 'named_type': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.NonNullTypeNode(*, loc: Location | None = None, type: NamedTypeNode | ListTypeNode)

Bases: TypeNode

A non-null type reference.

Parameters:

type – The GraphQL type reference or runtime type for this element.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import NameNode, NamedTypeNode, NonNullTypeNode, print_ast
>>> print_ast(NonNullTypeNode(type=NamedTypeNode(name=NameNode(value='String'))))
'String!'

keys: ClassVar[tuple[str, ...]] = ('loc', 'type'): The names of the attributes of this node.

kind: ClassVar[str] = 'non_null_type': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

type: NamedTypeNode | ListTypeNode: The GraphQL type reference or runtime type for this element.

class graphql.language.NullValueNode(*, loc: Location | None = None)

Bases: ValueNode

A null value literal.

Parameters:: loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import NullValueNode, print_ast
>>> print_ast(NullValueNode())
'null'

keys: ClassVar[tuple[str, ...]] = ('loc',): The names of the attributes of this node.

kind: ClassVar[str] = 'null_value': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.ObjectFieldNode(*, loc: Location | None = None, name: NameNode, value: ValueNode)

Bases: Node

A field inside an input object value literal.

Parameters:

name – Name node identifying this AST node.
value – Parsed value represented by this node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import NameNode, ObjectFieldNode, VariableNode, print_ast
>>> value = VariableNode(name=NameNode(value='a'))
>>> print_ast(ObjectFieldNode(name=NameNode(value='a'), value=value))
'a: $a'

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'value'): The names of the attributes of this node.

kind: ClassVar[str] = 'object_field': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

value: ValueNode: Parsed value represented by this node.

class graphql.language.ObjectTypeDefinitionNode(*, loc: Location | None = None, name: NameNode, description: StringValueNode | None = None, directives: tuple[ConstDirectiveNode, ...] | None = None, interfaces: tuple[NamedTypeNode, ...] | None = None, fields: tuple[FieldDefinitionNode, ...] | None = None)

Bases: TypeDefinitionNode

An object type definition in a type-system document.

Parameters:

description – The optional GraphQL description associated with this definition.
name – Name node identifying this AST node.
interfaces – Interfaces implemented by this object or interface type.
directives – Directives available in this schema or applied to this AST node.
fields – Fields declared by this object, interface, input object, or literal.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     FieldDefinitionNode, NamedTypeNode, NameNode, ObjectTypeDefinitionNode,
...     print_ast,
... )
>>> field = FieldDefinitionNode(
...     name=NameNode(value='hello'),
...     type=NamedTypeNode(name=NameNode(value='String')),
... )
>>> node = ObjectTypeDefinitionNode(name=NameNode(value='Query'), fields=(field,))
>>> print(print_ast(node))
type Query {
  hello: String
}

description: StringValueNode | None = None: The optional GraphQL description associated with this definition.

directives: tuple[ConstDirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

fields: tuple[FieldDefinitionNode, ...] | None = None: Fields declared by this object, interface, input object, or literal.

interfaces: tuple[NamedTypeNode, ...] | None = None: Interfaces implemented by this object or interface type.

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'description', 'directives', 'interfaces', 'fields'): The names of the attributes of this node.

kind: ClassVar[str] = 'object_type_definition': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.ObjectTypeExtensionNode(*, loc: Location | None = None, name: NameNode, directives: tuple[ConstDirectiveNode, ...] | None = None, interfaces: tuple[NamedTypeNode, ...] | None = None, fields: tuple[FieldDefinitionNode, ...] | None = None)

Bases: TypeExtensionNode

An object type extension.

Parameters:

name – Name node identifying this AST node.
interfaces – Interfaces implemented by this object or interface type.
directives – Directives available in this schema or applied to this AST node.
fields – Fields declared by this object, interface, input object, or literal.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     NamedTypeNode, NameNode, ObjectTypeExtensionNode, print_ast,
... )
>>> interface = NamedTypeNode(name=NameNode(value='Node'))
>>> node = ObjectTypeExtensionNode(
...     name=NameNode(value='User'), interfaces=(interface,)
... )
>>> print_ast(node)
'extend type User implements Node'

directives: tuple[ConstDirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

fields: tuple[FieldDefinitionNode, ...] | None = None: Fields declared by this object, interface, input object, or literal.

interfaces: tuple[NamedTypeNode, ...] | None = None: Interfaces implemented by this object or interface type.

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'directives', 'interfaces', 'fields'): The names of the attributes of this node.

kind: ClassVar[str] = 'object_type_extension': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.ObjectValueNode(*, loc: Location | None = None, fields: tuple[ObjectFieldNode, ...] = ())

Bases: ValueNode

An input object value literal.

Parameters:

fields – Fields declared by this object, interface, input object, or literal.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     NameNode, ObjectFieldNode, ObjectValueNode, VariableNode, print_ast
... )
>>> value = VariableNode(name=NameNode(value='a'))
>>> field = ObjectFieldNode(name=NameNode(value='a'), value=value)
>>> print_ast(ObjectValueNode(fields=(field,)))
'{ a: $a }'

fields: tuple[ObjectFieldNode, ...] = (): Fields declared by this object, interface, input object, or literal.

keys: ClassVar[tuple[str, ...]] = ('loc', 'fields'): The names of the attributes of this node.

kind: ClassVar[str] = 'object_value': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.OperationDefinitionNode(*, loc: Location | None = None, selection_set: SelectionSetNode, description: StringValueNode | None = None, name: NameNode | None = None, variable_definitions: tuple[VariableDefinitionNode, ...] | None = None, directives: tuple[DirectiveNode, ...] | None = None, operation: OperationType)

Bases: ExecutableDefinitionNode

A query, mutation, or subscription operation definition.

Parameters:

operation – The operation selected for execution.
description – The optional GraphQL description associated with this definition.
name – Name node identifying this AST node.
variable_definitions – Variable definitions declared by this operation or fragment.
directives – Directives available in this schema or applied to this AST node.
selection_set – Selections made by this operation, field, or fragment.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     FieldNode, NameNode, OperationDefinitionNode, OperationType,
...     SelectionSetNode, print_ast,
... )
>>> field = FieldNode(name=NameNode(value='hello'))
>>> node = OperationDefinitionNode(
...     operation=OperationType.QUERY,
...     name=NameNode(value='Hello'),
...     selection_set=SelectionSetNode(selections=(field,)),
... )
>>> print(print_ast(node))
query Hello {
  hello
}

description: StringValueNode | None = None: The optional GraphQL description associated with this definition.

directives: tuple[DirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

keys: ClassVar[tuple[str, ...]] = ('loc', 'selection_set', 'description', 'name', 'variable_definitions', 'directives', 'operation'): The names of the attributes of this node.

kind: ClassVar[str] = 'operation_definition': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode | None = None: Name node identifying this AST node.

operation: OperationType: The operation selected for execution.

selection_set: SelectionSetNode: Selections made by this operation, field, or fragment.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

variable_definitions: tuple[VariableDefinitionNode, ...] | None = None

Variable definitions declared by this operation or fragment.

Note: variable definitions on fragment definitions are experimental and may be changed or removed in the future.

class graphql.language.OperationType(*values)

Bases: Enum

The operation types supported by GraphQL executable definitions.

MUTATION = 'mutation'

QUERY = 'query'

SUBSCRIPTION = 'subscription'

class graphql.language.OperationTypeDefinitionNode(*, loc: Location | None = None, operation: OperationType, type: NamedTypeNode)

Bases: Node

A root operation type declaration inside a schema definition or extension.

Parameters:

operation – The operation selected for execution.
type – The GraphQL type reference or runtime type for this element.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     NamedTypeNode, NameNode, OperationType, OperationTypeDefinitionNode,
...     print_ast,
... )
>>> node = OperationTypeDefinitionNode(
...     operation=OperationType.QUERY,
...     type=NamedTypeNode(name=NameNode(value='Root')),
... )
>>> print_ast(node)
'query: Root'

keys: ClassVar[tuple[str, ...]] = ('loc', 'operation', 'type'): The names of the attributes of this node.

kind: ClassVar[str] = 'operation_type_definition': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

operation: OperationType: The operation selected for execution.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

type: NamedTypeNode: The GraphQL type reference or runtime type for this element.

class graphql.language.ScalarTypeDefinitionNode(*, loc: Location | None = None, name: NameNode, description: StringValueNode | None = None, directives: tuple[ConstDirectiveNode, ...] | None = None)

Bases: TypeDefinitionNode

A scalar type definition in a type-system document.

Parameters:

description – The optional GraphQL description associated with this definition.
name – Name node identifying this AST node.
directives – Directives available in this schema or applied to this AST node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     NameNode, ScalarTypeDefinitionNode, StringValueNode, print_ast,
... )
>>> node = ScalarTypeDefinitionNode(
...     name=NameNode(value='Date'), description=StringValueNode(value='A date')
... )
>>> print(print_ast(node))
"A date"
scalar Date

description: StringValueNode | None = None: The optional GraphQL description associated with this definition.

directives: tuple[ConstDirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'description', 'directives'): The names of the attributes of this node.

kind: ClassVar[str] = 'scalar_type_definition': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.ScalarTypeExtensionNode(*, loc: Location | None = None, name: NameNode, directives: tuple[ConstDirectiveNode, ...] | None = None)

Bases: TypeExtensionNode

A scalar type extension.

Parameters:

name – Name node identifying this AST node.
directives – Directives available in this schema or applied to this AST node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     ConstDirectiveNode, NameNode, ScalarTypeExtensionNode, print_ast,
... )
>>> directive = ConstDirectiveNode(name=NameNode(value='deprecated'))
>>> node = ScalarTypeExtensionNode(
...     name=NameNode(value='Date'), directives=(directive,)
... )
>>> print_ast(node)
'extend scalar Date @deprecated'

directives: tuple[ConstDirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'directives'): The names of the attributes of this node.

kind: ClassVar[str] = 'scalar_type_extension': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.SchemaDefinitionNode(*, loc: Location | None = None, description: StringValueNode | None = None, directives: tuple[ConstDirectiveNode, ...] | None = None, operation_types: tuple[OperationTypeDefinitionNode, ...] = ())

Bases: TypeSystemDefinitionNode

A schema definition in a type-system document.

Parameters:

description – The optional GraphQL description associated with this definition.
directives – Directives available in this schema or applied to this AST node.
operation_types – Root operation types declared by this schema definition or extension.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     NamedTypeNode, NameNode, OperationType, OperationTypeDefinitionNode,
...     SchemaDefinitionNode, print_ast,
... )
>>> operation_type = OperationTypeDefinitionNode(
...     operation=OperationType.QUERY,
...     type=NamedTypeNode(name=NameNode(value='Root')),
... )
>>> print(print_ast(SchemaDefinitionNode(operation_types=(operation_type,))))
schema {
  query: Root
}

description: StringValueNode | None = None: The optional GraphQL description associated with this definition.

directives: tuple[ConstDirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

keys: ClassVar[tuple[str, ...]] = ('loc', 'description', 'directives', 'operation_types'): The names of the attributes of this node.

kind: ClassVar[str] = 'schema_definition': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

operation_types: tuple[OperationTypeDefinitionNode, ...] = (): Root operation types declared by this schema definition or extension.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.SchemaExtensionNode(*, loc: Location | None = None, directives: tuple[ConstDirectiveNode, ...] | None = None, operation_types: tuple[OperationTypeDefinitionNode, ...] | None = None)

Bases: Node

A schema extension in a type-system document.

Parameters:

directives – Directives available in this schema or applied to this AST node.
operation_types – Root operation types declared by this schema definition or extension.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     ConstDirectiveNode, NameNode, SchemaExtensionNode, print_ast,
... )
>>> directive = ConstDirectiveNode(name=NameNode(value='link'))
>>> print_ast(SchemaExtensionNode(directives=(directive,)))
'extend schema @link'

directives: tuple[ConstDirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

keys: ClassVar[tuple[str, ...]] = ('loc', 'directives', 'operation_types'): The names of the attributes of this node.

kind: ClassVar[str] = 'schema_extension': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

operation_types: tuple[OperationTypeDefinitionNode, ...] | None = None: Root operation types declared by this schema definition or extension.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.SelectionNode(*, loc: Location | None = None, directives: tuple[DirectiveNode, ...] | None = None)

Bases: Node

Base class for selection nodes.

Parameters:

directives – Directives available in this schema or applied to this AST node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import SelectionNode, parse
>>> operation = parse('{ hello ...Hi ... on Query { hi } }').definitions[0]
>>> [isinstance(node, SelectionNode) for node in operation.selection_set.selections]
[True, True, True]

directives: tuple[DirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

keys: ClassVar[tuple[str, ...]] = ('loc', 'directives'): The names of the attributes of this node.

kind: ClassVar[str] = 'selection': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.SelectionSetNode(*, loc: Location | None = None, selections: tuple[SelectionNode, ...] = ())

Bases: Node

A set of fields and fragments selected from an object, interface, or union.

Parameters:

selections – Fields and fragments contained in this selection set.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import FieldNode, NameNode, SelectionSetNode, print_ast
>>> field = FieldNode(name=NameNode(value='hello'))
>>> print(print_ast(SelectionSetNode(selections=(field,))))
{
  hello
}

keys: ClassVar[tuple[str, ...]] = ('loc', 'selections'): The names of the attributes of this node.

kind: ClassVar[str] = 'selection_set': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

selections: tuple[SelectionNode, ...] = (): Fields and fragments contained in this selection set.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.StringValueNode(*, loc: Location | None = None, value: str, block: bool | None = None)

Bases: ValueNode

A string value literal.

Parameters:

value – Parsed value represented by this node.
block – Whether this string was parsed from block string syntax.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import StringValueNode, print_ast
>>> print_ast(StringValueNode(value='hello'))
'"hello"'

block: bool | None = None: Whether this string was parsed from block string syntax.

keys: ClassVar[tuple[str, ...]] = ('loc', 'value', 'block'): The names of the attributes of this node.

kind: ClassVar[str] = 'string_value': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

value: str: Parsed value represented by this node.

class graphql.language.TypeDefinitionNode(*, loc: Location | None = None, name: NameNode, description: StringValueNode | None = None, directives: tuple[ConstDirectiveNode, ...] | None = None)

Bases: TypeSystemDefinitionNode

Base class for type definition nodes.

Parameters:

name – Name node identifying this AST node.
description – The optional GraphQL description associated with this definition.
directives – Directives available in this schema or applied to this AST node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import TypeDefinitionNode, parse
>>> document = parse('scalar Date directive @a on FIELD')
>>> [isinstance(node, TypeDefinitionNode) for node in document.definitions]
[True, False]

description: StringValueNode | None = None: The optional GraphQL description associated with this definition.

directives: tuple[ConstDirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'description', 'directives'): The names of the attributes of this node.

kind: ClassVar[str] = 'type_definition': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.TypeExtensionNode(*, loc: Location | None = None, name: NameNode, directives: tuple[ConstDirectiveNode, ...] | None = None)

Bases: TypeSystemDefinitionNode

Base class for type extension nodes.

Parameters:

name – Name node identifying this AST node.
directives – Directives available in this schema or applied to this AST node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import TypeExtensionNode, parse
>>> document = parse('extend scalar Date @a extend schema @a')
>>> [isinstance(node, TypeExtensionNode) for node in document.definitions]
[True, False]

directives: tuple[ConstDirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'directives'): The names of the attributes of this node.

kind: ClassVar[str] = 'type_extension': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.TypeNode(*, loc: Location | None = None)

Bases: Node

Base class for type nodes.

Parameters:: loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import TypeNode, parse_type
>>> isinstance(parse_type('[String!]'), TypeNode)
True

keys: ClassVar[tuple[str, ...]] = ('loc',): The names of the attributes of this node.

kind: ClassVar[str] = 'type': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.TypeSystemDefinitionNode(*, loc: Location | None = None)

Bases: DefinitionNode

Base class for type system definition nodes.

Parameters:: loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import TypeSystemDefinitionNode, parse
>>> document = parse('schema { query: Query } scalar Date directive @a on FIELD')
>>> [isinstance(node, TypeSystemDefinitionNode) for node in document.definitions]
[True, True, True]

keys: ClassVar[tuple[str, ...]] = ('loc',): The names of the attributes of this node.

kind: ClassVar[str] = 'type_system_definition': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

graphql.language.TypeSystemExtensionNode: alias of SchemaExtensionNode | TypeExtensionNode | DirectiveExtensionNode

class graphql.language.UnionTypeDefinitionNode(*, loc: Location | None = None, name: NameNode, description: StringValueNode | None = None, directives: tuple[ConstDirectiveNode, ...] | None = None, types: tuple[NamedTypeNode, ...] | None = None)

Bases: TypeDefinitionNode

A union type definition in a type-system document.

Parameters:

description – The optional GraphQL description associated with this definition.
name – Name node identifying this AST node.
directives – Directives available in this schema or applied to this AST node.
types – Object types that belong to this union type.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     NamedTypeNode, NameNode, UnionTypeDefinitionNode, print_ast,
... )
>>> types = tuple(NamedTypeNode(name=NameNode(value=name)) for name in ('A', 'B'))
>>> print_ast(UnionTypeDefinitionNode(name=NameNode(value='AOrB'), types=types))
'union AOrB = A | B'

description: StringValueNode | None = None: The optional GraphQL description associated with this definition.

directives: tuple[ConstDirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'description', 'directives', 'types'): The names of the attributes of this node.

kind: ClassVar[str] = 'union_type_definition': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

types: tuple[NamedTypeNode, ...] | None = None: Object types that belong to this union type.

class graphql.language.UnionTypeExtensionNode(*, loc: Location | None = None, name: NameNode, directives: tuple[ConstDirectiveNode, ...] | None = None, types: tuple[NamedTypeNode, ...] | None = None)

Bases: TypeExtensionNode

A union type extension.

Parameters:

name – Name node identifying this AST node.
directives – Directives available in this schema or applied to this AST node.
types – Object types that belong to this union type.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     NamedTypeNode, NameNode, UnionTypeExtensionNode, print_ast,
... )
>>> types = (NamedTypeNode(name=NameNode(value='C')),)
>>> print_ast(UnionTypeExtensionNode(name=NameNode(value='AOrB'), types=types))
'extend union AOrB = C'

directives: tuple[ConstDirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'directives', 'types'): The names of the attributes of this node.

kind: ClassVar[str] = 'union_type_extension': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

types: tuple[NamedTypeNode, ...] | None = None: Object types that belong to this union type.

class graphql.language.ValueNode(*, loc: Location | None = None)

Bases: Node

Base class for value nodes.

Parameters:: loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import ValueNode, parse_value
>>> isinstance(parse_value('[1, "two", $three]'), ValueNode)
True

keys: ClassVar[tuple[str, ...]] = ('loc',): The names of the attributes of this node.

kind: ClassVar[str] = 'value': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

Bases: Node

A variable declaration in an operation or experimental fragment definition.

Parameters:

description – The optional GraphQL description associated with this definition.
variable – The variable being defined or referenced.
type – The GraphQL type reference or runtime type for this element.
default_value – Default value used when no explicit value is supplied.
directives – Directives available in this schema or applied to this AST node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     IntValueNode, NamedTypeNode, NameNode, VariableDefinitionNode, VariableNode,
...     print_ast,
... )
>>> node = VariableDefinitionNode(
...     variable=VariableNode(name=NameNode(value='id')),
...     type=NamedTypeNode(name=NameNode(value='ID')),
...     default_value=IntValueNode(value='4'),
... )
>>> print_ast(node)
'$id: ID = 4'

default_value: IntValueNode | FloatValueNode | StringValueNode | BooleanValueNode | NullValueNode | EnumValueNode | ConstListValueNode | ConstObjectValueNode | None = None: Default value used when no explicit value is supplied.

description: StringValueNode | None = None: The optional GraphQL description associated with this definition.

directives: tuple[ConstDirectiveNode, ...] | None = None: Directives available in this schema or applied to this AST node.

keys: ClassVar[tuple[str, ...]] = ('loc', 'description', 'variable', 'type', 'default_value', 'directives'): The names of the attributes of this node.

kind: ClassVar[str] = 'variable_definition': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

type: TypeNode: The GraphQL type reference or runtime type for this element.

variable: VariableNode: The variable being defined or referenced.

class graphql.language.VariableNode(*, loc: Location | None = None, name: NameNode)

Bases: ValueNode

A variable reference, such as $id.

Parameters:

name – Name node identifying this AST node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import NameNode, VariableNode, print_ast
>>> print_ast(VariableNode(name=NameNode(value='id')))
'$id'

keys: ClassVar[tuple[str, ...]] = ('loc', 'name'): The names of the attributes of this node.

kind: ClassVar[str] = 'variable': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

Schema coordinates are represented using the following node classes:

graphql.language.SchemaCoordinateNode: alias of TypeCoordinateNode | MemberCoordinateNode | ArgumentCoordinateNode | DirectiveCoordinateNode | DirectiveArgumentCoordinateNode

class graphql.language.TypeCoordinateNode(*, loc: Location | None = None, name: NameNode)

Bases: Node

A schema coordinate that refers to a named type.

Parameters:

name – Name node identifying this AST node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import NameNode, TypeCoordinateNode, print_ast
>>> print_ast(TypeCoordinateNode(name=NameNode(value='User')))
'User'

keys: ClassVar[tuple[str, ...]] = ('loc', 'name'): The names of the attributes of this node.

kind: ClassVar[str] = 'type_coordinate': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.MemberCoordinateNode(*, loc: Location | None = None, name: NameNode, member_name: NameNode)

Bases: Node

A schema coordinate that refers to a member of a named type.

Parameters:

name – Name node identifying this AST node.
member_name – The member name referenced by this schema coordinate.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import MemberCoordinateNode, NameNode, print_ast
>>> node = MemberCoordinateNode(
...     name=NameNode(value='User'), member_name=NameNode(value='name')
... )
>>> print_ast(node)
'User.name'

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'member_name'): The names of the attributes of this node.

kind: ClassVar[str] = 'member_coordinate': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

member_name: NameNode: The member name referenced by this schema coordinate.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.ArgumentCoordinateNode(*, loc: Location | None = None, name: NameNode, field_name: NameNode, argument_name: NameNode)

Bases: Node

A schema coordinate that refers to a field or directive argument.

Parameters:

name – Name node identifying this AST node.
field_name – The field name referenced by this schema coordinate.
argument_name – The argument name referenced by this schema coordinate.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import ArgumentCoordinateNode, NameNode, print_ast
>>> node = ArgumentCoordinateNode(
...     name=NameNode(value='Query'),
...     field_name=NameNode(value='user'),
...     argument_name=NameNode(value='id'),
... )
>>> print_ast(node)
'Query.user(id:)'

argument_name: NameNode: The argument name referenced by this schema coordinate.

field_name: NameNode: The field name referenced by this schema coordinate.

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'field_name', 'argument_name'): The names of the attributes of this node.

kind: ClassVar[str] = 'argument_coordinate': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.DirectiveCoordinateNode(*, loc: Location | None = None, name: NameNode)

Bases: Node

A schema coordinate that refers to a directive.

Parameters:

name – Name node identifying this AST node.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import DirectiveCoordinateNode, NameNode, print_ast
>>> print_ast(DirectiveCoordinateNode(name=NameNode(value='deprecated')))
'@deprecated'

keys: ClassVar[tuple[str, ...]] = ('loc', 'name'): The names of the attributes of this node.

kind: ClassVar[str] = 'directive_coordinate': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

class graphql.language.DirectiveArgumentCoordinateNode(*, loc: Location | None = None, name: NameNode, argument_name: NameNode)

Bases: Node

A schema coordinate that refers to a directive argument.

Parameters:

name – Name node identifying this AST node.
argument_name – The argument name referenced by this schema coordinate.
loc – The source location for this AST node, if location tracking was enabled.

>>> from graphql.language import (
...     DirectiveArgumentCoordinateNode, NameNode, print_ast,
... )
>>> node = DirectiveArgumentCoordinateNode(
...     name=NameNode(value='deprecated'), argument_name=NameNode(value='reason')
... )
>>> print_ast(node)
'@deprecated(reason:)'

argument_name: NameNode: The argument name referenced by this schema coordinate.

keys: ClassVar[tuple[str, ...]] = ('loc', 'name', 'argument_name'): The names of the attributes of this node.

kind: ClassVar[str] = 'directive_argument_coordinate': The kind of the node as a snake_case string, identifying the concrete node.

loc: Location | None = None: The source location for this AST node, if location tracking was enabled.

name: NameNode: Name node identifying this AST node.

to_dict(locations: bool = False) → dict

Convert this node to a nested dictionary.

Parameters:: locations – whether the dictionaries should include the locations
Returns:: a JSON-compatible dictionary representing this AST node

>>> from graphql import parse_value
>>> value = parse_value('42')
>>> value.to_dict()
{'kind': 'int_value', 'value': '42'}
>>> value.to_dict(locations=True)
{'kind': 'int_value', 'value': '42', 'loc': {'start': 0, 'end': 2}}

Directive locations are specified using the following enumeration:

class graphql.language.DirectiveLocation(*values)

Bases: Enum

The enum type representing the directive location values.

ARGUMENT_DEFINITION = 'argument definition': Directive location for argument definitions.

DIRECTIVE_DEFINITION = 'directive definition': Directive location for directive definitions and extensions.

ENUM = 'enum': Directive location for enum type definitions and extensions.

ENUM_VALUE = 'enum value': Directive location for enum value definitions.

FIELD = 'field': Directive location for field selections.

FIELD_DEFINITION = 'field definition': Directive location for field definitions.

FRAGMENT_DEFINITION = 'fragment definition': Directive location for fragment definitions.

FRAGMENT_SPREAD = 'fragment spread': Directive location for fragment spreads.

FRAGMENT_VARIABLE_DEFINITION = 'fragment variable definition': Directive location for fragment variable definitions.

INLINE_FRAGMENT = 'inline fragment': Directive location for inline fragments.

INPUT_FIELD_DEFINITION = 'input field definition': Directive location for input object field definitions.

INPUT_OBJECT = 'input object': Directive location for input object type definitions and extensions.

INTERFACE = 'interface': Directive location for interface type definitions and extensions.

MUTATION = 'mutation': Directive location for mutation operations.

OBJECT = 'object': Directive location for object type definitions and extensions.

QUERY = 'query': Directive location for query operations.

SCALAR = 'scalar': Directive location for scalar type definitions and extensions.

SCHEMA = 'schema': Directive location for schema definitions and extensions.

SUBSCRIPTION = 'subscription': Directive location for subscription operations.

UNION = 'union': Directive location for union type definitions and extensions.

VARIABLE_DEFINITION = 'variable definition': Directive location for variable definitions.

You can also check the type of nodes with the following predicates:

graphql.language.is_definition_node(node: Node) → TypeGuard[DefinitionNode]

Check whether the given node represents a definition.

Parameters:: node – the AST node to test
Returns:: whether the AST node is a definition node

>>> from graphql import parse, is_definition_node
>>> document = parse('{ hello }')
>>> is_definition_node(document.definitions[0])
True
>>> is_definition_node(document)
False

graphql.language.is_executable_definition_node(node: Node) → TypeGuard[ExecutableDefinitionNode]

Check whether the given node represents an executable definition.

Parameters:: node – the AST node to test
Returns:: whether the AST node is an executable definition node

>>> from graphql import parse, is_executable_definition_node
>>> query = parse('{ hello }')
>>> schema = parse('type Query { hello: String }')
>>> is_executable_definition_node(query.definitions[0])
True
>>> is_executable_definition_node(schema.definitions[0])
False

graphql.language.is_selection_node(node: Node) → TypeGuard[SelectionNode]

Check whether the given node represents a selection.

Parameters:: node – the AST node to test
Returns:: whether the AST node is a selection node

>>> from graphql import parse, is_selection_node
>>> document = parse('{ hello }')
>>> field = document.definitions[0].selection_set.selections[0]
>>> is_selection_node(field)
True
>>> is_selection_node(document)
False

graphql.language.is_value_node(node: Node) → TypeGuard[ValueNode]

Check whether the given node represents a value.

Parameters:: node – the AST node to test
Returns:: whether the AST node is a value node

>>> from graphql import parse_type, parse_value, is_value_node
>>> value = parse_value('[42]')
>>> type_ = parse_type('[String!]')
>>> is_value_node(value)
True
>>> is_value_node(type_)
False

graphql.language.is_const_value_node(node: Node) → TypeGuard[ValueNode]

Check whether the given node represents a constant value.

Parameters:: node – the AST node to test
Returns:: whether the AST node is a constant value node

>>> from graphql import parse_const_value, parse_value, is_const_value_node
>>> value = parse_const_value('[42]')
>>> variable = parse_value('$id')
>>> is_const_value_node(value)
True
>>> is_const_value_node(variable)
False

graphql.language.is_type_node(node: Node) → TypeGuard[TypeNode]

Check whether the given node represents a type.

Parameters:: node – the AST node to test
Returns:: whether the AST node is a type node

>>> from graphql import parse_type, parse_value, is_type_node
>>> type_ = parse_type('[String!]')
>>> value = parse_value('[42]')
>>> is_type_node(type_)
True
>>> is_type_node(value)
False

graphql.language.is_type_system_definition_node(node: Node) → TypeGuard[TypeSystemDefinitionNode]

Check whether the given node represents a type system definition.

Parameters:: node – the AST node to test
Returns:: whether the AST node is a type system definition node

>>> from graphql import parse, is_type_system_definition_node
>>> schema = parse('type Query { hello: String }')
>>> query = parse('{ hello }')
>>> is_type_system_definition_node(schema.definitions[0])
True
>>> is_type_system_definition_node(query.definitions[0])
False

graphql.language.is_type_definition_node(node: Node) → TypeGuard[TypeDefinitionNode]

Check whether the given node represents a type definition.

Parameters:: node – the AST node to test
Returns:: whether the AST node is a type definition node

>>> from graphql import parse, is_type_definition_node
>>> type_definition = parse('type Query { hello: String }')
>>> directive_definition = parse('directive @cache on FIELD')
>>> is_type_definition_node(type_definition.definitions[0])
True
>>> is_type_definition_node(directive_definition.definitions[0])
False

graphql.language.is_type_system_extension_node(node: Node) → TypeGuard[SchemaExtensionNode | DirectiveExtensionNode | TypeExtensionNode]

Check whether the given node represents a type system extension.

Parameters:: node – the AST node to test
Returns:: whether the AST node is a type system extension node

>>> from graphql import parse, is_type_system_extension_node
>>> extension = parse('extend type Query { hello: String }')
>>> definition = parse('type Query { hello: String }')
>>> is_type_system_extension_node(extension.definitions[0])
True
>>> is_type_system_extension_node(definition.definitions[0])
False

graphql.language.is_type_extension_node(node: Node) → TypeGuard[TypeExtensionNode]

Check whether the given node represents a type extension.

Parameters:: node – the AST node to test
Returns:: whether the AST node is a type extension node

>>> from graphql import parse, is_type_extension_node
>>> extension = parse('extend type Query { hello: String }')
>>> schema_extension = parse('extend schema { query: Query }')
>>> is_type_extension_node(extension.definitions[0])
True
>>> is_type_extension_node(schema_extension.definitions[0])
False

graphql.language.is_schema_coordinate_node(node: Node) → TypeGuard[TypeCoordinateNode | MemberCoordinateNode | ArgumentCoordinateNode | DirectiveCoordinateNode | DirectiveArgumentCoordinateNode]

Check whether the given node represents a schema coordinate.

Parameters:: node – the AST node to test
Returns:: whether the AST node is a schema coordinate node

>>> from graphql import parse, parse_schema_coordinate, is_schema_coordinate_node
>>> coordinate = parse_schema_coordinate('Query.hero')
>>> document = parse('{ hero }')
>>> is_schema_coordinate_node(coordinate)
True
>>> is_schema_coordinate_node(document)
False

graphql.language.is_subscription_operation_definition_node(node: OperationDefinitionNode) → bool

Check whether the given node represents a subscription operation.

Useful anywhere that must distinguish subscription operations from queries and mutations, such as the subscription execution pipeline which routes events through a different code path.

Parameters:: node – operation definition node to test
Returns:: whether the operation definition is a subscription

>>> from graphql import parse, is_subscription_operation_definition_node
>>> subscription = parse('subscription { greeting }').definitions[0]
>>> query = parse('{ greeting }').definitions[0]
>>> is_subscription_operation_definition_node(subscription)
True
>>> is_subscription_operation_definition_node(query)
False

Lexer

class graphql.language.Lexer(source: Source)

Bases: object

GraphQL Lexer

A Lexer is a stateful stream generator in that every time it is advanced, it returns the next token in the Source. Assuming the source lexes, the final Token emitted by the lexer will be of kind EOF, after which the lexer will repeatedly return the same EOF token whenever called.

Given a Source object, creates a Lexer for that source.

Parameters:: source – Source document used to derive error locations.

>>> from graphql.language import Lexer, Source, TokenKind
>>> lexer = Lexer(Source('{ hello }'))
>>> lexer.token.kind
<TokenKind.SOF: '<SOF>'>
>>> lexer.advance().kind
<TokenKind.BRACE_L: '{'>
>>> lexer.advance().value
'hello'
>>> lexer.advance().kind
<TokenKind.BRACE_R: '}'>

advance() → Token

Advance the token stream to the next non-ignored token.

Returns:: The next non-ignored token.

>>> from graphql.language import Lexer, Source
>>> lexer = Lexer(Source('{ hello }'))
>>> token = lexer.advance()
>>> token.kind.value
'{'
>>> lexer.token is token
True

last_token: Token: Most recent non-ignored token returned by the lexer.

line: int: The (1-indexed) line containing the current token.

line_start: int: Character offset where the current line starts.

lookahead() → Token

Look ahead and return the next non-ignored token, but do not change state.

Returns:: The next non-ignored token without advancing the lexer.

>>> from graphql.language import Lexer, Source
>>> lexer = Lexer(Source('{ hello }'))
>>> token = lexer.lookahead()
>>> token.kind.value
'{'
>>> lexer.token.kind.value
'<SOF>'

source: Source: Source document used to derive error locations.

token: Token: Current non-ignored token at the lexer cursor.

class graphql.language.TokenKind(*values)

Bases: Enum

The different kinds of tokens that the lexer emits

AMP = '&'

AT = '@'

BANG = '!'

BLOCK_STRING = 'BlockString'

BRACE_L = '{'

BRACE_R = '}'

BRACKET_L = '['

BRACKET_R = ']'

COLON = ':'

COMMENT = 'Comment'

DOLLAR = '$'

DOT = '.'

EOF = '<EOF>'

EQUALS = '='

FLOAT = 'Float'

INT = 'Int'

NAME = 'Name'

PAREN_L = '('

PAREN_R = ')'

PIPE = '|'

SOF = '<SOF>'

SPREAD = '...'

STRING = 'String'

class graphql.language.Token(kind: TokenKind, start: int, end: int, line: int, column: int, value: str | None = None)

Bases: object

AST Token

Represents a range of characters represented by a lexical token within a Source.

Parameters:

kind – Token kind produced by lexical analysis.
start – Character offset where this token begins.
end – Character offset where this token ends.
line – One-indexed line number where this token begins.
column – One-indexed column number where this token begins.
value – Interpreted value for non-punctuation tokens.

>>> from graphql.language import Token, TokenKind
>>> token = Token(TokenKind.NAME, 2, 7, 1, 3, 'hello')
>>> token.kind
<TokenKind.NAME: 'Name'>
>>> token.value
'hello'
>>> token
<Token Name 'hello' 1:3>

column: int: The 1-indexed column number at which this Token begins.

property desc: str: A helper property to describe a token as a string for debugging

end: int: The character offset at which this Node ends.

kind: TokenKind: The kind of Token.

line: int: The 1-indexed line number on which this Token appears.

next: Token | None: Next token in the token stream, including ignored tokens.

prev: Token | None

Previous token in the token stream, including ignored tokens.

Tokens exist as nodes in a double-linked-list amongst all tokens including ignored tokens. <SOF> is always the first node and <EOF> the last.

start: int: The character offset at which this Node begins.

value: str | None

For non-punctuation tokens, represents the interpreted value of the token.

Note: is None for punctuation tokens.

Location

graphql.language.get_location(source: Source, position: int) → SourceLocation

Get the line and column for a character position in the source.

Takes a Source and a UTF-8 character offset, and returns the corresponding line and column as a SourceLocation.

Parameters:

source – The source document that contains the position.
position – The UTF-8 character offset in the source body.

Returns:

The 1-indexed line and column for the given source position.

>>> from graphql.language import Source, get_location
>>> source = Source('type Query { hello: String }')
>>> get_location(source, 13)
SourceLocation(line=1, column=14)

class graphql.language.SourceLocation(line: int, column: int)

Bases: NamedTuple

Represents a location in a Source.

column: int: One-indexed column number in the source document.

count(value, /): Return number of occurrences of value.

property formatted: FormattedSourceLocation: Get formatted source location.

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

Return first index of value.

Raises ValueError if the value is not present.

line: int: One-indexed line number in the source document.

graphql.language.print_location(location: Location) → str

Render a helpful description of the location in the GraphQL Source document.

Parameters:: location – The AST location to print.
Returns:: A formatted source excerpt with line and column information.

>>> from graphql.language import parse, print_location
>>> document = parse('type Query { hello: String }')
>>> print_location(document.definitions[0].loc)
'GraphQL request:1:1\n1 | type Query { hello: String }\n  | ^'

class graphql.language.FormattedSourceLocation

Bases: TypedDict

Formatted source location

column: int: One-indexed column number in the source document.

line: int: One-indexed line number in the source document.

Parser

graphql.language.parse(source: Source | str, no_location: bool = False, max_tokens: int | None = None, experimental_fragment_arguments: bool = False) → DocumentNode

Given a GraphQL source, parse it into a Document.

Throws GraphQLError if a syntax error is encountered.

By default, the parser creates AST nodes that know the location in the source that they correspond to. The no_location option disables that behavior for performance or testing.

Parser CPU and memory usage is linear to the number of tokens in a document, however in extreme cases it becomes quadratic due to memory exhaustion. Parsing happens before validation so even invalid queries can burn lots of CPU time and memory. To prevent this you can set a maximum number of tokens allowed within a document.

EXPERIMENTAL:

If experimental_fragment_arguments is set to True, the parser will understand and parse fragment variable definitions and arguments on fragment spreads. Fragment variable definitions will be represented in the variable_definitions field of the FragmentDefinitionNode. Fragment spread arguments will be represented in the arguments field of the FragmentSpreadNode.

For example:

{
  t { ...A(var: true) }
}
fragment A($var: Boolean = false) on T {
  ...B(x: $var)
}

Parameters:

source – A GraphQL source string or source object.
no_location – By default, the parser creates AST nodes that know the location in the source that they correspond to. Setting this parameter to True disables that behavior for performance or testing.
max_tokens – Parser CPU and memory usage is linear to the number of tokens in a document, however in extreme cases it becomes quadratic due to memory exhaustion. Parsing happens before validation, so even invalid queries can burn lots of CPU time and memory. To prevent this, you can set a maximum number of tokens allowed within a document.
experimental_fragment_arguments – Allows fragment variable definitions and arguments on fragment spreads to be parsed (experimental).

Returns:

The parsed GraphQL document AST.

Parse a GraphQL document with the default parser options:

>>> from graphql import parse
>>> document = parse('{ hero { name } }')
>>> document.kind
'document'

This variant enables parser options:

>>> document = parse(
...     '{ t { ...A(var: true) } }'
...     ' fragment A($var: Boolean = false) on T { name }',
...     experimental_fragment_arguments=True,
...     max_tokens=80,
...     no_location=True,
... )
>>> directive_document = parse('directive @foo @bar on FIELD')
>>> document.definitions[0].kind
'operation_definition'
>>> document.definitions[1].kind
'fragment_definition'
>>> document.loc is None
True
>>> directive_document.definitions[0].kind
'directive_definition'

graphql.language.parse_type(source: Source | str, no_location: bool = False, max_tokens: int | None = None, experimental_fragment_arguments: bool = False) → TypeNode

Parse the AST for a given string containing a GraphQL Type.

Throws GraphQLError if a syntax error is encountered.

This is useful within tools that operate upon GraphQL Types directly and in isolation of complete GraphQL documents.

Consider providing the results to the utility function: value_from_ast().

Parameters:

source – A GraphQL source string or source object containing a type reference.
no_location – By default, the parser creates AST nodes that know the location in the source that they correspond to. Setting this parameter to True disables that behavior for performance or testing.
max_tokens – Parser CPU and memory usage is linear to the number of tokens in a document, however in extreme cases it becomes quadratic due to memory exhaustion. Parsing happens before validation, so even invalid queries can burn lots of CPU time and memory. To prevent this, you can set a maximum number of tokens allowed within a document.
experimental_fragment_arguments – Allows fragment variable definitions and arguments on fragment spreads to be parsed (experimental).

Returns:

The parsed GraphQL type AST.

>>> from graphql import parse_type
>>> type_ = parse_type('[String!]')
>>> type_.kind
'list_type'

graphql.language.parse_value(source: Source | str, no_location: bool = False, max_tokens: int | None = None, experimental_fragment_arguments: bool = False) → ValueNode

Parse the AST for a given string containing a GraphQL value.

Throws GraphQLError if a syntax error is encountered.

This is useful within tools that operate upon GraphQL Values directly and in isolation of complete GraphQL documents.

Parameters:

source – A GraphQL source string or source object containing a value.
no_location – By default, the parser creates AST nodes that know the location in the source that they correspond to. Setting this parameter to True disables that behavior for performance or testing.
max_tokens – Parser CPU and memory usage is linear to the number of tokens in a document, however in extreme cases it becomes quadratic due to memory exhaustion. Parsing happens before validation, so even invalid queries can burn lots of CPU time and memory. To prevent this, you can set a maximum number of tokens allowed within a document.
experimental_fragment_arguments – Allows fragment variable definitions and arguments on fragment spreads to be parsed (experimental).

Returns:

The parsed GraphQL value AST.

>>> from graphql import parse_value
>>> value = parse_value('[42]')
>>> value.kind
'list_value'

Parse the AST for a given string containing a GraphQL constant value.

Similar to parse_value, but raises a parse error if it encounters a variable. The return type will be a constant value.

Parameters:

source – A GraphQL source string or source object containing a constant value.
no_location – By default, the parser creates AST nodes that know the location in the source that they correspond to. Setting this parameter to True disables that behavior for performance or testing.
max_tokens – Parser CPU and memory usage is linear to the number of tokens in a document, however in extreme cases it becomes quadratic due to memory exhaustion. Parsing happens before validation, so even invalid queries can burn lots of CPU time and memory. To prevent this, you can set a maximum number of tokens allowed within a document.
experimental_fragment_arguments – Allows fragment variable definitions and arguments on fragment spreads to be parsed (experimental).

Returns:

The parsed GraphQL constant value AST.

>>> from graphql import parse_const_value
>>> value = parse_const_value('{ enabled: true }')
>>> value.kind
'object_value'
>>> parse_const_value('$variable')
Traceback (most recent call last):
...
graphql.error.syntax_error.GraphQLSyntaxError: Syntax Error: Unexpected ...

Parse the AST for a given string containing a GraphQL schema coordinate.

Throws GraphQLError if a syntax error is encountered.

This is useful within tools that operate upon GraphQL schema coordinates (ex. Type.field) directly and in isolation of complete GraphQL documents.

Consider providing the results to the utility function: resolve_ast_schema_coordinate(). Or calling resolve_schema_coordinate() directly with an unparsed source.

Parameters:

source – A GraphQL source string or source object containing a schema coordinate.
no_location – By default, the parser creates AST nodes that know the location in the source that they correspond to. Setting this parameter to True disables that behavior for performance or testing.
max_tokens – Parser CPU and memory usage is linear to the number of tokens in a document, however in extreme cases it becomes quadratic due to memory exhaustion. Parsing happens before validation, so even invalid queries can burn lots of CPU time and memory. To prevent this, you can set a maximum number of tokens allowed within a document.

Returns:

The parsed GraphQL schema coordinate AST.

>>> from graphql import parse_schema_coordinate
>>> coordinate = parse_schema_coordinate('Query.hero')
>>> coordinate.kind
'member_coordinate'

Printer

graphql.language.print_ast(ast: Node) → str

Convert an AST into a string.

The conversion is done using a set of reasonable formatting rules.

Parameters:: ast – The GraphQL AST node to print.
Returns:: A stable string representation of the AST.

>>> from graphql import parse, print_ast
>>> ast = parse('{ hero { name } }')
>>> print_ast(ast)
'{\n  hero {\n    name\n  }\n}'

Source

class graphql.language.Source(body: str, name: str = 'GraphQL request', location_offset: SourceLocation = (1, 1))

Bases: object

A representation of source input to GraphQL.

The name and location_offset parameters are optional, but they are useful for clients who store GraphQL documents in source files. For example, if the GraphQL input starts at line 40 in a file named Foo.graphql, it might be useful for name to be "Foo.graphql" and location to be (40, 1).

The line and column attributes in location_offset are 1-indexed.

Parameters:

body – The GraphQL source text.
name – Name used in diagnostics for this source.
location_offset – One-indexed line and column where this source begins.

>>> from graphql.language import Source
>>> source = Source(
...     'type Query { greeting: String }',
...     'schema.graphql',
...     (10, 1),
... )
>>> source.body
'type Query { greeting: String }'
>>> source.name
'schema.graphql'
>>> source.location_offset
SourceLocation(line=10, column=1)

body: str: The GraphQL source text.

get_location(position: int) → SourceLocation

Get the line and column for a character position in this source.

Parameters:: position – The UTF-8 character offset in the source body.
Returns:: The 1-indexed line and column for the given source position.

>>> from graphql.language import Source
>>> Source('type Query {\n  hello: String\n}').get_location(15)
SourceLocation(line=2, column=3)

location_offset: SourceLocation: One-indexed line and column where this source begins.

name: str: Name used in diagnostics for this source, such as a file path or request name.

graphql.language.print_source_location(source: Source, source_location: SourceLocation) → str

Render a helpful description of the location in the GraphQL Source document.

Parameters:

source – The source document that contains the location.
source_location – The 1-indexed line and column to print.

Returns:

A formatted source excerpt with line and column information.

>>> from graphql.language import (
...     Source, SourceLocation, print_source_location)
>>> source = Source('type Query { hello: String }')
>>> print_source_location(source, SourceLocation(line=1, column=14))
'GraphQL request:1:14\n1 | type Query { hello: String }\n  |              ^'

Visitor

graphql.language.visit(root: Node, visitor: Visitor, visitor_keys: dict[str, tuple[str, ...]] | None = None) → Any

Visit each node in an AST.

visit() will walk through an AST using a depth-first traversal, calling the visitor’s enter methods at each node in the traversal, and calling the leave methods after visiting that node and all of its child nodes.

By returning different values from the enter and leave methods, the behavior of the visitor can be altered, including skipping over a sub-tree of the AST (by returning False), editing the AST by returning a value or None to remove the value, or to stop the whole traversal by returning BREAK.

When using visit() to edit an AST, the original AST will not be modified, and a new version of the AST with the changes applied will be returned from the visit function.

To customize the node attributes to be used for traversal, you can provide a dictionary visitor_keys mapping node kinds to node attributes.

Parameters:

root – The AST node at which to start traversal.
visitor – The visitor whose methods are called while traversing.
visitor_keys – Optional map of child keys to visit for each AST node kind.

Returns:

The original AST, an edited AST, or a reduced value depending on the visitor.

Return values control traversal: None makes no change, SKIP or False skips a subtree, BREAK or True stops traversal, REMOVE or ... removes a node, and any other value replaces the current node:

>>> from dataclasses import replace
>>> from graphql import NameNode, parse, print_ast, visit, Visitor
>>> document = parse('{ hero { name } }')
>>> class RenameVisitor(Visitor):
...     def enter_field(self, node, *_args):
...         if node.name.value == 'hero':
...             return replace(node, name=NameNode(value='human'))
>>> edited_ast = visit(document, RenameVisitor())
>>> print_ast(edited_ast)
'{\n  human {\n    name\n  }\n}'

A kind specific visitor method runs when entering nodes of that kind:

>>> field_names = []
>>> class FieldVisitor(Visitor):
...     def enter_field(self, node, *_args):
...         field_names.append(node.name.value)
>>> visit(document, FieldVisitor()) is document
True
>>> field_names
['hero', 'name']

Generic enter and leave methods run for every node:

>>> class CountingVisitor(Visitor):
...     entered = left = 0
...     def enter(self, *_args):
...         self.entered += 1
...     def leave(self, *_args):
...         self.left += 1
>>> visitor = CountingVisitor()
>>> visit(document, visitor) is document
True
>>> visitor.entered == visitor.left
True
>>> visitor.entered > 0
True

A visitor can return values from its leave methods to build a reduced result instead of returning an edited AST:

>>> class ReducingVisitor(Visitor):
...     def leave_name(self, node, *_args):
...         return node.value
...     def leave_field(self, node, *_args):
...         if node.selection_set is None:
...             return node.name
...         return f'{node.name} {{ {node.selection_set} }}'
...     def leave_selection_set(self, node, *_args):
...         return ' '.join(node.selections)
...     def leave_operation_definition(self, node, *_args):
...         return node.selection_set
...     def leave_document(self, node, *_args):
...         return '\n'.join(node.definitions)
>>> visit(document, ReducingVisitor())
'hero { name }'

class graphql.language.Visitor

Bases: object

Visitor that walks through an AST.

Visitors can define two generic methods “enter” and “leave”. The former will be called when a node is entered in the traversal, the latter is called after visiting the node and its child nodes. These methods have the following signature:

def enter(self, node, key, parent, path, ancestors):
    # The return value has the following meaning:
    # IDLE (None): no action
    # SKIP: skip visiting this node
    # BREAK: stop visiting altogether
    # REMOVE: delete this node
    # any other value: replace this node with the returned value
    return

def leave(self, node, key, parent, path, ancestors):
    # The return value has the following meaning:
    # IDLE (None) or SKIP: no action
    # BREAK: stop visiting altogether
    # REMOVE: delete this node
    # any other value: replace this node with the returned value
    return

The parameters have the following meaning:

Parameters:

node – Current node being visited.
key – Index or key for this node within the parent node or array.
parent – Parent immediately above this node, which may be an array.
path – Key path from the root node to this node.
ancestors – All nodes and arrays visited before reaching this node’s parent. These correspond to array indices in path. Note: ancestors includes arrays that contain the visited node’s parent.

You can also define node kind specific methods by suffixing them with an underscore followed by the kind of the node to be visited. For instance, to visit field nodes, you would define the methods enter_field() and/or leave_field(), with the same signature as above. If no kind specific method has been defined for a given node, the generic method is called.

A visitor can provide separate enter and leave methods for nodes of a kind:

>>> from graphql import parse, visit, Visitor
>>> document = parse('{ hero { name } }')
>>> events = []
>>> class FieldVisitor(Visitor):
...     def enter_field(self, node, *_args):
...         events.append(f'enter:{node.name.value}')
...     def leave_field(self, node, *_args):
...         events.append(f'leave:{node.name.value}')
>>> visit(document, FieldVisitor()) is document
True
>>> events
['enter:hero', 'enter:name', 'leave:name', 'leave:hero']

BREAK = True

IDLE = None

REMOVE = Ellipsis

SKIP = False

enter_leave_map: dict[str, EnterLeaveVisitor]: Cache of the enter and leave methods of this visitor per node kind.

get_enter_leave_for_kind(kind: str) → EnterLeaveVisitor

Given a node kind, return the EnterLeaveVisitor for that kind.

Parameters:: kind – The AST node kind to resolve methods for.
Returns:: The enter and leave methods that apply for the given node kind.

>>> from graphql import Visitor
>>> class FieldVisitor(Visitor):
...     def enter_field(self, node, *_args):
...         pass
>>> enter, leave = FieldVisitor().get_enter_leave_for_kind('field')
>>> callable(enter)
True
>>> leave is None
True

class graphql.language.ParallelVisitor(visitors: Collection[Visitor])

Bases: Visitor

A Visitor which delegates to many visitors to run in parallel.

Each visitor will be visited for each node before moving on.

If a prior visitor edits a node, no following visitors will see that node.

Parameters:: visitors – The visitors to merge into one parallel visitor.

>>> from graphql import parse, visit, ParallelVisitor, Visitor
>>> document = parse('{ hero { name } }')
>>> events = []
>>> class FieldVisitor(Visitor):
...     def enter_field(self, node, *_args):
...         events.append(f'field:{node.name.value}')
>>> class NameVisitor(Visitor):
...     def enter_name(self, node, *_args):
...         events.append(f'name:{node.value}')
>>> parallel_visitor = ParallelVisitor([FieldVisitor(), NameVisitor()])
>>> visit(document, parallel_visitor) is document
True
>>> events
['field:hero', 'name:hero', 'field:name', 'name:name']

BREAK = True

IDLE = None

REMOVE = Ellipsis

SKIP = False

enter_leave_map: dict[str, EnterLeaveVisitor]: Cache of the enter and leave methods of this visitor per node kind.

get_enter_leave_for_kind(kind: str) → EnterLeaveVisitor

Given a node kind, return the EnterLeaveVisitor for that kind.

The returned methods delegate to the corresponding methods of all visitors.

Parameters:: kind – The AST node kind to resolve methods for.
Returns:: The merged enter and leave methods for the given node kind.

>>> from graphql import ParallelVisitor, Visitor
>>> class FieldVisitor(Visitor):
...     def enter_field(self, node, *_args):
...         pass
>>> class NameVisitor(Visitor):
...     def leave_name(self, node, *_args):
...         pass
>>> visitor = ParallelVisitor([FieldVisitor(), NameVisitor()])
>>> enter, leave = visitor.get_enter_leave_for_kind('field')
>>> callable(enter) and callable(leave)
True
>>> visitor.get_enter_leave_for_kind('document')
EnterLeaveVisitor(enter=None, leave=None)

skipping: list[Any]

The module also exports the following enumeration that can be used as the return type for Visitor methods:

class graphql.language.visitor.VisitorActionEnum(*values)

Bases: Enum

Special return values for the visitor methods.

You can also use the values of this enum directly.

BREAK = True

REMOVE = Ellipsis

SKIP = False

The module also exports the values of this enumeration directly. These can be used as return values of Visitor methods to signal particular actions:

graphql.language.BREAK (same as ``True``): This return value signals that no further nodes shall be visited.

graphql.language.SKIP (same as ``False``): This return value signals that the current node shall be skipped.

graphql.language.REMOVE (same as``Ellipsis``): This return value signals that the current node shall be deleted.

graphql.language.IDLE = None: This return value signals that no additional action shall take place.