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
 

src/graphql/utilities/schema_printer.py

@@ -70,7 +70,7 @@ def print_filtered_schema(
 
 
 def print_schema_definition(schema: GraphQLSchema) -> Optional[str]:
-    if is_schema_of_common_names(schema):
+    if schema.description is None and is_schema_of_common_names(schema):
         return None
 
     operation_types = []
@@ -87,7 +87,7 @@ def print_schema_definition(schema: GraphQLSchema) -> Optional[str]:
     if subscription_type:
         operation_types.append(f"  subscription: {subscription_type.name}")
 
-    return "schema {\n" + "\n".join(operation_types) + "\n}"
+    return print_description(schema) + "schema {\n" + "\n".join(operation_types) + "\n}"
 
 
 def is_schema_of_common_names(schema: GraphQLSchema) -> bool:
@@ -264,7 +264,13 @@ def print_deprecated(field_or_enum_value: Union[GraphQLField, GraphQLEnumValue])
 
 
 def print_description(
-    def_: Union[GraphQLArgument, GraphQLDirective, GraphQLEnumValue, GraphQLNamedType],
+    def_: Union[
+        GraphQLArgument,
+        GraphQLDirective,
+        GraphQLEnumValue,
+        GraphQLNamedType,
+        GraphQLSchema,
+    ],
     indentation="",
     first_in_block=True,
 ) -> str:

tests/fixtures/kitchen_sink.graphql

@@ -1,8 +1,3 @@
-# Copyright (c) 2015-present, Facebook, Inc.
-#
-# This source code is licensed under the MIT license found in the
-# LICENSE file in the root directory of this source tree.
-
 query queryName($foo: ComplexType, $site: Site = MOBILE) @onQuery {
   whoever123is: node(id: [123, 456]) {
     id ,

tests/fixtures/schema_kitchen_sink.graphql

@@ -1,8 +1,4 @@
-# Copyright (c) 2015-present, Facebook, Inc.
-#
-# This source code is licensed under the MIT license found in the
-# LICENSE file in the root directory of this source tree.
-
+"""This is a description of the schema as a whole."""
 schema {
   query: QueryType
   mutation: MutationType

tests/language/test_schema_parser.py

@@ -24,6 +24,7 @@
     OperationType,
     OperationTypeDefinitionNode,
     ScalarTypeDefinitionNode,
+    SchemaDefinitionNode,
     SchemaExtensionNode,
     StringValueNode,
     UnionTypeDefinitionNode,
@@ -96,6 +97,10 @@ def boolean_value_node(value, loc):
     return BooleanValueNode(value=value, loc=loc)
 
 
+def string_value_node(value, block, loc):
+    return StringValueNode(value=value, block=block, loc=loc)
+
+
 def list_type_node(type_, loc):
     return ListTypeNode(type=type_, loc=loc)
 
@@ -149,10 +154,7 @@ def parses_type_with_description_string():
         assert isinstance(definition, ObjectTypeDefinitionNode)
         assert definition.name == name_node("Hello", (20, 25))
         description = definition.description
-        assert isinstance(description, StringValueNode)
-        assert description.value == "Description"
-        assert description.block is False
-        assert description.loc == (1, 14)
+        assert description == string_value_node("Description", False, (1, 14))
 
     def parses_type_with_description_multi_line_string():
         body = dedent(
@@ -169,10 +171,21 @@ def parses_type_with_description_multi_line_string():
         assert isinstance(definition, ObjectTypeDefinitionNode)
         assert definition.name == name_node("Hello", (60, 65))
         description = definition.description
-        assert isinstance(description, StringValueNode)
-        assert description.value == "Description"
-        assert description.block is True
-        assert description.loc == (1, 20)
+        assert description == string_value_node("Description", True, (1, 20))
+
+    def parses_schema_with_description_string():
+        body = dedent(
+            """
+            "Description"
+            schema {
+              query: Foo
+            }
+            """
+        )
+        definition = assert_definitions(body, (0, 39))
+        assert isinstance(definition, SchemaDefinitionNode)
+        description = definition.description
+        assert description == string_value_node("Description", False, (1, 14))
 
     def description_followed_by_something_other_than_type_system_definition_throws():
         assert_syntax_error('"Description" 1', "Unexpected Int '1'.", (1, 15))

tests/language/test_schema_printer.py

@@ -36,6 +36,7 @@ def prints_kitchen_sink(kitchen_sink_sdl):  # noqa: F811
 
         assert printed == dedent(
             '''
+            """This is a description of the schema as a whole."""
             schema {
               query: QueryType
               mutation: MutationType

tests/type/test_introspection.py

@@ -17,7 +17,8 @@
 def describe_introspection():
     def executes_an_introspection_query():
         schema = GraphQLSchema(
-            GraphQLObjectType("QueryRoot", {"onlyField": GraphQLField(GraphQLString)})
+            GraphQLObjectType("QueryRoot", {"onlyField": GraphQLField(GraphQLString)}),
+            description="Sample schema",
         )
         source = get_introspection_query(
             descriptions=False, directive_is_repeatable=True
@@ -74,6 +75,17 @@ def executes_an_introspection_query():
                         "kind": "OBJECT",
                         "name": "__Schema",
                         "fields": [
+                            {
+                                "name": "description",
+                                "args": [],
+                                "type": {
+                                    "kind": "SCALAR",
+                                    "name": "String",
+                                    "ofType": None,
+                                },
+                                "isDeprecated": False,
+                                "deprecationReason": None,
+                            },
                             {
                                 "name": "types",
                                 "args": [],
@@ -1240,6 +1252,7 @@ def exposes_descriptions_on_types_and_fields():
                     " directives on the server, as well as the entry points"
                     " for query, mutation, and subscription operations.",
                     "fields": [
+                        {"name": "description", "description": None},
                         {
                             "name": "types",
                             "description": "A list of all types supported"

tests/type/test_schema.py

@@ -91,7 +91,9 @@ def define_sample_schema():
             },
         )
 
-        schema = GraphQLSchema(BlogQuery, BlogMutation, BlogSubscription)
+        schema = GraphQLSchema(
+            BlogQuery, BlogMutation, BlogSubscription, description="Sample schema",
+        )
 
         kwargs = schema.to_kwargs()
         types = kwargs.pop("types")
@@ -101,14 +103,22 @@ def define_sample_schema():
             "mutation": BlogMutation,
             "subscription": BlogSubscription,
             "directives": specified_directives,
-            "ast_node": None,
+            "description": "Sample schema",
             "extensions": None,
+            "ast_node": None,
             "extension_ast_nodes": None,
             "assume_valid": False,
         }
 
         assert print_schema(schema) == dedent(
-            """
+            '''
+            """Sample schema"""
+            schema {
+              query: Query
+              mutation: Mutation
+              subscription: Subscription
+            }
+
             type Query {
               article(id: String): Article
               feed: [Article]
@@ -142,7 +152,7 @@ def define_sample_schema():
             type Subscription {
               articleSubscribe(id: String): Article
             }
-            """
+            '''
         )
 
     def freezes_the_specified_directives():
@@ -154,6 +164,12 @@ def freezes_the_specified_directives():
         schema = GraphQLSchema(directives=directives)
         assert schema.directives is directives
 
+    def rejects_a_schema_with_incorrectly_typed_description():
+        with raises(TypeError) as exc_info:
+            # noinspection PyTypeChecker
+            GraphQLSchema(description=[])  # type: ignore
+        assert str(exc_info.value) == "Schema description must be a string."
+
     def describe_type_map():
         def includes_interface_possible_types_in_the_type_map():
             SomeInterface = GraphQLInterfaceType("SomeInterface", {})