py_gql.sdl#

Utilities to work with the GraphQL schema definition language (SDL).

class py_gql.sdl.SchemaDirective(args=None)[source]#

@directive implementation for use alongside py_gql.schema.build_schema().

You need to subclass this in order to define your own custom directives. All valid directive locations have a corresponding on_X method to implement from SchemaVisitor.

py_gql.sdl.apply_schema_directives(schema, schema_directives)[source]#

Apply SchemaDirective implementors to a given schema.

This assumes the provided schema was built from a GraphQL document and contains references to the parse node which contains the actual directive information.

Each directive will be instantiated with the arguments extracted from the parse nodes (which is why we need to provide a class here and not an instance of SchemaDirective).

Warning

Specified types (scalars, introspection) cannot be modified through schema directives.

Parameters
  • schema (Schema) – Schema to modify

  • schema_directives (Mapping[str, Type[SchemaDirective]]) – Dict of directive name to corredponsing SchemaDirective implementation. The directive must either be defined in the schema or the class implement the definition attribute.

Return type

Schema

py_gql.sdl.build_schema(document, *, ignore_extensions=False, additional_types=None, schema_directives=None)[source]#

Build an executable schema from a GraphQL document.

This includes:

  • Generating types from their definitions

  • Applying schema and type extensions

  • Applying schema directives

Parameters
  • document (Union[Document, str]) – SDL document

  • ignore_extensions (bool) – Whether to apply schema and type extensions or not.

  • additional_types (Optional[List[NamedType]]) – User supplied list of types Use this to specify some custom implementation for scalar, enums, etc. - In case of object types, interfaces, etc. the supplied type will override the extracted type without checking for compatibility. - Extension will be applied to these types. As a result, the resulting types may not be the same objects that were provided, so users should not rely on type identity.

  • schema_directives (Optional[Mapping[str, Type[SchemaDirective]]]) –

    Schema directive classes. Members must be subclasses of py_gql.schema.SchemaDirective and must either define a non-null definition attribute or the corresponding definition must be present in the document. See apply_schema_directives() for more details.

    Note

    Specified directives such as @deperecated do not need to be specified this way and are always processed internally to ensure compliance with the specification.

Return type

Schema

Returns

Executable schema

Raises
py_gql.sdl.extend_schema(schema, document, *, additional_types=None, strict=True, schema_directives=None)[source]#

Extend an existing Schema according to a GraphQL document (adding new types and directives + extending known types).

Warning

Specified types (scalars, introspection) cannot be replace or extended.

Parameters
  • schema (Schema) – Executable schema

  • document (Union[Document, str]) – SDL document

  • additional_types (Optional[List[NamedType]]) – User supplied list of types Use this to specify some custom implementation for scalar, enums, etc. - In case of object types, interfaces, etc. the supplied type will override the extracted type without checking for compatibility. - Extension will be applied to these types. As a result, the resulting types may not be the same objects that were provided, so users should not rely on type identity.

  • strict (bool) – Enable strict mode. In strict mode, unknown extension targets, overriding type and overriding the schema definition will raise an ExtensionError. Disable strict mode will silently ignore such errors.

  • schema_directives (Optional[Mapping[str, Type[SchemaDirective]]]) –

    Schema directive classes. Members must be subclasses of py_gql.schema.SchemaDirective and must either define a non-null definition attribute or the corresponding definition must be present in the document. See apply_schema_directives() for more details.

    Note

    Specified directives such as @deperecated do not need to be specified this way and are always processed internally to ensure compliance with the specification.

Returns

Executable schema

Return type

py_gql.schema.Schema

Raises

py_gql.exc.SDLError