Implement changes for executable descriptions

Replicates graphql/graphql-js@364f17fd

Author: Cito

src/graphql/language/ast.py

@@ -242,19 +242,27 @@ class OperationType(Enum):
     "name": (),
     "document": ("definitions",),
     "operation_definition": (
+        "description",
         "name",
         "variable_definitions",
         "directives",
         "selection_set",
     ),
-    "variable_definition": ("variable", "type", "default_value", "directives"),
+    "variable_definition": (
+        "description",
+        "variable",
+        "type",
+        "default_value",
+        "directives",
+    ),
     "variable": ("name",),
     "selection_set": ("selections",),
     "field": ("alias", "name", "arguments", "directives", "selection_set"),
     "argument": ("name", "value"),
     "fragment_spread": ("name", "directives"),
     "inline_fragment": ("type_condition", "directives", "selection_set"),
     "fragment_definition": (
+        "description",
         # Note: fragment variable definitions are deprecated and will be removed in v3.3
         "name",
         "variable_definitions",
@@ -423,8 +431,15 @@ class DefinitionNode(Node):
 
 
 class ExecutableDefinitionNode(DefinitionNode):
-    __slots__ = "name", "directives", "variable_definitions", "selection_set"
+    __slots__ = (
+        "description",
+        "name",
+        "directives",
+        "variable_definitions",
+        "selection_set",
+    )
 
+    description: Optional["StringValueNode"]
     name: Optional[NameNode]
     directives: Tuple["DirectiveNode", ...]
     variable_definitions: Tuple["VariableDefinitionNode", ...]
@@ -438,8 +453,9 @@ class OperationDefinitionNode(ExecutableDefinitionNode):
 
 
 class VariableDefinitionNode(Node):
-    __slots__ = "variable", "type", "default_value", "directives"
+    __slots__ = "description", "variable", "type", "default_value", "directives"
 
+    description: Optional["StringValueNode"]
     variable: "VariableNode"
     type: "TypeNode"
     default_value: Optional["ConstValueNode"]

src/graphql/language/parser.py

@@ -261,9 +261,12 @@ def parse_document(self) -> DocumentNode:
         "directive": "directive_definition",
     }
 
-    _parse_other_definition_method_names: Dict[str, str] = {
+    _parse_executable_definition_method_names: Dict[str, str] = {
         **dict.fromkeys(("query", "mutation", "subscription"), "operation_definition"),
         "fragment": "fragment_definition",
+    }
+
+    _parse_other_definition_method_names: Dict[str, str] = {
         "extend": "type_system_extension",
     }
 
@@ -287,6 +290,14 @@ def parse_definition(self) -> DefinitionNode:
             self._lexer.lookahead() if has_description else self._lexer.token
         )
 
+        if has_description and keyword_token.kind is TokenKind.BRACE_L:
+            raise GraphQLSyntaxError(
+                self._lexer.source,
+                self._lexer.token.start,
+                "Unexpected description,"
+                " descriptions are not supported on shorthand queries.",
+            )
+
         if keyword_token.kind is TokenKind.NAME:
             token_name = cast(str, keyword_token.value)
             method_name = self._parse_type_system_definition_method_names.get(
@@ -295,12 +306,16 @@ def parse_definition(self) -> DefinitionNode:
             if method_name:
                 return getattr(self, f"parse_{method_name}")()
 
+            method_name = self._parse_executable_definition_method_names.get(token_name)
+            if method_name:
+                return getattr(self, f"parse_{method_name}")()
+
             if has_description:
                 raise GraphQLSyntaxError(
                     self._lexer.source,
                     self._lexer.token.start,
                     "Unexpected description,"
-                    " descriptions are supported only on type definitions.",
+                    " only GraphQL definitions support descriptions.",
                 )
 
             method_name = self._parse_other_definition_method_names.get(token_name)
@@ -317,16 +332,19 @@ def parse_operation_definition(self) -> OperationDefinitionNode:
         if self.peek(TokenKind.BRACE_L):
             return OperationDefinitionNode(
                 operation=OperationType.QUERY,
+                description=None,
                 name=None,
                 variable_definitions=[],
                 directives=[],
                 selection_set=self.parse_selection_set(),
                 loc=self.loc(start),
             )
+        description = self.parse_description()
         operation = self.parse_operation_type()
         name = self.parse_name() if self.peek(TokenKind.NAME) else None
         return OperationDefinitionNode(
             operation=operation,
+            description=description,
             name=name,
             variable_definitions=self.parse_variable_definitions(),
             directives=self.parse_directives(False),
@@ -352,6 +370,7 @@ def parse_variable_definition(self) -> VariableDefinitionNode:
         """VariableDefinition: Variable: Type DefaultValue? Directives[Const]?"""
         start = self._lexer.token
         return VariableDefinitionNode(
+            description=self.parse_description(),
             variable=self.parse_variable(),
             type=self.expect_token(TokenKind.COLON) and self.parse_type_reference(),
             default_value=(
@@ -455,11 +474,13 @@ def parse_fragment(self) -> Union[FragmentSpreadNode, InlineFragmentNode]:
     def parse_fragment_definition(self) -> FragmentDefinitionNode:
         """FragmentDefinition"""
         start = self._lexer.token
+        description = self.parse_description()
         self.expect_keyword("fragment")
         # Legacy support for defining variables within fragments changes
         # the grammar of FragmentDefinition
         if self._allow_legacy_fragment_variables:
             return FragmentDefinitionNode(
+                description=description,
                 name=self.parse_fragment_name(),
                 variable_definitions=self.parse_variable_definitions(),
                 type_condition=self.parse_type_condition(),
@@ -468,6 +489,7 @@ def parse_fragment_definition(self) -> FragmentDefinitionNode:
                 loc=self.loc(start),
             )
         return FragmentDefinitionNode(
+            description=description,
             name=self.parse_fragment_name(),
             type_condition=self.parse_type_condition(),
             directives=self.parse_directives(False),

src/graphql/language/printer.py

@@ -66,8 +66,12 @@ def leave_document(node: PrintedNode, *_args: Any) -> str:
 
     @staticmethod
     def leave_operation_definition(node: PrintedNode, *_args: Any) -> str:
-        var_defs = wrap("(", join(node.variable_definitions, ", "), ")")
-        prefix = join(
+        var_defs = (
+            wrap("(\n", join(node.variable_definitions, "\n"), "\n)")
+            if has_multiline_items(node.variable_definitions)
+            else wrap("(", join(node.variable_definitions, ", "), ")")
+        )
+        prefix = wrap("", node.description, "\n") + join(
             (
                 node.operation.value,
                 join((node.name, var_defs)),
@@ -82,7 +86,7 @@ def leave_operation_definition(node: PrintedNode, *_args: Any) -> str:
     @staticmethod
     def leave_variable_definition(node: PrintedNode, *_args: Any) -> str:
         return (
-            f"{node.variable}: {node.type}"
+            wrap("", node.description, "\n") + f"{node.variable}: {node.type}"
             f"{wrap(' = ', node.default_value)}"
             f"{wrap(' ', join(node.directives, ' '))}"
         )
@@ -127,7 +131,7 @@ def leave_inline_fragment(node: PrintedNode, *_args: Any) -> str:
     def leave_fragment_definition(node: PrintedNode, *_args: Any) -> str:
         # Note: fragment variable definitions are deprecated and will be removed in v3.3
         return (
-            f"fragment {node.name}"
+            wrap("", node.description, "\n") + f"fragment {node.name}"
             f"{wrap('(', join(node.variable_definitions, ', '), ')')}"
             f" on {node.type_condition}"
             f" {wrap('', join(node.directives, ' '), ' ')}"

tests/fixtures/kitchen_sink.graphql

@@ -1,4 +1,9 @@
-query queryName($foo: ComplexType, $site: Site = MOBILE) @onQuery {
+"Query description"
+query queryName(
+  "Very complex variable"
+  $foo: ComplexType,
+  $site: Site = MOBILE
+) @onQuery {
   whoever123is: node(id: [123, 456]) {
     id ,
     ... on User @onInlineFragment {
@@ -42,6 +47,9 @@ subscription StoryLikeSubscription(
   }
 }
 
+"""
+  Fragment description
+"""
 fragment frag on Friend @onFragmentDefinition {
   foo(size: $size, bar: $b, obj: {key: "value", block: """