From a40730aff99d1e0b288005bdc95d2346da0d41cc Mon Sep 17 00:00:00 2001
From: Phil Aquilina <philaquilina@gmail.com>
Date: Fri, 7 Dec 2018 15:35:25 -0800
Subject: [PATCH 1/2] Fix indent function
The indent function wasn't actually indenting. Add the indent to
the function and fix up the one call site.
---
graphql/language/printer.py | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/graphql/language/printer.py b/graphql/language/printer.py
index d2f27ef8..676af0a8 100644
--- a/graphql/language/printer.py
+++ b/graphql/language/printer.py
@@ -301,7 +301,7 @@ def block(_list):
# type: (List[str]) -> str
"""Given a list, print each item on its own line, wrapped in an indented "{ }" block."""
if _list:
- return indent("{\n" + join(_list, "\n")) + "\n}"
+ return "{\n" + indent(join(_list, "\n")) + "\n}"
return "{}"
@@ -315,5 +315,5 @@ def wrap(start, maybe_str, end=""):
def indent(maybe_str):
# type: (Optional[str]) -> str
if maybe_str:
- return maybe_str.replace("\n", "\n ")
+ return ' ' + maybe_str.replace("\n", "\n ")
return ""
From 3338aaae8dfa5bb96f6dd8d1368c2cdf3d7ddce7 Mon Sep 17 00:00:00 2001
From: Phil Aquilina <philaquilina@gmail.com>
Date: Thu, 29 Nov 2018 15:52:36 -0800
Subject: [PATCH 2/2] Add description to schema parser and printer
Descriptions are now part of the [graphql spec](https://facebook.github.io/graphql/June2018/#sec-Descriptions).
This commit brings graphql-core inline with the spec.
---
graphql/language/ast.py | 48 ++++--
graphql/language/lexer.py | 96 +++++++++++-
graphql/language/parser.py | 53 ++++++-
graphql/language/printer.py | 73 ++++++---
graphql/language/tests/fixtures.py | 31 +++-
.../language/tests/test_block_string_value.py | 108 +++++++++++++
graphql/language/tests/test_schema_printer.py | 33 +++-
graphql/language/visitor_meta.py | 20 +--
graphql/type/directives.py | 2 +-
graphql/utils/build_ast_schema.py | 22 ++-
graphql/utils/schema_printer.py | 142 +++++++++++++++---
graphql/utils/tests/test_build_ast_schema.py | 31 ++++
graphql/utils/tests/test_schema_printer.py | 141 ++++++++++++++++-
13 files changed, 715 insertions(+), 85 deletions(-)
create mode 100644 graphql/language/tests/test_block_string_value.py
diff --git a/graphql/language/ast.py b/graphql/language/ast.py
index f7f407ea..cd616313 100644
--- a/graphql/language/ast.py
+++ b/graphql/language/ast.py
@@ -543,13 +543,14 @@ def __hash__(self):
class StringValue(Value):
- __slots__ = ("loc", "value")
+ __slots__ = ("loc", "value", "is_block_string")
_fields = ("value",)
- def __init__(self, value, loc=None):
+ def __init__(self, value, loc=None, is_block_string=False):
# type: (str, Optional[Loc]) -> None
self.loc = loc
self.value = value
+ self.is_block_string = is_block_string
def __eq__(self, other):
# type: (Any) -> bool
@@ -989,7 +990,7 @@ def __hash__(self):
class ObjectTypeDefinition(TypeDefinition):
- __slots__ = ("loc", "name", "interfaces", "directives", "fields")
+ __slots__ = ("loc", "name", "interfaces", "directives", "fields", "description")
_fields = ("name", "interfaces", "fields")
def __init__(
@@ -999,6 +1000,7 @@ def __init__(
interfaces=None, # type: Optional[List[NamedType]]
loc=None, # type: Optional[Loc]
directives=None, # type: Optional[List[Directive]]
+ description=None, # type: Optional[String]
):
# type: (...) -> None
self.loc = loc
@@ -1006,12 +1008,12 @@ def __init__(
self.interfaces = interfaces
self.fields = fields
self.directives = directives
+ self.description = description
def __eq__(self, other):
# type: (Any) -> bool
return self is other or (
- isinstance(other, ObjectTypeDefinition)
- and
+ isinstance(other, ObjectTypeDefinition) and
# self.loc == other.loc and
self.name == other.name
and self.interfaces == other.interfaces
@@ -1042,7 +1044,7 @@ def __hash__(self):
class FieldDefinition(Node):
- __slots__ = ("loc", "name", "arguments", "type", "directives")
+ __slots__ = ("loc", "name", "arguments", "type", "directives", "description")
_fields = ("name", "arguments", "type")
def __init__(
@@ -1052,6 +1054,7 @@ def __init__(
type, # type: Union[NamedType, NonNullType, ListType]
loc=None, # type: Optional[Loc]
directives=None, # type: Optional[List]
+ description=None, # type: Optional[String]
):
# type: (...) -> None
self.loc = loc
@@ -1059,6 +1062,7 @@ def __init__(
self.arguments = arguments
self.type = type
self.directives = directives
+ self.description = description
def __eq__(self, other):
# type: (Any) -> bool
@@ -1094,7 +1098,7 @@ def __hash__(self):
class InputValueDefinition(Node):
- __slots__ = ("loc", "name", "type", "default_value", "directives")
+ __slots__ = ("loc", "name", "type", "default_value", "directives", "description")
_fields = ("name", "type", "default_value")
def __init__(
@@ -1104,6 +1108,7 @@ def __init__(
default_value=None, # type: Any
loc=None, # type: Optional[Loc]
directives=None, # type: Optional[List]
+ description=None, # type: Optional[String]
):
# type: (...) -> None
self.loc = loc
@@ -1111,6 +1116,7 @@ def __init__(
self.type = type
self.default_value = default_value
self.directives = directives
+ self.description = description
def __eq__(self, other):
# type: (Any) -> bool
@@ -1147,7 +1153,7 @@ def __hash__(self):
class InterfaceTypeDefinition(TypeDefinition):
- __slots__ = ("loc", "name", "fields", "directives")
+ __slots__ = ("loc", "name", "fields", "directives", "description")
_fields = ("name", "fields")
def __init__(
@@ -1156,12 +1162,14 @@ def __init__(
fields, # type: List[FieldDefinition]
loc=None, # type: Optional[Loc]
directives=None, # type: Optional[List[Directive]]
+ description=None, # type: Optional[String]
):
# type: (...) -> None
self.loc = loc
self.name = name
self.fields = fields
self.directives = directives
+ self.description = description
def __eq__(self, other):
# type: (Any) -> bool
@@ -1194,7 +1202,7 @@ def __hash__(self):
class UnionTypeDefinition(TypeDefinition):
- __slots__ = ("loc", "name", "types", "directives")
+ __slots__ = ("loc", "name", "types", "directives", "description")
_fields = ("name", "types")
def __init__(
@@ -1203,12 +1211,14 @@ def __init__(
types, # type: List[NamedType]
loc=None, # type: Optional[Loc]
directives=None, # type: Optional[List[Directive]]
+ description=None, # type: Optional[String]
):
# type: (...) -> None
self.loc = loc
self.name = name
self.types = types
self.directives = directives
+ self.description = description
def __eq__(self, other):
# type: (Any) -> bool
@@ -1241,7 +1251,7 @@ def __hash__(self):
class ScalarTypeDefinition(TypeDefinition):
- __slots__ = ("loc", "name", "directives")
+ __slots__ = ("loc", "name", "directives", "description")
_fields = ("name",)
def __init__(
@@ -1249,11 +1259,13 @@ def __init__(
name, # type: Name
loc=None, # type: Optional[Loc]
directives=None, # type: Optional[List[Directive]]
+ description=None, # type: Optional[String]
):
# type: (...) -> None
self.loc = loc
self.name = name
self.directives = directives
+ self.description = description
def __eq__(self, other):
# type: (Any) -> bool
@@ -1284,7 +1296,7 @@ def __hash__(self):
class EnumTypeDefinition(TypeDefinition):
- __slots__ = ("loc", "name", "values", "directives")
+ __slots__ = ("loc", "name", "values", "directives", "description")
_fields = ("name", "values")
def __init__(
@@ -1293,12 +1305,14 @@ def __init__(
values, # type: List[EnumValueDefinition]
loc=None, # type: Optional[Loc]
directives=None, # type: Optional[List[Directive]]
+ description=None, # type: Optional[String]
):
# type: (...) -> None
self.loc = loc
self.name = name
self.values = values
self.directives = directives
+ self.description = description
def __eq__(self, other):
# type: (Any) -> bool
@@ -1331,7 +1345,7 @@ def __hash__(self):
class EnumValueDefinition(Node):
- __slots__ = ("loc", "name", "directives")
+ __slots__ = ("loc", "name", "directives", "description")
_fields = ("name",)
def __init__(
@@ -1339,11 +1353,13 @@ def __init__(
name, # type: Name
loc=None, # type: Optional[Loc]
directives=None, # type: Optional[List[Directive]]
+ description=None, # type: Optional[String]
):
# type: (...) -> None
self.loc = loc
self.name = name
self.directives = directives
+ self.description = description
def __eq__(self, other):
# type: (Any) -> bool
@@ -1374,7 +1390,7 @@ def __hash__(self):
class InputObjectTypeDefinition(TypeDefinition):
- __slots__ = ("loc", "name", "fields", "directives")
+ __slots__ = ("loc", "name", "fields", "directives", "description")
_fields = ("name", "fields")
def __init__(
@@ -1383,12 +1399,14 @@ def __init__(
fields, # type: List[InputValueDefinition]
loc=None, # type: Optional[Loc]
directives=None, # type: Optional[List[Directive]]
+ description=None, # type: Optional[String]
):
# type: (...) -> None
self.loc = loc
self.name = name
self.fields = fields
self.directives = directives
+ self.description = description
def __eq__(self, other):
# type: (Any) -> bool
@@ -1454,7 +1472,7 @@ def __hash__(self):
class DirectiveDefinition(TypeSystemDefinition):
- __slots__ = ("loc", "name", "arguments", "locations")
+ __slots__ = ("loc", "name", "arguments", "locations", "description")
_fields = ("name", "locations")
def __init__(
@@ -1463,12 +1481,14 @@ def __init__(
locations, # type: List[Name]
arguments=None, # type: Optional[List[InputValueDefinition]]
loc=None, # type: Optional[Loc]
+ description=None, # type: Optional[String]
):
# type: (...) -> None
self.name = name
self.locations = locations
self.loc = loc
self.arguments = arguments
+ self.description = description
def __eq__(self, other):
# type: (Any) -> bool
diff --git a/graphql/language/lexer.py b/graphql/language/lexer.py
index a60bc6e2..b1451dbc 100644
--- a/graphql/language/lexer.py
+++ b/graphql/language/lexer.py
@@ -1,3 +1,4 @@
+import re
import json
from six import unichr
@@ -55,6 +56,10 @@ def next_token(self, reset_position=None):
self.prev_position = token.end
return token
+ def look_ahead(self):
+ skip_token = read_token(self.source, self.prev_position)
+ return read_token(self.source, skip_token.start)
+
class TokenKind(object):
EOF = 1
@@ -76,6 +81,7 @@ class TokenKind(object):
INT = 17
FLOAT = 18
STRING = 19
+ BLOCK_STRING = 20
def get_token_desc(token):
@@ -111,6 +117,7 @@ def get_token_kind_desc(kind):
TokenKind.INT: "Int",
TokenKind.FLOAT: "Float",
TokenKind.STRING: "String",
+ TokenKind.BLOCK_STRING: "Block string",
}
@@ -155,7 +162,7 @@ def read_token(source, from_position):
This skips over whitespace and comments until it finds the next lexable
token, then lexes punctuators immediately or calls the appropriate
- helper fucntion for more complicated tokens."""
+ helper function for more complicated tokens."""
body = source.body
body_length = len(body)
@@ -191,6 +198,11 @@ def read_token(source, from_position):
return read_number(source, position, code)
elif code == 34: # "
+ if (
+ char_code_at(body, position + 1) == 34 and
+ char_code_at(body, position + 2) == 34
+ ):
+ return read_block_string(source, position)
return read_string(source, position)
raise GraphQLSyntaxError(
@@ -417,6 +429,55 @@ def read_string(source, start):
return Token(TokenKind.STRING, start, position + 1, u"".join(value))
+def read_block_string(source, from_position):
+ body = source.body
+ position = from_position + 3
+
+ chunk_start = position
+ code = 0 # type: Optional[int]
+ value = [] # type: List[str]
+
+ while position < len(body) and code is not None:
+ code = char_code_at(body, position)
+
+ # Closing triple quote
+ if (
+ code == 34 and
+ char_code_at(body, position + 1) == 34 and
+ char_code_at(body, position + 2) == 34
+ ):
+ value.append(body[chunk_start:position])
+ return Token(
+ TokenKind.BLOCK_STRING,
+ from_position,
+ position + 3,
+ block_string_value(u"".join(value)),
+ )
+
+ if code < 0x0020 and code not in (0x0009, 0x000a, 0x000d):
+ raise GraphQLSyntaxError(
+ source,
+ position,
+ "Invalid character within str: %s." % print_char_code(code),
+ )
+
+ # Escaped triple quote (\""")
+ if (
+ code == 92 and
+ char_code_at(body, position + 1) == 34 and
+ char_code_at(body, position + 2) == 34 and
+ char_code_at(body, position + 3) == 34
+ ):
+ value.append(body[chunk_start, position] + '"""')
+ position += 4
+ chunk_start = position
+ else:
+ position += 1
+
+ raise GraphQLSyntaxError(source, position, "Unterminated string")
+
+
+
def uni_char_code(a, b, c, d):
# type: (int, int, int, int) -> int
"""Converts four hexidecimal chars to the integer that the
@@ -473,3 +534,36 @@ def read_name(source, position):
end += 1
return Token(TokenKind.NAME, position, end, body[position:end])
+
+
+
+SPLIT_RE = re.compile("\r\n|[\n\r]")
+WHITESPACE_RE = re.compile("(^[ |\t]*)")
+EMPTY_LINE_RE = re.compile("^\s*$")
+
+def block_string_value(value):
+ lines = SPLIT_RE.split(value)
+
+ common_indent = None
+ for line in lines[1:]:
+ match = WHITESPACE_RE.match(line)
+ indent = len(match.groups()[0])
+
+ if indent < len(line) and (common_indent is None or indent < common_indent):
+ common_indent = indent
+ if common_indent == 0:
+ break
+
+ if common_indent:
+ new_lines = [lines[0]]
+ for line in lines[1:]:
+ new_lines.append(line[common_indent:])
+ lines = new_lines
+
+ while len(lines) and EMPTY_LINE_RE.match(lines[0]):
+ lines = lines[1:]
+
+ while len(lines) and EMPTY_LINE_RE.match(lines[-1]):
+ lines = lines[:-1]
+
+ return '\n'.join(lines)
diff --git a/graphql/language/parser.py b/graphql/language/parser.py
index 8b658e50..406abef5 100644
--- a/graphql/language/parser.py
+++ b/graphql/language/parser.py
@@ -140,6 +140,10 @@ def peek(parser, kind):
return parser.token.kind == kind
+def peek_description(parser):
+ return peek(parser, TokenKind.STRING) or peek(parser, TokenKind.BLOCK_STRING)
+
+
def skip(parser, kind):
# type: (Parser, int) -> bool
"""If the next token is of the given kind, return true after advancing
@@ -254,6 +258,9 @@ def parse_definition(parser):
if peek(parser, TokenKind.BRACE_L):
return parse_operation_definition(parser)
+ if peek_description(parser):
+ return parse_type_system_definition(parser)
+
if peek(parser, TokenKind.NAME):
name = parser.token.value
@@ -277,6 +284,11 @@ def parse_definition(parser):
raise unexpected(parser)
+def parse_description(parser):
+ if peek_description(parser):
+ return parse_value_literal(parser, False)
+
+
# Implements the parsing rules in the Operations section.
def parse_operation_definition(parser):
# type: (Parser) -> OperationDefinition
@@ -494,6 +506,14 @@ def parse_value_literal(parser, is_const):
value=token.value, loc=loc(parser, token.start)
)
+ elif token.kind == TokenKind.BLOCK_STRING:
+ advance(parser)
+ return ast.StringValue( # type: ignore
+ value=token.value,
+ loc=loc(parser, token.start),
+ is_block_string=True,
+ )
+
elif token.kind == TokenKind.NAME:
if token.value in ("true", "false"):
advance(parser)
@@ -624,10 +644,10 @@ def parse_type_system_definition(parser):
- EnumTypeDefinition
- InputObjectTypeDefinition
"""
- if not peek(parser, TokenKind.NAME):
- raise unexpected(parser)
-
- name = parser.token.value
+ if peek_description(parser):
+ name = parser.lexer.look_ahead().value
+ else:
+ name = parser.token.value
if name == "schema":
return parse_schema_definition(parser)
@@ -688,9 +708,11 @@ def parse_scalar_type_definition(parser):
# type: (Parser) -> ScalarTypeDefinition
start = parser.token.start
expect_keyword(parser, "scalar")
+ description = parse_description(parser)
return ast.ScalarTypeDefinition(
name=parse_name(parser),
+ description=description,
directives=parse_directives(parser),
loc=loc(parser, start),
)
@@ -699,9 +721,11 @@ def parse_scalar_type_definition(parser):
def parse_object_type_definition(parser):
# type: (Parser) -> ObjectTypeDefinition
start = parser.token.start
+ description = parse_description(parser)
expect_keyword(parser, "type")
return ast.ObjectTypeDefinition(
name=parse_name(parser),
+ description=description,
interfaces=parse_implements_interfaces(parser),
directives=parse_directives(parser),
fields=any(
@@ -729,9 +753,11 @@ def parse_implements_interfaces(parser):
def parse_field_definition(parser):
# type: (Parser) -> FieldDefinition
start = parser.token.start
+ description = parse_description(parser)
return ast.FieldDefinition( # type: ignore
name=parse_name(parser),
+ description=description,
arguments=parse_argument_defs(parser),
type=expect(parser, TokenKind.COLON) and parse_type(parser),
directives=parse_directives(parser),
@@ -750,9 +776,11 @@ def parse_argument_defs(parser):
def parse_input_value_def(parser):
# type: (Parser) -> InputValueDefinition
start = parser.token.start
+ description = parse_description(parser)
return ast.InputValueDefinition( # type: ignore
name=parse_name(parser),
+ description=description,
type=expect(parser, TokenKind.COLON) and parse_type(parser),
default_value=parse_const_value(parser)
if skip(parser, TokenKind.EQUALS)
@@ -765,10 +793,12 @@ def parse_input_value_def(parser):
def parse_interface_type_definition(parser):
# type: (Parser) -> InterfaceTypeDefinition
start = parser.token.start
+ description = parse_description(parser)
expect_keyword(parser, "interface")
return ast.InterfaceTypeDefinition(
name=parse_name(parser),
+ description=description,
directives=parse_directives(parser),
fields=any(
parser, TokenKind.BRACE_L, parse_field_definition, TokenKind.BRACE_R
@@ -780,10 +810,12 @@ def parse_interface_type_definition(parser):
def parse_union_type_definition(parser):
# type: (Parser) -> UnionTypeDefinition
start = parser.token.start
+ description = parse_description(parser)
expect_keyword(parser, "union")
return ast.UnionTypeDefinition( # type: ignore
name=parse_name(parser),
+ description=description,
directives=parse_directives(parser),
types=expect(parser, TokenKind.EQUALS) and parse_union_members(parser),
loc=loc(parser, start),
@@ -806,10 +838,12 @@ def parse_union_members(parser):
def parse_enum_type_definition(parser):
# type: (Parser) -> EnumTypeDefinition
start = parser.token.start
+ description = parse_description(parser)
expect_keyword(parser, "enum")
return ast.EnumTypeDefinition(
name=parse_name(parser),
+ description=description,
directives=parse_directives(parser),
values=many(
parser, TokenKind.BRACE_L, parse_enum_value_definition, TokenKind.BRACE_R
@@ -821,9 +855,11 @@ def parse_enum_type_definition(parser):
def parse_enum_value_definition(parser):
# type: (Parser) -> EnumValueDefinition
start = parser.token.start
+ description = parse_description(parser)
return ast.EnumValueDefinition(
name=parse_name(parser),
+ description=description,
directives=parse_directives(parser),
loc=loc(parser, start),
)
@@ -832,10 +868,12 @@ def parse_enum_value_definition(parser):
def parse_input_object_type_definition(parser):
# type: (Parser) -> InputObjectTypeDefinition
start = parser.token.start
+ description = parse_description(parser)
expect_keyword(parser, "input")
return ast.InputObjectTypeDefinition(
name=parse_name(parser),
+ description=description,
directives=parse_directives(parser),
fields=any(parser, TokenKind.BRACE_L, parse_input_value_def, TokenKind.BRACE_R),
loc=loc(parser, start),
@@ -855,6 +893,7 @@ def parse_type_extension_definition(parser):
def parse_directive_definition(parser):
# type: (Parser) -> DirectiveDefinition
start = parser.token.start
+ description = parse_description(parser)
expect_keyword(parser, "directive")
expect(parser, TokenKind.AT)
@@ -864,7 +903,11 @@ def parse_directive_definition(parser):
locations = parse_directive_locations(parser)
return ast.DirectiveDefinition(
- name=name, locations=locations, arguments=args, loc=loc(parser, start)
+ name=name,
+ description=description,
+ locations=locations,
+ arguments=args,
+ loc=loc(parser, start),
)
diff --git a/graphql/language/printer.py b/graphql/language/printer.py
index 676af0a8..67cde409 100644
--- a/graphql/language/printer.py
+++ b/graphql/language/printer.py
@@ -140,8 +140,10 @@ def leave_IntValue(self, node, *args):
def leave_FloatValue(self, node, *args):
return node.value
- def leave_StringValue(self, node, *args):
+ def leave_StringValue(self, node, key, *args):
# type: (Any, *Any) -> str
+ if node.is_block_string:
+ return print_block_string(node.value, key == 'description')
return json.dumps(node.value)
def leave_BooleanValue(self, node, *args):
@@ -198,84 +200,102 @@ def leave_OperationTypeDefinition(self, node, *args):
def leave_ScalarTypeDefinition(self, node, *args):
# type: (Any, *Any) -> str
- return "scalar " + node.name + wrap(" ", join(node.directives, " "))
+ return join([
+ node.description,
+ join(["scalar", node.name, join(node.directives, " ")], " "),
+ ], "\n")
def leave_ObjectTypeDefinition(self, node, *args):
# type: (Any, *Any) -> str
- return join(
- [
+ return join([
+ node.description,
+ join([
"type",
node.name,
wrap("implements ", join(node.interfaces, ", ")),
join(node.directives, " "),
block(node.fields),
- ],
- " ",
- )
+ ], " "),
+ ], "\n")
def leave_FieldDefinition(self, node, *args):
# type: (Any, *Any) -> str
- return (
+ has_multiline_item = any("\n" in arg for arg in node.arguments)
+ if has_multiline_item:
+ arguments_str = wrap("(\n", indent(join(node.arguments, "\n")), "\n)")
+ else:
+ arguments_str = wrap("(", join(node.arguments, ", "), ")")
+
+ definition_str = (
node.name
- + wrap("(", join(node.arguments, ", "), ")")
+ + arguments_str
+ ": "
+ node.type
+ wrap(" ", join(node.directives, " "))
)
+ return join([node.description, definition_str], "\n")
def leave_InputValueDefinition(self, node, *args):
# type: (Any, *Any) -> str
- return (
+ definition_str = (
node.name
+ ": "
+ node.type
+ wrap(" = ", node.default_value)
+ wrap(" ", join(node.directives, " "))
)
+ return join([node.description, definition_str], "\n")
def leave_InterfaceTypeDefinition(self, node, *args):
# type: (Any, *Any) -> str
- return (
+ definition_str = (
"interface "
+ node.name
+ wrap(" ", join(node.directives, " "))
+ " "
+ block(node.fields)
)
+ return join([node.description, definition_str], "\n")
def leave_UnionTypeDefinition(self, node, *args):
# type: (Any, *Any) -> str
- return (
+ definition_str = (
"union "
+ node.name
+ wrap(" ", join(node.directives, " "))
+ " = "
+ join(node.types, " | ")
)
+ return join([node.description, definition_str], "\n")
def leave_EnumTypeDefinition(self, node, *args):
# type: (Any, *Any) -> str
- return (
+ definition_str = (
"enum "
+ node.name
+ wrap(" ", join(node.directives, " "))
+ " "
+ block(node.values)
)
+ return join([node.description, definition_str], "\n")
def leave_EnumValueDefinition(self, node, *args):
# type: (Any, *Any) -> str
- return node.name + wrap(" ", join(node.directives, " "))
+ return join([
+ node.description,
+ join([node.name, join(node.directives, " ")], " "),
+ ], "\n")
def leave_InputObjectTypeDefinition(self, node, *args):
# type: (Any, *Any) -> str
- return (
+ definition_str = (
"input "
+ node.name
+ wrap(" ", join(node.directives, " "))
+ " "
+ block(node.fields)
)
+ return join([node.description, definition_str], "\n")
def leave_TypeExtensionDefinition(self, node, *args):
# type: (Any, *Any) -> str
@@ -283,11 +303,14 @@ def leave_TypeExtensionDefinition(self, node, *args):
def leave_DirectiveDefinition(self, node, *args):
# type: (Any, *Any) -> str
- return "directive @{}{} on {}".format(
- node.name,
- wrap("(", join(node.arguments, ", "), ")"),
- " | ".join(node.locations),
- )
+ return join([
+ node.description,
+ "directive @{}{} on {}".format(
+ node.name,
+ wrap("(", join(node.arguments, ", "), ")"),
+ " | ".join(node.locations),
+ )
+ ], "\n")
def join(maybe_list, separator=""):
@@ -317,3 +340,13 @@ def indent(maybe_str):
if maybe_str:
return ' ' + maybe_str.replace("\n", "\n ")
return ""
+
+
+def print_block_string(value, is_description):
+ escaped = value.replace('"""', '\\"""')
+ if "\n" in value or (value[0] != " " and value[0] != "\t"):
+ if is_description:
+ return '"""\n' + escaped + '\n"""'
+ else:
+ return '"""\n' + indent(escaped) + '\n"""'
+ return '"""' + escaped.replace(r'"$', '"\n') + '"""'
diff --git a/graphql/language/tests/fixtures.py b/graphql/language/tests/fixtures.py
index b16653c4..290dc98d 100644
--- a/graphql/language/tests/fixtures.py
+++ b/graphql/language/tests/fixtures.py
@@ -58,7 +58,7 @@
}
"""
-SCHEMA_KITCHEN_SINK = """
+SCHEMA_KITCHEN_SINK = '''
# Copyright (c) 2015, Facebook, Inc.
# All rights reserved.
@@ -72,9 +72,23 @@
mutation: MutationType
}
+"""
+This is a description
+of the `Foo` type.
+"""
type Foo implements Bar {
+ "Description of the `one` field."
one: Type
- two(argument: InputType!): Type
+ """
+ This is a description of the `two` field.
+ """
+ two(
+ """
+ This is a description of the `argument` argument.
+ """
+ argument: InputType!
+ ): Type
+ """This is a description of the `three` field."""
three(argument: InputType, other: String): Int
four(argument: String = "string"): String
five(argument: [String] = ["string", "string"]): String
@@ -103,8 +117,16 @@
scalar AnnotatedScalar @onScalar
enum Site {
+ """
+ This is a description of the `DESKTOP` value
+ """
+
DESKTOP
+ """This is a description of the `MOBILE` value"""
MOBILE
+
+ "This is a description of the `WEB` value"
+ WEB
}
enum AnnotatedEnum @onEnum {
@@ -129,7 +151,10 @@
type NoFields {}
+"""
+This is a description of the `@skip` directive
+"""
directive @skip(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
directive @include(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
-"""
+'''
diff --git a/graphql/language/tests/test_block_string_value.py b/graphql/language/tests/test_block_string_value.py
new file mode 100644
index 00000000..cbbaacf6
--- /dev/null
+++ b/graphql/language/tests/test_block_string_value.py
@@ -0,0 +1,108 @@
+from graphql.language.lexer import block_string_value
+
+
+def test_uniform_indentation():
+ _input = [
+ '',
+ ' Hello,',
+ ' World!',
+ '',
+ ' Yours,',
+ ' GraphQL.',
+ ]
+ expectation = [
+ 'Hello,',
+ ' World!',
+ '',
+ 'Yours,',
+ ' GraphQL.',
+ ]
+ _test_harness(_input, expectation)
+
+
+def test_empty_leading_and_trailing_lines():
+ _input = [
+ '',
+ '',
+ ' Hello,',
+ ' World!',
+ '',
+ ' Yours,',
+ ' GraphQL.',
+ '',
+ '',
+ ]
+ expectation = [
+ 'Hello,',
+ ' World!',
+ '',
+ 'Yours,',
+ ' GraphQL.',
+ ]
+ _test_harness(_input, expectation)
+
+
+def remove_blank_and_leading_lines():
+ _input = [
+ ' ',
+ ' ',
+ ' Hello,',
+ ' World!',
+ '',
+ ' Yours,',
+ ' GraphQL.',
+ ' ',
+ ' ',
+ ]
+ expectation = [
+ 'Hello,',
+ ' World!',
+ '',
+ 'Yours,',
+ ' GraphQL.',
+ ]
+ _test_harness(_input, expectation)
+
+
+def test_retain_indentation_from_first_line():
+ _input = [
+ ' Hello,',
+ ' World!',
+ '',
+ ' Yours,',
+ ' GraphQL.',
+ ]
+ expectation = [
+ ' Hello,',
+ ' World!',
+ '',
+ 'Yours,',
+ ' GraphQL.',
+ ]
+ _test_harness(_input, expectation)
+
+
+def test_does_not_alter_trailing_spaces():
+ _input = [
+ ' ',
+ ' Hello, ',
+ ' World! ',
+ ' ',
+ ' Yours, ',
+ ' GraphQL. ',
+ ' ',
+ ]
+ expectation = [
+ 'Hello, ',
+ ' World! ',
+ ' ',
+ 'Yours, ',
+ ' GraphQL. ',
+ ]
+ _test_harness(_input, expectation)
+
+
+def _test_harness(_input, expectation):
+ _input = "\n".join(_input)
+ expectation = "\n".join(expectation)
+ assert block_string_value(_input) == expectation
diff --git a/graphql/language/tests/test_schema_printer.py b/graphql/language/tests/test_schema_printer.py
index afa979cb..310fef55 100644
--- a/graphql/language/tests/test_schema_printer.py
+++ b/graphql/language/tests/test_schema_printer.py
@@ -38,14 +38,30 @@ def test_prints_kitchen_sink():
ast = parse(SCHEMA_KITCHEN_SINK)
printed = print_ast(ast)
- expected = """schema {
+ expected = '''schema {
query: QueryType
mutation: MutationType
}
+"""
+This is a description
+of the `Foo` type.
+"""
type Foo implements Bar {
+ "Description of the `one` field."
one: Type
- two(argument: InputType!): Type
+ """
+ This is a description of the `two` field.
+ """
+ two(
+ """
+ This is a description of the `argument` argument.
+ """
+ argument: InputType!
+ ): Type
+ """
+ This is a description of the `three` field.
+ """
three(argument: InputType, other: String): Int
four(argument: String = "string"): String
five(argument: [String] = ["string", "string"]): String
@@ -74,8 +90,16 @@ def test_prints_kitchen_sink():
scalar AnnotatedScalar @onScalar
enum Site {
+ """
+ This is a description of the `DESKTOP` value
+ """
DESKTOP
+ """
+ This is a description of the `MOBILE` value
+ """
MOBILE
+ "This is a description of the `WEB` value"
+ WEB
}
enum AnnotatedEnum @onEnum {
@@ -100,9 +124,12 @@ def test_prints_kitchen_sink():
type NoFields {}
+"""
+This is a description of the `@skip` directive
+"""
directive @skip(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
directive @include(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
-"""
+'''
assert printed == expected
diff --git a/graphql/language/visitor_meta.py b/graphql/language/visitor_meta.py
index 37372c48..87f5ad37 100644
--- a/graphql/language/visitor_meta.py
+++ b/graphql/language/visitor_meta.py
@@ -31,17 +31,17 @@
ast.NonNullType: ("type",),
ast.SchemaDefinition: ("directives", "operation_types"),
ast.OperationTypeDefinition: ("type",),
- ast.ScalarTypeDefinition: ("name", "directives"),
- ast.ObjectTypeDefinition: ("name", "interfaces", "directives", "fields"),
- ast.FieldDefinition: ("name", "arguments", "directives", "type"),
- ast.InputValueDefinition: ("name", "type", "directives", "default_value"),
- ast.InterfaceTypeDefinition: ("name", "directives", "fields"),
- ast.UnionTypeDefinition: ("name", "directives", "types"),
- ast.EnumTypeDefinition: ("name", "directives", "values"),
- ast.EnumValueDefinition: ("name", "directives"),
- ast.InputObjectTypeDefinition: ("name", "directives", "fields"),
+ ast.ScalarTypeDefinition: ("description", "name", "directives"),
+ ast.ObjectTypeDefinition: ("description", "name", "interfaces", "directives", "fields"),
+ ast.FieldDefinition: ("description", "name", "arguments", "directives", "type"),
+ ast.InputValueDefinition: ("description", "name", "type", "directives", "default_value"),
+ ast.InterfaceTypeDefinition: ("description", "name", "directives", "fields"),
+ ast.UnionTypeDefinition: ("description", "name", "directives", "types"),
+ ast.EnumTypeDefinition: ("description", "name", "directives", "values"),
+ ast.EnumValueDefinition: ("description", "name", "directives"),
+ ast.InputObjectTypeDefinition: ("description", "name", "directives", "fields"),
ast.TypeExtensionDefinition: ("definition",),
- ast.DirectiveDefinition: ("name", "arguments", "locations"),
+ ast.DirectiveDefinition: ("description", "name", "arguments", "locations"),
}
AST_KIND_TO_TYPE = {c.__name__: c for c in QUERY_DOCUMENT_KEYS.keys()}
diff --git a/graphql/type/directives.py b/graphql/type/directives.py
index ef7417c4..1a7bf701 100644
--- a/graphql/type/directives.py
+++ b/graphql/type/directives.py
@@ -107,7 +107,7 @@ def __init__(self, name, description=None, args=None, locations=None):
"reason": GraphQLArgument(
type=GraphQLString,
description=(
- "Explains why this element was deprecated, usually also including a suggestion for how to"
+ "Explains why this element was deprecated, usually also including a suggestion for how to "
"access supported similar data. Formatted in [Markdown]"
"(https://daringfireball.net/projects/markdown/)."
),
diff --git a/graphql/utils/build_ast_schema.py b/graphql/utils/build_ast_schema.py
index 8d28f4be..541be45b 100644
--- a/graphql/utils/build_ast_schema.py
+++ b/graphql/utils/build_ast_schema.py
@@ -167,6 +167,7 @@ def get_directive(directive_ast):
name=directive_ast.name.value,
locations=[node.value for node in directive_ast.locations],
args=make_input_values(directive_ast.arguments, GraphQLArgument),
+ description=get_description(directive_ast),
)
def get_object_type(type_ast):
@@ -210,6 +211,7 @@ def make_type_def(definition):
name=definition.name.value,
fields=lambda: make_field_def_map(definition),
interfaces=make_implemented_interfaces(definition),
+ description=get_description(definition),
)
def make_field_def_map(definition):
@@ -220,6 +222,7 @@ def make_field_def_map(definition):
type=produce_type_def(f.type),
args=make_input_values(f.arguments, GraphQLArgument),
deprecation_reason=get_deprecation_reason(f.directives),
+ description=get_description(f),
),
)
for f in definition.fields
@@ -237,6 +240,7 @@ def make_input_values(values, cls):
default_value=value_from_ast(
value.default_value, produce_type_def(value.type)
),
+ description=get_description(value),
),
)
for value in values
@@ -247,6 +251,7 @@ def make_interface_def(definition):
name=definition.name.value,
resolve_type=_none,
fields=lambda: make_field_def_map(definition),
+ description=get_description(definition),
)
def make_enum_def(definition):
@@ -254,18 +259,24 @@ def make_enum_def(definition):
(
v.name.value,
GraphQLEnumValue(
- deprecation_reason=get_deprecation_reason(v.directives)
+ deprecation_reason=get_deprecation_reason(v.directives),
+ description=get_description(v),
),
)
for v in definition.values
)
- return GraphQLEnumType(name=definition.name.value, values=values)
+ return GraphQLEnumType(
+ name=definition.name.value,
+ values=values,
+ description=get_description(definition),
+ )
def make_union_def(definition):
return GraphQLUnionType(
name=definition.name.value,
resolve_type=_none,
types=[produce_type_def(t) for t in definition.types],
+ description=get_description(definition),
)
def make_scalar_def(definition):
@@ -277,6 +288,7 @@ def make_scalar_def(definition):
# will cause them to pass.
parse_literal=_false,
parse_value=_false,
+ description=get_description(definition),
)
def make_input_object_def(definition):
@@ -285,6 +297,7 @@ def make_input_object_def(definition):
fields=lambda: make_input_values(
definition.fields, GraphQLInputObjectField
),
+ description=get_description(definition),
)
_schema_def_handlers = {
@@ -352,3 +365,8 @@ def get_deprecation_reason(directives):
return args["reason"]
else:
return None
+
+
+def get_description(node):
+ if node.description:
+ return node.description.value
diff --git a/graphql/utils/schema_printer.py b/graphql/utils/schema_printer.py
index 30a28abd..18356a75 100644
--- a/graphql/utils/schema_printer.py
+++ b/graphql/utils/schema_printer.py
@@ -1,3 +1,5 @@
+import re
+
from ..language.printer import print_ast
from ..type.definition import (
GraphQLEnumType,
@@ -25,6 +27,9 @@
from typing import Any, Union, Callable
+MAX_DESC_LEN = 120
+
+
def print_schema(schema):
# type: (GraphQLSchema) -> str
return _print_filtered_schema(
@@ -122,7 +127,7 @@ def _print_type(type):
def _print_scalar(type):
# type: (GraphQLScalarType) -> str
- return "scalar {}".format(type.name)
+ return _print_description(type) + "scalar {}".format(type.name)
def _print_object(type):
@@ -134,44 +139,69 @@ def _print_object(type):
else ""
)
- return ("type {}{} {{\n" "{}\n" "}}").format(
- type.name, implemented_interfaces, _print_fields(type)
+ return ("{}type {}{} {{\n" "{}\n" "}}").format(
+ _print_description(type),
+ type.name,
+ implemented_interfaces,
+ _print_fields(type),
)
def _print_interface(type):
# type: (GraphQLInterfaceType) -> str
- return ("interface {} {{\n" "{}\n" "}}").format(type.name, _print_fields(type))
+ return ("{}interface {} {{\n" "{}\n" "}}").format(
+ _print_description(type),
+ type.name,
+ _print_fields(type),
+ )
def _print_union(type):
# type: (GraphQLUnionType) -> str
- return "union {} = {}".format(type.name, " | ".join(str(t) for t in type.types))
+ return "{}union {} = {}".format(
+ _print_description(type),
+ type.name,
+ " | ".join(str(t) for t in type.types),
+ )
def _print_enum(type):
# type: (GraphQLEnumType) -> str
- return ("enum {} {{\n" "{}\n" "}}").format(
- type.name, "\n".join(" " + v.name + _print_deprecated(v) for v in type.values)
+ enum_values_str = "\n".join(
+ _print_description(v, ' ', not idx) + ' ' + v.name + _print_deprecated(v)
+ for idx, v in enumerate(type.values)
+ )
+ return ("{}enum {} {{\n" "{}\n" "}}").format(
+ _print_description(type),
+ type.name,
+ enum_values_str,
)
def _print_input_object(type):
# type: (GraphQLInputObjectType) -> str
- return ("input {} {{\n" "{}\n" "}}").format(
+ fields_str = "\n".join(
+ _print_description(f, " ", not idx) + " " + _print_input_value(name, f)
+ for idx, (name, f) in enumerate(type.fields.items())
+ )
+ return ("{}input {} {{\n" "{}\n" "}}").format(
+ _print_description(type),
type.name,
- "\n".join(
- " " + _print_input_value(name, field)
- for name, field in type.fields.items()
- ),
+ fields_str,
)
def _print_fields(type):
# type: (Union[GraphQLObjectType, GraphQLInterfaceType]) -> str
return "\n".join(
- " {}{}: {}{}".format(f_name, _print_args(f), f.type, _print_deprecated(f))
- for f_name, f in type.fields.items()
+ "{} {}{}: {}{}".format(
+ _print_description(f, ' ', not idx),
+ f_name,
+ _print_args(f),
+ f.type,
+ _print_deprecated(f),
+ )
+ for idx, (f_name, f) in enumerate(type.fields.items())
)
@@ -189,15 +219,24 @@ def _print_deprecated(field_or_enum_value):
def _print_args(field_or_directives):
# type: (Union[GraphQLField, GraphQLDirective]) -> str
- if not field_or_directives.args:
+ args = field_or_directives.args
+
+ if not args:
return ""
- return "({})".format(
- ", ".join(
- _print_input_value(arg_name, arg)
- for arg_name, arg in field_or_directives.args.items()
+ if all(not arg.description for arg in args.values()):
+ return "({})".format(
+ ", ".join(
+ _print_input_value(arg_name, arg)
+ for arg_name, arg in args.items()
+ )
)
+
+ args_description = "\n".join(
+ _print_description(arg, ' ', not idx) + " " + _print_input_value(arg_name, arg)
+ for idx, (arg_name, arg) in enumerate(args.items())
)
+ return "(\n" + args_description + "\n)"
def _print_input_value(name, arg):
@@ -212,9 +251,70 @@ def _print_input_value(name, arg):
def _print_directive(directive):
# type: (GraphQLDirective) -> str
- return "directive @{}{} on {}".format(
- directive.name, _print_args(directive), " | ".join(directive.locations)
+ return "{}directive @{}{} on {}".format(
+ _print_description(directive),
+ directive.name,
+ _print_args(directive),
+ " | ".join(directive.locations),
)
+def _print_description(definition, indentation="", first_in_block=True):
+ if not definition.description:
+ return ""
+
+ lines = _description_lines(definition.description, MAX_DESC_LEN - len(indentation))
+ if indentation and not first_in_block:
+ description = "\n" + indentation + '"""'
+ else:
+ description = indentation + '"""'
+
+ if len(lines) == 1 and len(lines[0]) < 70 and lines[0][-1] != '"':
+ return description + _escape_quote(lines[0]) + '"""\n'
+
+ has_leading_space = lines[0][0] == " " or lines[0][0] == "\t";
+ if not has_leading_space:
+ description += "\n";
+
+ for idx, line in enumerate(lines):
+ if idx != 0 or not has_leading_space:
+ description += indentation;
+
+ description += _escape_quote(line) + "\n";
+
+ return description + indentation + '"""\n';
+
+
+def _description_lines(description, max_len):
+ lines = []
+ raw_lines = description.split("\n")
+ for line in raw_lines:
+ if line == "":
+ lines.append(line)
+ else:
+ lines = lines + _break_lines(line, max_len)
+ return lines
+
+
+def _break_lines(line, max_len):
+ if len(line) < max_len + 5:
+ return [line]
+
+ line_split_re = r"((?: |^).{15,%s}(?= |$))" % str(max_len - 40)
+ parts = re.split(line_split_re, line)
+
+ if len(parts) < 4:
+ return [line]
+
+ sublines = [parts[0] + parts[1] + parts[2]]
+ for idx in range(3, len(parts), 2):
+ sublines.append(parts[idx][1:] + parts[idx + 1])
+
+ return sublines
+
+
+def _escape_quote(line):
+ return line.replace('"""', '\\"""')
+
+
__all__ = ["print_schema", "print_introspection_schema"]
diff --git a/graphql/utils/tests/test_build_ast_schema.py b/graphql/utils/tests/test_build_ast_schema.py
index 6f84aa64..bf9bcf0f 100644
--- a/graphql/utils/tests/test_build_ast_schema.py
+++ b/graphql/utils/tests/test_build_ast_schema.py
@@ -54,6 +54,37 @@ def test_with_directives():
assert output == body
+def test_supports_descriptions():
+ body = '''
+schema {
+ query: Query
+}
+
+"""This is a directive"""
+directive @foo(
+ """It has an argument"""
+ arg: Int
+) on FIELD
+
+"""With an enum"""
+enum Color {
+ RED
+
+ """Not a creative color"""
+ GREEN
+ BLUE
+}
+
+"""What a great type"""
+type Query {
+ """And a field to boot"""
+ str: String
+}
+'''
+ output = cycle_output(body)
+ assert output == body
+
+
def test_maintains_skip_and_include_directives():
body = """
schema {
diff --git a/graphql/utils/tests/test_schema_printer.py b/graphql/utils/tests/test_schema_printer.py
index 0d61facf..fbaf3a5d 100644
--- a/graphql/utils/tests/test_schema_printer.py
+++ b/graphql/utils/tests/test_schema_printer.py
@@ -569,17 +569,45 @@ def test_print_introspection_schema():
assert (
output
- == """
+ == '''
schema {
query: Root
}
-directive @include(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
+"""
+Directs the executor to include this field or fragment only when the `if` argument is true.
+"""
+directive @include(
+ """Included when true."""
+ if: Boolean!
+) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
-directive @skip(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
+"""
+Directs the executor to skip this field or fragment when the `if` argument is true.
+"""
+directive @skip(
+ """Skipped when true."""
+ if: Boolean!
+) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
+
+"""Marks an element of a GraphQL schema as no longer supported."""
+directive @deprecated(
+ """
+ Explains why this element was deprecated, usually also including a suggestion
+ for how to access supported similar data. Formatted in
+ [Markdown](https://daringfireball.net/projects/markdown/).
+ """
+ reason: String = "No longer supported"
+) on FIELD_DEFINITION | ENUM_VALUE
-directive @deprecated(reason: String = "No longer supported") on FIELD_DEFINITION | ENUM_VALUE
+"""
+A Directive provides a way to describe alternate runtime execution and type validation behavior in a GraphQL document.
+In some cases, you need to provide options to alter GraphQL's execution behavior
+in ways field arguments will not suffice, such as conditionally including or
+skipping a field. Directives provide this by describing additional information
+to the executor.
+"""
type __Directive {
name: String!
description: String
@@ -590,27 +618,71 @@ def test_print_introspection_schema():
onField: Boolean! @deprecated(reason: "Use `locations`.")
}
+"""
+A Directive can be adjacent to many parts of the GraphQL language, a
+__DirectiveLocation describes one such possible adjacencies.
+"""
enum __DirectiveLocation {
+ """Location adjacent to a query operation."""
QUERY
+
+ """Location adjacent to a mutation operation."""
MUTATION
+
+ """Location adjacent to a subscription operation."""
SUBSCRIPTION
+
+ """Location adjacent to a field."""
FIELD
+
+ """Location adjacent to a fragment definition."""
FRAGMENT_DEFINITION
+
+ """Location adjacent to a fragment spread."""
FRAGMENT_SPREAD
+
+ """Location adjacent to an inline fragment."""
INLINE_FRAGMENT
+
+ """Location adjacent to a schema definition."""
SCHEMA
+
+ """Location adjacent to a scalar definition."""
SCALAR
+
+ """Location adjacent to an object definition."""
OBJECT
+
+ """Location adjacent to a field definition."""
FIELD_DEFINITION
+
+ """Location adjacent to an argument definition."""
ARGUMENT_DEFINITION
+
+ """Location adjacent to an interface definition."""
INTERFACE
+
+ """Location adjacent to a union definition."""
UNION
+
+ """Location adjacent to an enum definition."""
ENUM
+
+ """Location adjacent to an enum value definition."""
ENUM_VALUE
+
+ """Location adjacent to an input object definition."""
INPUT_OBJECT
+
+ """Location adjacent to an input object field definition."""
INPUT_FIELD_DEFINITION
}
+"""
+One possible value for a given Enum. Enum values are unique values, not a
+placeholder for a string or numeric value. However an Enum value is returned in
+a JSON response as a string.
+"""
type __EnumValue {
name: String!
description: String
@@ -618,6 +690,10 @@ def test_print_introspection_schema():
deprecationReason: String
}
+"""
+Object and Interface types are described by a list of Fields, each of which has
+a name, potentially a list of arguments, and a return type.
+"""
type __Field {
name: String!
description: String
@@ -627,6 +703,11 @@ def test_print_introspection_schema():
deprecationReason: String
}
+"""
+Arguments provided to Fields or Directives and the input fields of an
+InputObject are represented as Input Values which describe their type and
+optionally a default value.
+"""
type __InputValue {
name: String!
description: String
@@ -634,14 +715,42 @@ def test_print_introspection_schema():
defaultValue: String
}
+"""
+A GraphQL Schema defines the capabilities of a GraphQL server. It exposes all
+available types and directives on the server, as well as the entry points for
+query, mutation and subscription operations.
+"""
type __Schema {
+ """A list of all types supported by this server."""
types: [__Type!]!
+
+ """The type that query operations will be rooted at."""
queryType: __Type!
+
+ """
+ If this server supports mutation, the type that mutation operations will be rooted at.
+ """
mutationType: __Type
+
+ """
+ If this server support subscription, the type that subscription operations will be rooted at.
+ """
subscriptionType: __Type
+
+ """A list of all directives supported by this server."""
directives: [__Directive!]!
}
+"""
+The fundamental unit of any GraphQL Schema is the type. There are many kinds of
+types in GraphQL as represented by the `__TypeKind` enum.
+
+Depending on the kind of a type, certain fields describe information about that
+type. Scalar types provide no information beyond a name and description, while
+Enum types provide their values. Object and Interface types provide the fields
+they describe. Abstract types, Union and Interface, provide the Object types
+possible at runtime. List and NonNull types compose other types.
+"""
type __Type {
kind: __TypeKind!
name: String
@@ -654,15 +763,37 @@ def test_print_introspection_schema():
ofType: __Type
}
+"""An enum describing what kind of type a given `__Type` is"""
enum __TypeKind {
+ """Indicates this type is a scalar."""
SCALAR
+
+ """
+ Indicates this type is an object. `fields` and `interfaces` are valid fields.
+ """
OBJECT
+
+ """
+ Indicates this type is an interface. `fields` and `possibleTypes` are valid fields.
+ """
INTERFACE
+
+ """Indicates this type is a union. `possibleTypes` is a valid field."""
UNION
+
+ """Indicates this type is an enum. `enumValues` is a valid field."""
ENUM
+
+ """
+ Indicates this type is an input object. `inputFields` is a valid field.
+ """
INPUT_OBJECT
+
+ """Indicates this type is a list. `ofType` is a valid field."""
LIST
+
+ """Indicates this type is a non-null. `ofType` is a valid field."""
NON_NULL
}
-"""
+'''
)