gql.dsl¶

gql.dsl.ast_from_serialized_value_untyped(serialized: Any) → Optional[ValueNode]¶

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_: Union[GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType, GraphQLWrappingType]) → Optional[ValueNode]¶

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

*operations (DSLQuery, DSLMutation, DSLSubscription, DSLFragment) – the GraphQL operations and fragments
**operations_with_name (DSLQuery, DSLMutation, DSLSubscription) – the GraphQL operations with an operation name

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

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

Raises

TypeError – if an argument is not an instance of DSLSelectable
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: Optional[str]¶

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

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

Raises

TypeError – if an argument is not an instance of DSLSelectable
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

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

Raises

TypeError – if an argument is not an instance of DSLSelectable
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

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

Raises

TypeError – if an argument is not an instance of DSLSelectable
GraphQLError – if an argument is not a valid field

variable_definitions: DSLVariableDefinitions¶

name: Optional[str]¶

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

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

Raises

TypeError – if an argument is not an instance of DSLSelectable
GraphQLError – if an argument is not a valid field

variable_definitions: DSLVariableDefinitions¶

name: Optional[str]¶

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

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

Raises

TypeError – if an argument is not an instance of DSLSelectable
GraphQLError – if an argument is not a valid field

variable_definitions: DSLVariableDefinitions¶

name: Optional[str]¶

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

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

Raises

TypeError – if an argument is not an instance of DSLSelectable
GraphQLError – if an argument is not a valid field

variable_definitions: DSLVariableDefinitions¶

name: Optional[str]¶

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_: Union[GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType, GraphQLWrappingType]) → TypeNode¶

set_type(type_: Union[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: Union[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: Union[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: Union[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

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

Raises

TypeError – if an argument is not an instance of DSLSelectable
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

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

Raises

TypeError – if an argument is not an instance of DSLSelectable
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: Union[GraphQLObjectType, GraphQLInterfaceType], field: GraphQLField, dsl_type: Optional[DSLType] = 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: Union[GraphQLObjectType, GraphQLInterfaceType], field: GraphQLField, dsl_type: Optional[DSLType] = 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

*fields (DSLSelectable (DSLField, DSLFragment or DSLInlineFragment)) – new children fields
**fields_with_alias (DSLField) – new children fields with alias as key

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