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:

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:

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)
abstractmethod 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: 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.

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

abstractmethod 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
abstractmethod is_valid_field(field: DSLSelectable) → bool
select(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias) → Any

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, 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: str | None
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.

abstractmethod 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

abstractmethod is_valid_field(field: DSLSelectable) → bool
select(*fields: DSLSelectable, **fields_with_alias: DSLSelectableWithAlias) → Any

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

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

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.

abstractmethod 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:
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'
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:
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'
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:
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'
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:
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: 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)
ast_variable_type: TypeNode | None
type: GraphQLScalarType | GraphQLEnumType | GraphQLInputObjectType | GraphQLWrappingType | None
to_ast_type(type_: GraphQLScalarType | GraphQLEnumType | GraphQLInputObjectType | GraphQLWrappingType) → TypeNode
set_type(type_: GraphQLScalarType | GraphQLEnumType | GraphQLInputObjectType | GraphQLWrappingType) → 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__()
variables: Dict[str, DSLVariable]
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

__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: 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:
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:
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: 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: 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:
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.

variable_definitions: DSLVariableDefinitions
selection_set: SelectionSetNode
__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:
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