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, GraphQLList, GraphQLNonNull[Union[GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList]]]) → 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: graphql.error.GraphQLError – instead of returning None if we receive an Undefined of if we receive a Null value for a Non-Null type.

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

__call__(shortcut: Literal['__typename', '__schema', '__type']) → DSLMetaField¶

__call__(shortcut: Literal['...']) → DSLInlineFragment

__call__(shortcut: Any) → DSLDirective

Factory method for creating DSL objects from a shortcut string.

The shortcut determines which DSL object is created:

“__typename”, “__schema”, “__type” -> DSLMetaField

“…” -> DSLInlineFragment

“@<name>” -> DSLDirective

Parameters: shortcut (str) – The shortcut string identifying the DSL object.
Returns: A DSL object corresponding to the given shortcut.
Return type: DSLMetaField | DSLInlineFragment | DSLDirective
Raises: ValueError – If the shortcut is not recognized.

__getattr__(name: str) → DSLType¶

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

Returns: DSLType instance
Raises: AttributeError – if the name is not valid

__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.DSLDirective(name: str, dsl_schema: DSLSchema)¶

Bases: object

The DSLDirective represents a GraphQL directive for the DSL code.

Directives provide a way to describe alternate runtime execution and type validation behavior in a GraphQL document.

__init__(name: str, dsl_schema: DSLSchema)¶

Initialize the DSLDirective with the given name and arguments.

Parameters

name – the name of the directive
dsl_schema – DSLSchema for directive validation and definition lookup

Raises

graphql.error.GraphQLError – if directive not found or not executable

property name: str¶: Get the directive name.

args(**kwargs: Any) → Self¶

Set the arguments of a directive

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("@someDirective").args(value="foo") is equivalent to: ds("@someDirective")(value="foo")

Parameters

**kwargs – the arguments (keyword=value)

Returns

itself

Raises

AttributeError – if arguments already set for this directive
graphql.error.GraphQLError – if argument doesn’t exist in directive definition

class gql.dsl.DSLDirectable(*args, **kwargs)¶

Bases: ABC

Mixin class for DSL elements that can have directives.

Provides the directives() method for adding GraphQL directives to DSL elements. Classes that need immediate AST updates should override the directives() method.

__init__(*args, **kwargs)¶

abstract is_valid_directive(directive: DSLDirective) → bool¶

Check if a directive is valid for this DSL element.

Parameters: directive – The DSLDirective to validate
Returns: True if the directive can be used at this location

directives(*directives: DSLDirective) → Self¶

Add directives to this DSL element.

Parameters

*directives – DSLDirective instances to add

Returns

itself

Raises

graphql.error.GraphQLError – if directive location is invalid
TypeError – if argument is not a DSLDirective

Usage:

# Using new factory method
element.directives(ds("@include")(**{"if": var.show}))
element.directives(ds("@skip")(**{"if": var.hide}))

property directives_ast: Tuple[DirectiveNode, ...]¶: Get AST directive nodes for this element.

class gql.dsl.DSLSelectable(*args, **kwargs)¶

Bases: DSLDirectable

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]¶

__init__(*args, **kwargs)¶

directives(*directives: DSLDirective) → Self¶

Add directives to this DSL element.

Parameters

*directives – DSLDirective instances to add

Returns

itself

Raises

graphql.error.GraphQLError – if directive location is invalid
TypeError – if argument is not a DSLDirective

Usage:

# Using new factory method
element.directives(ds("@include")(**{"if": var.show}))
element.directives(ds("@skip")(**{"if": var.hide}))

property directives_ast: Tuple[DirectiveNode, ...]¶: Get AST directive nodes for this element.

abstract is_valid_directive(directive: DSLDirective) → bool¶

Check if a directive is valid for this DSL element.

Parameters: directive – The DSLDirective to validate
Returns: True if the directive can be used at this location

class gql.dsl.DSLSelectableWithAlias(*args, **kwargs)¶

Bases: DSLSelectable

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

ast_field: FieldNode¶

alias(alias: str) → Self¶

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

__init__(*args, **kwargs)¶

directives(*directives: DSLDirective) → Self¶

Add directives to this DSL element.

Parameters

*directives – DSLDirective instances to add

Returns

itself

Raises

graphql.error.GraphQLError – if directive location is invalid
TypeError – if argument is not a DSLDirective

Usage:

# Using new factory method
element.directives(ds("@include")(**{"if": var.show}))
element.directives(ds("@skip")(**{"if": var.hide}))

property directives_ast: Tuple[DirectiveNode, ...]¶: Get AST directive nodes for this element.

abstract is_valid_directive(directive: DSLDirective) → bool¶

Check if a directive is valid for this DSL element.

Parameters: directive – The DSLDirective to validate
Returns: True if the directive can be used at this location

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) → Any¶

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
graphql.error.GraphQLError – if an argument is not a valid field

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

Bases: DSLSelector, DSLDirectable

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¶

directives(*directives: DSLDirective) → Self¶

Add directives to this DSL element.

Parameters

*directives – DSLDirective instances to add

Returns

itself

Raises

graphql.error.GraphQLError – if directive location is invalid
TypeError – if argument is not a DSLDirective

Usage:

# Using new factory method
element.directives(ds("@include")(**{"if": var.show}))
element.directives(ds("@skip")(**{"if": var.hide}))

property directives_ast: Tuple[DirectiveNode, ...]¶: Get AST directive nodes for this element.

abstract is_valid_directive(directive: DSLDirective) → bool¶

Check if a directive is valid for this DSL element.

Parameters: directive – The DSLDirective to validate
Returns: True if the directive can be used at this location

abstract is_valid_field(field: DSLSelectable) → bool¶

select(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias) → Any¶

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
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) → Any¶

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
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

directives(*directives: DSLDirective) → Self¶

Add directives to this DSL element.

Parameters

*directives – DSLDirective instances to add

Returns

itself

Raises

graphql.error.GraphQLError – if directive location is invalid
TypeError – if argument is not a DSLDirective

Usage:

# Using new factory method
element.directives(ds("@include")(**{"if": var.show}))
element.directives(ds("@skip")(**{"if": var.hide}))

property directives_ast: Tuple[DirectiveNode, ...]¶: Get AST directive nodes for this element.

abstract is_valid_directive(directive: DSLDirective) → bool¶

Check if a directive is valid for this DSL element.

Parameters: directive – The DSLDirective to validate
Returns: True if the directive can be used at this location

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) → Any¶

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
graphql.error.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'¶

is_valid_directive(directive: DSLDirective) → bool¶: Check if directive is valid for Query operations.

__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

directives(*directives: DSLDirective) → Self¶

Add directives to this DSL element.

Parameters

*directives – DSLDirective instances to add

Returns

itself

Raises

graphql.error.GraphQLError – if directive location is invalid
TypeError – if argument is not a DSLDirective

Usage:

# Using new factory method
element.directives(ds("@include")(**{"if": var.show}))
element.directives(ds("@skip")(**{"if": var.hide}))

property directives_ast: Tuple[DirectiveNode, ...]¶: Get AST directive nodes for this element.

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) → Any¶

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
graphql.error.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'¶

is_valid_directive(directive: DSLDirective) → bool¶: Check if directive is valid for Mutation operations.

__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

directives(*directives: DSLDirective) → Self¶

Add directives to this DSL element.

Parameters

*directives – DSLDirective instances to add

Returns

itself

Raises

graphql.error.GraphQLError – if directive location is invalid
TypeError – if argument is not a DSLDirective

Usage:

# Using new factory method
element.directives(ds("@include")(**{"if": var.show}))
element.directives(ds("@skip")(**{"if": var.hide}))

property directives_ast: Tuple[DirectiveNode, ...]¶: Get AST directive nodes for this element.

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) → Any¶

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
graphql.error.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'¶

is_valid_directive(directive: DSLDirective) → bool¶: Check if directive is valid for Subscription operations.

__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

directives(*directives: DSLDirective) → Self¶

Add directives to this DSL element.

Parameters

*directives – DSLDirective instances to add

Returns

itself

Raises

graphql.error.GraphQLError – if directive location is invalid
TypeError – if argument is not a DSLDirective

Usage:

# Using new factory method
element.directives(ds("@include")(**{"if": var.show}))
element.directives(ds("@skip")(**{"if": var.hide}))

property directives_ast: Tuple[DirectiveNode, ...]¶: Get AST directive nodes for this element.

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) → Any¶

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
graphql.error.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: DSLDirectable

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, GraphQLList, GraphQLNonNull[Union[GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList]]]) → TypeNode¶

set_type(type_: Union[GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList, GraphQLNonNull[Union[GraphQLScalarType, GraphQLEnumType, GraphQLInputObjectType, GraphQLList]]]) → Self¶

default(default_value: Any) → Self¶

is_valid_directive(directive: DSLDirective) → bool¶: Check if directive is valid for Variable definitions.

directives(*directives: DSLDirective) → Self¶

Add directives to this DSL element.

Parameters

*directives – DSLDirective instances to add

Returns

itself

Raises

graphql.error.GraphQLError – if directive location is invalid
TypeError – if argument is not a DSLDirective

Usage:

# Using new factory method
element.directives(ds("@include")(**{"if": var.show}))
element.directives(ds("@skip")(**{"if": var.hide}))

property directives_ast: Tuple[DirectiveNode, ...]¶: Get AST directive nodes for this element.

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.

__getattr__(name: str) → DSLVariable¶

Attributes of the DSLVariableDefinitions class are generated automatically with this dunder method in order to generate instances of DSLVariable

Returns: DSLVariable instance

__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

__getattr__(name: str) → DSLField¶

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

Returns: DSLField instance
Raises: AttributeError – if the field name does not exist in the type

__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.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) → Any¶

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
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) → Any¶

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
graphql.error.GraphQLError – if an argument is not a valid field

selection_set: SelectionSetNode¶

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: Any) → Self¶

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) → Self¶: Calling select method with corrected typing hints

directives(*directives: DSLDirective) → Self¶: Add directives to this field.

is_valid_directive(directive: DSLDirective) → bool¶: Check if directive is valid for Field locations.

alias(alias: str) → Self¶

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

property directives_ast: Tuple[DirectiveNode, ...]¶: Get AST directive nodes for this element.

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

is_valid_directive(directive: DSLDirective) → bool¶: Check if directive is valid for MetaField locations (same as Field).

alias(alias: str) → Self¶

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: Any) → Self¶

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.

directives(*directives: DSLDirective) → Self¶: Add directives to this field.

property directives_ast: Tuple[DirectiveNode, ...]¶: Get AST directive nodes for this element.

is_valid_field(field: DSLSelectable) → bool¶: Check that a field is valid.

select(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias) → Self¶: 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) → Self¶: Calling select method with corrected typing hints

on(type_condition: DSLType) → Self¶: Provides the GraphQL type of this inline fragment.

directives(*directives: DSLDirective) → Self¶

Add directives to this inline fragment.

Inline fragments support all directive types through auto-validation.

is_valid_directive(directive: DSLDirective) → bool¶: Check if directive is valid for Inline Fragment locations.

property directives_ast: Tuple[DirectiveNode, ...]¶: Get AST directive nodes for this element.

is_valid_field(field: DSLSelectable) → bool¶: Check that a field is valid.

selection_set: SelectionSetNode¶

class gql.dsl.DSLFragmentSpread(fragment: DSLFragment)¶

Bases: DSLSelectable

Represents a fragment spread (usage) with its own directives.

This class is created by calling .spread() on a DSLFragment and allows adding directives specific to the FRAGMENT_SPREAD location.

__init__(fragment: DSLFragment)¶

Initialize a fragment spread from a fragment definition.

Parameters: fragment – The DSLFragment to create a spread from

ast_field: FragmentSpreadNode¶

directives(*directives: DSLDirective) → Self¶

Add directives to this fragment spread.

Fragment spreads support all directive types through auto-validation.

is_valid_directive(directive: DSLDirective) → bool¶: Check if directive is valid for Fragment Spread locations.

property directives_ast: Tuple[DirectiveNode, ...]¶: Get AST directive nodes for this element.

class gql.dsl.DSLFragment(name: str)¶

Bases: DSLSelectable, DSLFragmentSelector, DSLExecutable

DSLFragment represents a named GraphQL fragment for the DSL code.

directives(*directives: DSLDirective) → Self¶

Add directives to this DSL element.

Parameters

*directives – DSLDirective instances to add

Returns

itself

Raises

graphql.error.GraphQLError – if directive location is invalid
TypeError – if argument is not a DSLDirective

Usage:

# Using new factory method
element.directives(ds("@include")(**{"if": var.show}))
element.directives(ds("@skip")(**{"if": var.hide}))

property directives_ast: Tuple[DirectiveNode, ...]¶: Get AST directive nodes for this element.

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

ast_field: FragmentSpreadNode¶

spread() → DSLFragmentSpread¶

Create a fragment spread that can have its own directives.

This allows adding directives specific to the FRAGMENT_SPREAD location, separate from directives on the fragment definition itself.

Returns: DSLFragmentSpread instance for this fragment

select(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias) → Self¶: Calling select method with corrected typing hints

on(type_condition: DSLType) → Self¶

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

is_valid_directive(directive: DSLDirective) → bool¶: Check if directive is valid for Fragment Definition locations.

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

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 GraphQLRequest 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