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

    > - “__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)
  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:

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

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

  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:

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

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

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

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

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

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

  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:

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