gql.dsl

gql.dsl.ast_from_serialized_value_untyped(serialized: Any) → ValueNode | None

Given a serialized value, try our best to produce an AST.

Anything ressembling an array (instance of Mapping) will be converted to an ObjectFieldNode.

Anything ressembling a list (instance of Iterable - except str) will be converted to a ListNode.

In some cases, a custom scalar can be serialized differently in the query than in the variables. In that case, this function will not work.

gql.dsl.ast_from_value(value: Any, type_: GraphQLScalarType | GraphQLEnumType | GraphQLInputObjectType | GraphQLWrappingType) → ValueNode | None

This is a partial copy paste of the ast_from_value function in graphql-core utilities/ast_from_value.py

Overwrite the if blocks that use recursion and add a new case to return a VariableNode when value is a DSLVariable

Produce a GraphQL Value AST given a Python object.

Raises a GraphQLError instead of returning None if we receive an Undefined of if we receive a Null value for a Non-Null type.

gql.dsl.dsl_gql(*operations: DSLExecutable, **operations_with_name: DSLExecutable) → DocumentNode

Given arguments instances of DSLExecutable containing GraphQL operations or fragments, generate a Document which can be executed later in a gql client or a gql session.

Similar to the gql.gql() function but instead of parsing a python string to describe the request, we are using operations which have been generated dynamically using instances of DSLField, generated by instances of DSLType which themselves originated from a DSLSchema class.

Parameters:
Returns:

a Document which can be later executed or subscribed by a Client, by an async session or by a sync session

Raises:

  • TypeError – if an argument is not an instance of DSLExecutable

  • AttributeError – if a type has not been provided in a DSLFragment

class gql.dsl.DSLSchema(schema: GraphQLSchema)

Bases: object

The DSLSchema is the root of the DSL code.

Attributes of the DSLSchema class are generated automatically with the __getattr__ dunder method in order to generate instances of DSLType

__init__(schema: GraphQLSchema)

Initialize the DSLSchema with the given schema.

Parameters:

schema (GraphQLSchema) – a GraphQL Schema provided locally or fetched using an introspection query. Usually client.schema

Raises:

TypeError – if the argument is not an instance of GraphQLSchema

class gql.dsl.DSLSelector(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)

Bases: ABC

DSLSelector is an abstract class which defines the select method to select children fields in the query.

Inherited by DSLRootFieldSelector, DSLFieldSelector DSLFragmentSelector

__init__(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)
selection_set: SelectionSetNode
abstract is_valid_field(field: DSLSelectable) → bool
select(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)

Select the fields which should be added.

Parameters:
Raises:

  • TypeError – if an argument is not an instance of DSLSelectable

  • graphql.error.GraphQLError – if an argument is not a valid field

class gql.dsl.DSLExecutable(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)

Bases: DSLSelector

Interface for the root elements which can be executed in the dsl_gql function

Inherited by DSLOperation and DSLFragment

selection_set: SelectionSetNode
abstract property executable_ast

Generates the ast for dsl_gql.

__init__(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)

Given arguments of type DSLSelectable containing GraphQL requests, generate an operation which can be converted to a Document using the dsl_gql.

The fields arguments should be either be fragments or fields of root GraphQL types (Query, Mutation or Subscription) and correspond to the operation_type of this operation.

Parameters:

  • *fields (DSLSelectable) – root fields or fragments

  • **fields_with_alias (DSLSelectable) – root fields or fragments with alias as key

Raises:

  • TypeError – if an argument is not an instance of DSLSelectable

  • AssertionError – if an argument is not a field which correspond to the operation type

name: str | None
variable_definitions: DSLVariableDefinitions
abstract is_valid_field(field: DSLSelectable) → bool
select(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)

Select the fields which should be added.

Parameters:
Raises:

  • TypeError – if an argument is not an instance of DSLSelectable

  • graphql.error.GraphQLError – if an argument is not a valid field

class gql.dsl.DSLRootFieldSelector(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)

Bases: DSLSelector

Class used to define the is_valid_field method for root fields for the select method.

Inherited by DSLOperation

is_valid_field(field: DSLSelectable) → bool

Check that a field is valid for a root field.

For operations, the fields arguments should be fields of root GraphQL types (Query, Mutation or Subscription) and correspond to the operation_type of this operation.

the __typename field can only be added to Query or Mutation. the __schema and __type field can only be added to Query.

__init__(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)
select(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)

Select the fields which should be added.

Parameters:
Raises:

  • TypeError – if an argument is not an instance of DSLSelectable

  • graphql.error.GraphQLError – if an argument is not a valid field

selection_set: SelectionSetNode
class gql.dsl.DSLOperation(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)

Bases: DSLExecutable, DSLRootFieldSelector

Interface for GraphQL operations.

Inherited by DSLQuery, DSLMutation and DSLSubscription

operation_type: OperationType
property executable_ast: OperationDefinitionNode

Generates the ast for dsl_gql.

__init__(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)

Given arguments of type DSLSelectable containing GraphQL requests, generate an operation which can be converted to a Document using the dsl_gql.

The fields arguments should be either be fragments or fields of root GraphQL types (Query, Mutation or Subscription) and correspond to the operation_type of this operation.

Parameters:

  • *fields (DSLSelectable) – root fields or fragments

  • **fields_with_alias (DSLSelectable) – root fields or fragments with alias as key

Raises:

  • TypeError – if an argument is not an instance of DSLSelectable

  • AssertionError – if an argument is not a field which correspond to the operation type

is_valid_field(field: DSLSelectable) → bool

Check that a field is valid for a root field.

For operations, the fields arguments should be fields of root GraphQL types (Query, Mutation or Subscription) and correspond to the operation_type of this operation.

the __typename field can only be added to Query or Mutation. the __schema and __type field can only be added to Query.

select(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)

Select the fields which should be added.

Parameters:
Raises:

  • TypeError – if an argument is not an instance of DSLSelectable

  • graphql.error.GraphQLError – if an argument is not a valid field

variable_definitions: DSLVariableDefinitions
name: str | None
selection_set: SelectionSetNode
class gql.dsl.DSLQuery(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)

Bases: DSLOperation

operation_type: OperationType = 'query'
__init__(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)

Given arguments of type DSLSelectable containing GraphQL requests, generate an operation which can be converted to a Document using the dsl_gql.

The fields arguments should be either be fragments or fields of root GraphQL types (Query, Mutation or Subscription) and correspond to the operation_type of this operation.

Parameters:

  • *fields (DSLSelectable) – root fields or fragments

  • **fields_with_alias (DSLSelectable) – root fields or fragments with alias as key

Raises:

  • TypeError – if an argument is not an instance of DSLSelectable

  • AssertionError – if an argument is not a field which correspond to the operation type

property executable_ast: OperationDefinitionNode

Generates the ast for dsl_gql.

is_valid_field(field: DSLSelectable) → bool

Check that a field is valid for a root field.

For operations, the fields arguments should be fields of root GraphQL types (Query, Mutation or Subscription) and correspond to the operation_type of this operation.

the __typename field can only be added to Query or Mutation. the __schema and __type field can only be added to Query.

select(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)

Select the fields which should be added.

Parameters:
Raises:

  • TypeError – if an argument is not an instance of DSLSelectable

  • graphql.error.GraphQLError – if an argument is not a valid field

variable_definitions: DSLVariableDefinitions
name: str | None
selection_set: SelectionSetNode
class gql.dsl.DSLMutation(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)

Bases: DSLOperation

operation_type: OperationType = 'mutation'
__init__(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)

Given arguments of type DSLSelectable containing GraphQL requests, generate an operation which can be converted to a Document using the dsl_gql.

The fields arguments should be either be fragments or fields of root GraphQL types (Query, Mutation or Subscription) and correspond to the operation_type of this operation.

Parameters:

  • *fields (DSLSelectable) – root fields or fragments

  • **fields_with_alias (DSLSelectable) – root fields or fragments with alias as key

Raises:

  • TypeError – if an argument is not an instance of DSLSelectable

  • AssertionError – if an argument is not a field which correspond to the operation type

property executable_ast: OperationDefinitionNode

Generates the ast for dsl_gql.

is_valid_field(field: DSLSelectable) → bool

Check that a field is valid for a root field.

For operations, the fields arguments should be fields of root GraphQL types (Query, Mutation or Subscription) and correspond to the operation_type of this operation.

the __typename field can only be added to Query or Mutation. the __schema and __type field can only be added to Query.

select(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)

Select the fields which should be added.

Parameters:
Raises:

  • TypeError – if an argument is not an instance of DSLSelectable

  • graphql.error.GraphQLError – if an argument is not a valid field

variable_definitions: DSLVariableDefinitions
name: str | None
selection_set: SelectionSetNode
class gql.dsl.DSLSubscription(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)

Bases: DSLOperation

operation_type: OperationType = 'subscription'
__init__(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)

Given arguments of type DSLSelectable containing GraphQL requests, generate an operation which can be converted to a Document using the dsl_gql.

The fields arguments should be either be fragments or fields of root GraphQL types (Query, Mutation or Subscription) and correspond to the operation_type of this operation.

Parameters:

  • *fields (DSLSelectable) – root fields or fragments

  • **fields_with_alias (DSLSelectable) – root fields or fragments with alias as key

Raises:

  • TypeError – if an argument is not an instance of DSLSelectable

  • AssertionError – if an argument is not a field which correspond to the operation type

property executable_ast: OperationDefinitionNode

Generates the ast for dsl_gql.

is_valid_field(field: DSLSelectable) → bool

Check that a field is valid for a root field.

For operations, the fields arguments should be fields of root GraphQL types (Query, Mutation or Subscription) and correspond to the operation_type of this operation.

the __typename field can only be added to Query or Mutation. the __schema and __type field can only be added to Query.

select(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)

Select the fields which should be added.

Parameters:
Raises:

  • TypeError – if an argument is not an instance of DSLSelectable

  • graphql.error.GraphQLError – if an argument is not a valid field

variable_definitions: DSLVariableDefinitions
name: str | None
selection_set: SelectionSetNode
class gql.dsl.DSLVariable(name: str)

Bases: object

The DSLVariable represents a single variable defined in a GraphQL operation

Instances of this class are generated for you automatically as attributes of the DSLVariableDefinitions

The type of the variable is set by the DSLField instance that receives it in the args method.

__init__(name: str)
to_ast_type(type_: GraphQLScalarType | GraphQLEnumType | GraphQLInputObjectType | GraphQLWrappingType) → TypeNode
set_type(type_: GraphQLScalarType | GraphQLEnumType | GraphQLInputObjectType | GraphQLWrappingType) → DSLVariable
default(default_value: Any) → DSLVariable
class gql.dsl.DSLVariableDefinitions

Bases: object

The DSLVariableDefinitions represents variable definitions in a GraphQL operation

Instances of this class have to be created and set as the variable_definitions attribute of a DSLOperation instance

Attributes of the DSLVariableDefinitions class are generated automatically with the __getattr__ dunder method in order to generate instances of DSLVariable, that can then be used as values in the args method.

__init__()
class gql.dsl.DSLType(graphql_type: GraphQLObjectType | GraphQLInterfaceType, dsl_schema: DSLSchema)

Bases: object

The DSLType represents a GraphQL type for the DSL code.

It can be a root type (Query, Mutation or Subscription). Or it can be any other object type (Human in the StarWars schema). Or it can be an interface type (Character in the StarWars schema).

Instances of this class are generated for you automatically as attributes of the DSLSchema

Attributes of the DSLType class are generated automatically with the __getattr__ dunder method in order to generate instances of DSLField

__init__(graphql_type: GraphQLObjectType | GraphQLInterfaceType, dsl_schema: DSLSchema)

Initialize the DSLType with the GraphQL type.

Warning

Don’t instantiate this class yourself. Use attributes of the DSLSchema instead.

Parameters:

  • graphql_type – the GraphQL type definition from the schema

  • dsl_schema – reference to the DSLSchema which created this type

class gql.dsl.DSLSelectable

Bases: ABC

DSLSelectable is an abstract class which indicates that the subclasses can be used as arguments of the select method.

Inherited by DSLField, DSLFragment DSLInlineFragment

ast_field: FieldNode | InlineFragmentNode | FragmentSpreadNode
class gql.dsl.DSLFragmentSelector(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)

Bases: DSLSelector

Class used to define the is_valid_field method for fragments for the select method.

Inherited by DSLFragment, DSLInlineFragment

is_valid_field(field: DSLSelectable) → bool

Check that a field is valid.

__init__(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)
select(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)

Select the fields which should be added.

Parameters:
Raises:

  • TypeError – if an argument is not an instance of DSLSelectable

  • graphql.error.GraphQLError – if an argument is not a valid field

selection_set: SelectionSetNode
class gql.dsl.DSLFieldSelector(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)

Bases: DSLSelector

Class used to define the is_valid_field method for fields for the select method.

Inherited by DSLField,

is_valid_field(field: DSLSelectable) → bool

Check that a field is valid.

__init__(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)
select(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)

Select the fields which should be added.

Parameters:
Raises:

  • TypeError – if an argument is not an instance of DSLSelectable

  • graphql.error.GraphQLError – if an argument is not a valid field

selection_set: SelectionSetNode
class gql.dsl.DSLSelectableWithAlias

Bases: DSLSelectable

DSLSelectableWithAlias is an abstract class which indicates that the subclasses can be selected with an alias.

ast_field: FieldNode
alias(alias: str) → DSLSelectableWithAlias

Set an alias

Note

You can also pass the alias directly at the select method. ds.Query.human.select(my_name=ds.Character.name) is equivalent to: ds.Query.human.select(ds.Character.name.alias("my_name"))

Parameters:

alias (str) – the alias

Returns:

itself

class gql.dsl.DSLField(name: str, parent_type: GraphQLObjectType | GraphQLInterfaceType, field: GraphQLField, dsl_type: DSLType | None = None)

Bases: DSLSelectableWithAlias, DSLFieldSelector

The DSLField represents a GraphQL field for the DSL code.

Instances of this class are generated for you automatically as attributes of the DSLType

If this field contains children fields, then you need to select which ones you want in the request using the select method.

__init__(name: str, parent_type: GraphQLObjectType | GraphQLInterfaceType, field: GraphQLField, dsl_type: DSLType | None = None)

Initialize the DSLField.

Warning

Don’t instantiate this class yourself. Use attributes of the DSLType instead.

Parameters:

  • name – the name of the field

  • parent_type – the GraphQL type definition from the schema of the parent type of the field

  • field – the GraphQL field definition from the schema

  • dsl_type – reference of the DSLType instance which created this field

field: GraphQLField
ast_field: FieldNode
args(**kwargs) → DSLField

Set the arguments of a field

The arguments are parsed to be stored in the AST of this field.

Note

You can also call the field directly with your arguments. ds.Query.human(id=1000) is equivalent to: ds.Query.human.args(id=1000)

Parameters:

**kwargs – the arguments (keyword=value)

Returns:

itself

Raises:

KeyError – if any of the provided arguments does not exist for this field.

select(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias) → DSLField

Calling select method with corrected typing hints

alias(alias: str) → DSLSelectableWithAlias

Set an alias

Note

You can also pass the alias directly at the select method. ds.Query.human.select(my_name=ds.Character.name) is equivalent to: ds.Query.human.select(ds.Character.name.alias("my_name"))

Parameters:

alias (str) – the alias

Returns:

itself

is_valid_field(field: DSLSelectable) → bool

Check that a field is valid.

selection_set: SelectionSetNode
class gql.dsl.DSLMetaField(name: str)

Bases: DSLField

DSLMetaField represents a GraphQL meta-field for the DSL code.

meta-fields are reserved field in the GraphQL type system prefixed with “__” two underscores and used for introspection.

meta_type = <GraphQLObjectType 'meta_field'>
__init__(name: str)

Initialize the meta-field.

Parameters:

name – the name between __typename, __schema or __type

alias(alias: str) → DSLSelectableWithAlias

Set an alias

Note

You can also pass the alias directly at the select method. ds.Query.human.select(my_name=ds.Character.name) is equivalent to: ds.Query.human.select(ds.Character.name.alias("my_name"))

Parameters:

alias (str) – the alias

Returns:

itself

args(**kwargs) → DSLField

Set the arguments of a field

The arguments are parsed to be stored in the AST of this field.

Note

You can also call the field directly with your arguments. ds.Query.human(id=1000) is equivalent to: ds.Query.human.args(id=1000)

Parameters:

**kwargs – the arguments (keyword=value)

Returns:

itself

Raises:

KeyError – if any of the provided arguments does not exist for this field.

is_valid_field(field: DSLSelectable) → bool

Check that a field is valid.

select(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias) → DSLField

Calling select method with corrected typing hints

ast_field: FieldNode
field: GraphQLField
selection_set: SelectionSetNode
class gql.dsl.DSLInlineFragment(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)

Bases: DSLSelectable, DSLFragmentSelector

DSLInlineFragment represents an inline fragment for the DSL code.

__init__(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias)

Initialize the DSLInlineFragment.

Parameters:
ast_field: InlineFragmentNode
select(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias) → DSLInlineFragment

Calling select method with corrected typing hints

on(type_condition: DSLType) → DSLInlineFragment

Provides the GraphQL type of this inline fragment.

is_valid_field(field: DSLSelectable) → bool

Check that a field is valid.

selection_set: SelectionSetNode
class gql.dsl.DSLFragment(name: str)

Bases: DSLSelectable, DSLFragmentSelector, DSLExecutable

DSLFragment represents a named GraphQL fragment for the DSL code.

is_valid_field(field: DSLSelectable) → bool

Check that a field is valid.

selection_set: SelectionSetNode
variable_definitions: DSLVariableDefinitions
__init__(name: str)

Initialize the DSLFragment.

Parameters:

name (str) – the name of the fragment

name: str
property ast_field: FragmentSpreadNode

ast_field property will generate a FragmentSpreadNode with the provided name.

Note: We need to ignore the type because of issue #4125 of mypy.

select(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias) → DSLFragment

Calling select method with corrected typing hints

on(type_condition: DSLType) → DSLFragment

Provides the GraphQL type of this fragment.

Parameters:

type_condition (DSLType) – the provided type

property executable_ast: FragmentDefinitionNode

Generates the ast for dsl_gql.

Raises:

AttributeError – if a type has not been provided