py_gql.utilities#

Mixed bag of exposed utility functions and classes that are used internally and can be useful if you are building custom GraphQL tooling on top of this library.

py_gql.utilities.ast_node_from_value(value, input_type)[source]#

Infer an input value ast Node from a Python value given an input type.

Parameters
  • value (Any) – Any python value that can be transformed into a node

  • input_type (GraphQLType) – Input type used to disambiguate between node types.

Return type

Value

Returns

Inferred value node

Raises

ValueError – when coercion into a node fails

class py_gql.utilities.ASTSchemaPrinter(indent=4, include_descriptions=True, include_introspection=False, use_legacy_comment_descriptions=False, include_custom_directives=False)[source]#

Bases: object

Encode schema serialisation as a valid SDL document.

Parameters
  • indent (Union[str, int]) – Indent character or number of spaces

  • include_descriptions (bool) – If True include descriptions in the output

  • use_legacy_comment_descriptions (bool) – Control how descriptions are formatted. Set to True for the old standard (use comments) which will be compatible with most GraphQL parsers while the default settings is to use block strings and is part of the most recent specification.

  • include_introspection (bool) – If True, include introspection types in the output

  • include_custom_directives (Union[bool, Sequence[str]]) –

    Include custom directives collected when building the schema from an SDL document.

    By default this class will not print any directive included in the schema as there is no guarantee any external tooling consuming the SDL will undertand them. You can set this flag to True to include all of them or use a whitelist of directive names.

    This applies only to directive locations and not directive definitions as they could be relevant to clients regardless of their use in the schema.

print_description(definition, depth=0, first_in_block=True)[source]#

Format an object description according to current configuration.

Parameters
  • definitions – Described object

  • depth (int) – Level of indentation

  • first_in_block (bool) –

Return type

str

py_gql.utilities.coerce_argument_values(definition, node, variables=None)[source]#

Prepare a dict of argument values given a field or directive definition and a field or directive node.

Parameters
  • definition (Union[Field, Directive]) – Field or Directive definition from which to extract argument definitions.

  • node (Union[Field, Directive]) – Parse node

  • variables (Optional[Mapping[str, Any]]) – Coerced variable values

Return type

Dict[str, Any]

Returns

Coerced arguments

:raises CoercionError: if any argument value fails to coerce, required argument is missing, etc.

py_gql.utilities.coerce_value(value, type_, node=None, path=None)[source]#

Coerce a Python value given a GraphQL Type.

Parameters
  • value (Any) – Value to coerce

  • type_ (GraphQLType) – Expected type

  • node (Optional[Node]) – Relevant node

  • path (Optional[List[Union[int, str]]]) – Path into the value for nested values (lists, objects). Should only be set on recursive calls.

Return type

Any

Returns

The coerced value

:raises CoercionError: if coercion fails

py_gql.utilities.coerce_variable_values(schema, operation, variables)[source]#

Prepare an object map of variable values of the correct type based on the provided operation definition and arbitrary JSON input. If the input cannot be parsed to match the variable definitions, an ExecutionError will be thrown. The returned value is a plain dict since it is exposed to user code.

Extra variables are ignored and filtered out.

Parameters
  • schema (Schema) – GraphQL Schema to consider

  • operation (OperationDefinition) – Operation definition containing the variable definitions

  • variables (Mapping[str, Any]) – Provided raw variables

Return type

Dict[str, Any]

Returns

Coerced variables

:raises VariablesCoercionError: if any variable cannot be coerced.

py_gql.utilities.directive_arguments(definition, node, variables=None)[source]#

Extract directive argument given a field or directive node and a directive definition.

Parameters
Return type

Optional[Dict[str, Any]]

Returns

Coerced directive arguments, None if the directive is not present on the node.

:raises CoercionError: if any directive argument value fails to coerce, required argument is missing, etc.

py_gql.utilities.introspection_query(description=True)[source]#

Return a generic introspection query to be used by GraphQL clients.

Parameters

description (bool) – If True the query will require descriptions to be included.

Return type

str

Returns

Canonical intropsection query

class py_gql.utilities.TypeInfoVisitor(schema)[source]#

Bases: py_gql.lang.visitor.DispatchingVisitor

Utility visitor that recurisvely track the current types and field definitions while traversing a Document.

All tracked types are considered with regards to the provided schema, however unknown types and other unexpected errors will be downgraded to null values in order to not crash the traversal. This leaves the consumer responsible to handle such cases.

Warning

When using this alongside other visitors (such as when using py_gql.lang.visitor.ParallelVisitor), this visitor must to be the first one to visit the nodes in order for the information provided donwstream to be accurate.

Parameters

schema (py_gql.schema.Schema) – Reference schema to extract types from

type#

Current type if applicable

Type

Optional[py_gql.schema.ObjectType]

parent_typ#

Current type if applicable_stack, 1)

Type

Optional[py_gql.schema.ObjectType]

input_typ#

Current input type if applicable (when visiting arguments)

Type

Optional[py_gql.schema.InputObjectType]

parent_input_typ#

Current parent input type if applicable (when visiting input objects)

Type

Optional[py_gql.schema.InputObjectType]

fiel#

Current field definition if applicable (when visiting object)

Type

Optional[py_gql.schema.Field]

input_value_def#

Current input value definition (e.g. arg def, input field) if applicable

Type

Optional[Union[py_gql.schema.Argument, py_gql.schema.InputField]]

py_gql.utilities.untyped_value_from_ast(node, variables=None)[source]#

Convert an ast value node into a valid python value without type validation.

Warning

No validation is done with regard to the variable values which are assumed to have been validated before.

Parameters
Returns

Extracted value

Return type

any

:raises :py:class:TypeError: when node is not a value node :raises UnknownVariable: if a variable is required and doesn’t exist

py_gql.utilities.value_from_ast(node, type_, variables=None)[source]#

Convert an ast value node into a valid python value while validating against a given type.

Warning

No validation is done with regard to the variable values which are assumed to have been validated before.

Parameters
Return type

Any

Returns

Extracted value

Raises

TypeError – when node is not a value node

Raises

~py_gql.exc.InvalidValue: if the value cannot be converted

Raises

~py_gql.exc.UnknownVariable: if a variable is required and doesn’t exist