py_gql.sdl#

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

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[Sequence[Type[ForwardRef]]]) –

    Schema directive classes. Members must be subclasses of py_gql.schema.SchemaDirective

    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

This adds new types and directives as well as extends 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[Sequence[Type[ForwardRef]]]) –

    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:

Schema

Raises:

ExtensionError – If applying an extension fails.

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.

The definition attributes defines how the definition will be found at runtime. A Directive object defines the directive inline, while a string delegates to the schema at build time by name, in which case the directive must be part of the schema it’s applied to.

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

Apply SchemaDirective implementers 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 (Sequence[Type[SchemaDirective]]) – List of schema directives (~py_gql.schema.SchemaDirective). Each directive must implement the definition attribute.
Return type:

Schema

Returns:

Modified schema.

class py_gql.sdl.ASTSchemaPrinter(*, indent=4, include_descriptions=True, include_introspection=False, include_custom_schema_directives=False)[source]#

Encode schema serialization 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
  • include_introspection (bool) – If True, include introspection types in the output
  • include_custom_schema_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 custom schema directive included in the schema as there is no guarantee external tooling consuming the resulting schema file will understand 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.
include_custom_schema_directive(directive_name)[source]#
Return type:bool
include_custom_schema_directives#
include_descriptions#
include_introspection#
indent#
print_arguments(args, depth=0)[source]#
Return type:str
print_deprecated(field_or_enum_value)[source]#
Return type:str
print_description(definition, depth=0, first_in_block=True)[source]#
Return type:str
print_directive_definition(directive)[source]#
Return type:str
print_directives(definition)[source]#
Return type:str
print_enum_type(type_)[source]#
Return type:str
print_fields(type_)[source]#
Return type:str
print_input_object_type(type_)[source]#
Return type:str
print_input_value(arg_or_inut_field)[source]#
Return type:str
print_interface_type(type_)[source]#
Return type:str
print_object_type(type_)[source]#
Return type:str
print_scalar_type(type_)[source]#
Return type:str
print_schema_definition(schema)[source]#
Return type:str
print_type(type_)[source]#
Return type:str
print_union_type(type_)[source]#
Return type:str