Implement changes for executable descriptions

Replicates graphql/graphql-js@364f17fd

Author: Cito

src/graphql/language/ast.py

@@ -256,12 +256,19 @@ 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": (
@@ -283,6 +290,7 @@ class OperationType(Enum):
     "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",
@@ -418,6 +426,7 @@ class ExecutableDefinitionNode(DefinitionNode):
     """Base class for executable definition nodes."""
 
     selection_set: SelectionSetNode
+    description: StringValueNode | None = None
     name: NameNode | None = None
     variable_definitions: tuple[VariableDefinitionNode, ...] = ()
     directives: tuple[DirectiveNode, ...] = ()
@@ -652,6 +661,7 @@ class SelectionSetNode(Node):
 
 @node_class
 class VariableDefinitionNode(Node):
+    description: StringValueNode | None = None
     variable: VariableNode
     type: TypeNode
     default_value: ConstValueNode | None = None

src/graphql/language/parser.py

@@ -298,9 +298,12 @@ def parse_document(self) -> DocumentNode:
         "directive": "directive_definition",
     }
 
-    _parse_other_definition_method_names: Mapping[str, str] = {
+    _parse_executable_definition_method_names: Mapping[str, str] = {
         **dict.fromkeys(("query", "mutation", "subscription"), "operation_definition"),
         "fragment": "fragment_definition",
+    }
+
+    _parse_other_definition_method_names: Mapping[str, str] = {
         "extend": "type_system_extension",
     }
 
@@ -324,6 +327,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(
@@ -332,12 +343,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)
@@ -354,16 +369,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),
@@ -388,10 +406,12 @@ def parse_variable_definitions(self) -> tuple[VariableDefinitionNode, ...]:
     def parse_variable_definition(self) -> VariableDefinitionNode:
         """VariableDefinition: Variable: Type DefaultValue? Directives[Const]?"""
         start = self._lexer.token
+        description = self.parse_description()
         variable = self.parse_variable()
         self.expect_token(TokenKind.COLON)
         type_ = self.parse_type_reference()
         return VariableDefinitionNode(
+            description=description,
             variable=variable,
             type=type_,
             default_value=self.parse_const_value_literal()
@@ -528,11 +548,13 @@ def parse_fragment(self) -> 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(),
@@ -541,6 +563,7 @@ def parse_fragment_definition(self) -> FragmentDefinitionNode:
                 loc=self.loc(start),
             )
         return FragmentDefinitionNode(
+            description=description,
             name=self.parse_fragment_name(),
             variable_definitions=(),
             type_condition=self.parse_type_condition(),

src/graphql/language/printer.py

@@ -76,8 +76,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)),
@@ -92,7 +96,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, ' '))}"
         )
@@ -160,7 +164,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 {
@@ -57,6 +62,9 @@ subscription StoryLikeSubscription(
   }
 }
 
+"""
+  Fragment description
+"""
 fragment frag on Friend @onFragmentDefinition {
   foo(size: $size, bar: $b, obj: {key: "value", block: """