Add support for adding description to schema

Replicates graphql/graphql-js@b883320

Author: Cito

src/graphql/language/ast.py

@@ -477,8 +477,9 @@ class TypeSystemDefinitionNode(DefinitionNode):
 
 
 class SchemaDefinitionNode(TypeSystemDefinitionNode):
-    __slots__ = "directives", "operation_types"
+    __slots__ = "description", "directives", "operation_types"
 
+    description: Optional[StringValueNode]
     directives: Optional[FrozenList[DirectiveNode]]
     operation_types: FrozenList["OperationTypeDefinitionNode"]
 

src/graphql/language/parser.py

@@ -581,13 +581,17 @@ def parse_description(self) -> Optional[StringValueNode]:
     def parse_schema_definition(self) -> SchemaDefinitionNode:
         """SchemaDefinition"""
         start = self._lexer.token
+        description = self.parse_description()
         self.expect_keyword("schema")
         directives = self.parse_directives(True)
         operation_types = self.many(
             TokenKind.BRACE_L, self.parse_operation_type_definition, TokenKind.BRACE_R
         )
         return SchemaDefinitionNode(
-            directives=directives, operation_types=operation_types, loc=self.loc(start)
+            description=description,
+            directives=directives,
+            operation_types=operation_types,
+            loc=self.loc(start),
         )
 
     def parse_operation_type_definition(self) -> OperationTypeDefinitionNode:

src/graphql/language/printer.py

@@ -153,6 +153,7 @@ def leave_non_null_type(self, node, *_args):
 
     # Type System Definitions
 
+    @add_description
     def leave_schema_definition(self, node, *_args):
         return join(
             ["schema", join(node.directives, " "), block(node.operation_types)], " "

src/graphql/language/visitor.py

@@ -71,7 +71,7 @@
     "named_type": ("name",),
     "list_type": ("type",),
     "non_null_type": ("type",),
-    "schema_definition": ("directives", "operation_types"),
+    "schema_definition": ("description", "directives", "operation_types"),
     "operation_type_definition": ("type",),
     "scalar_type_definition": ("description", "name", "directives"),
     "object_type_definition": (

src/graphql/type/introspection.py

@@ -40,6 +40,9 @@
     " on the server, as well as the entry points for query,"
     " mutation, and subscription operations.",
     fields=lambda: {
+        "description": GraphQLField(
+            GraphQLString, resolve=lambda schema, _info: schema.description
+        ),
         "types": GraphQLField(
             GraphQLNonNull(GraphQLList(GraphQLNonNull(__Type))),
             resolve=lambda schema, _info: schema.type_map.values(),

src/graphql/type/schema.py

@@ -12,7 +12,7 @@
 
 from ..error import GraphQLError
 from ..language import ast
-from ..pyutils import inspect, is_collection, FrozenList
+from ..pyutils import inspect, is_collection, is_description, FrozenList
 from .definition import (
     GraphQLAbstractType,
     GraphQLInterfaceType,
@@ -94,6 +94,7 @@ class GraphQLSchema:
     subscription_type: Optional[GraphQLObjectType]
     type_map: TypeMap
     directives: FrozenList[GraphQLDirective]
+    description: Optional[str]
     extensions: Optional[Dict[str, Any]]
     ast_node: Optional[ast.SchemaDefinitionNode]
     extension_ast_nodes: Optional[FrozenList[ast.SchemaExtensionNode]]
@@ -109,6 +110,7 @@ def __init__(
         subscription: Optional[GraphQLObjectType] = None,
         types: Optional[Collection[GraphQLNamedType]] = None,
         directives: Optional[Collection[GraphQLDirective]] = None,
+        description: Optional[str] = None,
         extensions: Optional[Dict[str, Any]] = None,
         ast_node: Optional[ast.SchemaDefinitionNode] = None,
         extension_ast_nodes: Optional[Collection[ast.SchemaExtensionNode]] = None,
@@ -144,6 +146,8 @@ def __init__(
                 raise TypeError("Schema directives must be a collection.")
             if not isinstance(directives, FrozenList):
                 directives = FrozenList(directives)
+        if description is not None and not is_description(description):
+            raise TypeError("Schema description must be a string.")
         if extensions is not None and (
             not isinstance(extensions, dict)
             or not all(isinstance(key, str) for key in extensions)
@@ -163,6 +167,7 @@ def __init__(
             if not isinstance(extension_ast_nodes, FrozenList):
                 extension_ast_nodes = FrozenList(extension_ast_nodes)
 
+        self.description = description
         self.extensions = extensions
         self.ast_node = ast_node
         self.extension_ast_nodes = (
@@ -268,6 +273,7 @@ def to_kwargs(self) -> Dict[str, Any]:
             subscription=self.subscription_type,
             types=FrozenList(self.type_map.values()) or None,
             directives=self.directives[:],
+            description=self.description,
             extensions=self.extensions,
             ast_node=self.ast_node,
             extension_ast_nodes=self.extension_ast_nodes,

src/graphql/utilities/build_client_schema.py

@@ -337,7 +337,6 @@ def build_directive(directive_introspection: Dict) -> GraphQLDirective:
             type_map[std_type_name] = std_type
 
     # Get the root Query, Mutation, and Subscription types.
-
     query_type_ref = schema_introspection.get("queryType")
     query_type = None if query_type_ref is None else get_object_type(query_type_ref)
     mutation_type_ref = schema_introspection.get("mutationType")
@@ -363,11 +362,13 @@ def build_directive(directive_introspection: Dict) -> GraphQLDirective:
         else []
     )
 
+    # Then produce and return a Schema with these types.
     return GraphQLSchema(
         query=query_type,
         mutation=mutation_type,
         subscription=subscription_type,
         types=list(type_map.values()),
         directives=directives,
+        description=schema_introspection.get("description"),
         assume_valid=assume_valid,
     )

src/graphql/utilities/extend_schema.py

@@ -652,6 +652,9 @@ def build_type(ast_node: TypeDefinitionNode) -> GraphQLNamedType:
             replace_directive(directive) for directive in schema_kwargs["directives"]
         ]
         + [build_directive(directive) for directive in directive_defs],
+        "description": schema_def.description.value
+        if schema_def and schema_def.description
+        else None,
         "extensions": None,
         "ast_node": schema_def or schema_kwargs["ast_node"],
         "extension_ast_nodes": (

src/graphql/utilities/get_introspection_query.py

@@ -3,17 +3,22 @@
 __all__ = ["get_introspection_query"]
 
 
-def get_introspection_query(descriptions=True, directive_is_repeatable=False) -> str:
+def get_introspection_query(
+    descriptions=True, directive_is_repeatable=False, schema_description=False
+) -> str:
     """Get a query for introspection.
 
-    Optionally, you can exclude descriptions and include repeatability of directives.
+    Optionally, you can exclude descriptions, include repeatability of directives,
+    and specify whether to include the schema description as well.
     """
     maybe_description = "description" if descriptions else ""
     maybe_directive_is_repeatable = "isRepeatable" if directive_is_repeatable else ""
+    maybe_schema_description = maybe_description if schema_description else ""
     return dedent(
         f"""
         query IntrospectionQuery {{
           __schema {{
+            {maybe_schema_description}
             queryType {{ name }}
             mutationType {{ name }}
             subscriptionType {{ name }}

src/graphql/utilities/introspection_from_schema.py

@@ -15,6 +15,7 @@ def introspection_from_schema(
     schema: GraphQLSchema,
     descriptions: bool = True,
     directive_is_repeatable: bool = True,
+    schema_description: bool = True,
 ) -> IntrospectionSchema:
     """Build an IntrospectionQuery from a GraphQLSchema
 
@@ -24,7 +25,11 @@ def introspection_from_schema(
     This is the inverse of build_client_schema. The primary use case is outside of the
     server context, for instance when doing schema comparisons.
     """
-    document = parse(get_introspection_query(descriptions, directive_is_repeatable))
+    document = parse(
+        get_introspection_query(
+            descriptions, directive_is_repeatable, schema_description
+        )
+    )
 
     from ..execution.execute import execute, ExecutionResult