Added Deprecated directive. Commit: graphql/graphql-js@5375c9b

Author: markusdap

graphql/__init__.py

@@ -76,9 +76,14 @@
         # Directive definition
         GraphQLDirective,
 
-        # Built-in directives
+        # Built-in directives defined by the Spec
+        specified_directives,
         GraphQLSkipDirective,
         GraphQLIncludeDirective,
+        GraphQLDeprecatedDirective,
+
+        # Constant Deprecation Reason
+        DEFAULT_DEPRECATION_REASON,
 
         # GraphQL Types for introspection.
         __Schema,
@@ -215,8 +220,11 @@
         'GraphQLString',
         'GraphQLUnionType',
         'GraphQLDirective',
+        'specified_directives',
         'GraphQLSkipDirective',
         'GraphQLIncludeDirective',
+        'GraphQLDeprecatedDirective',
+        'DEFAULT_DEPRECATION_REASON',
         'TypeKind',
         'DirectiveLocation',
         '__Schema',

graphql/execution/values.py

@@ -29,7 +29,7 @@ def get_variable_values(schema, definition_asts, inputs):
     return values
 
 
-def get_argument_values(arg_defs, arg_asts, variables):
+def get_argument_values(arg_defs, arg_asts, variables=None):
     """Prepares an object map of argument values given a list of argument
     definitions and list of argument AST nodes."""
     if not arg_defs:

graphql/type/__init__.py

@@ -30,9 +30,14 @@
     # Directive definition
     GraphQLDirective,
 
-    # Built-in directives
+    # Built-in directives defined by the Spec
+    specified_directives,
     GraphQLSkipDirective,
-    GraphQLIncludeDirective
+    GraphQLIncludeDirective,
+    GraphQLDeprecatedDirective,
+
+    # Constant Deprecation Reason
+    DEFAULT_DEPRECATION_REASON,
 )
 from .scalars import (  # no import order
     GraphQLInt,

graphql/type/directives.py

@@ -3,7 +3,7 @@
 from ..utils.assert_valid_name import assert_valid_name
 from .definition import (GraphQLArgument, GraphQLArgumentDefinition,
                          GraphQLNonNull, is_input_type)
-from .scalars import GraphQLBoolean
+from .scalars import GraphQLBoolean, GraphQLString
 
 
 class DirectiveLocation(object):
@@ -74,9 +74,10 @@ def __init__(self, name, description=None, args=None, locations=None):
                     default_value=_arg.default_value,
                 ))
 
-
+"""Used to conditionally include fields or fragments."""
 GraphQLIncludeDirective = GraphQLDirective(
     name='include',
+    description='Directs the executor to include this field or fragment only when the `if` argument is true.',
     args={
         'if': GraphQLArgument(
             type=GraphQLNonNull(GraphQLBoolean),
@@ -90,8 +91,10 @@ def __init__(self, name, description=None, args=None, locations=None):
     ]
 )
 
+"""Used to conditionally skip (exclude) fields or fragments."""
 GraphQLSkipDirective = GraphQLDirective(
     name='skip',
+    description='Directs the executor to skip this field or fragment when the `if` argument is true.',
     args={
         'if': GraphQLArgument(
             type=GraphQLNonNull(GraphQLBoolean),
@@ -104,3 +107,31 @@ def __init__(self, name, description=None, args=None, locations=None):
         DirectiveLocation.INLINE_FRAGMENT,
     ]
 )
+
+"""Constant string used for default reason for a deprecation."""
+DEFAULT_DEPRECATION_REASON = 'No longer supported'
+
+"""Used to declare element of a GraphQL schema as deprecated."""
+GraphQLDeprecatedDirective = GraphQLDirective(
+    name='deprecated',
+    description='Marks an element of a GraphQL schema as no longer supported.',
+    args={
+        'reason': GraphQLArgument(
+            type=GraphQLString,
+            description=('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/).'),
+            default_value=DEFAULT_DEPRECATION_REASON
+        ),
+    },
+    locations=[
+        DirectiveLocation.FIELD_DEFINITION,
+        DirectiveLocation.ENUM_VALUE,
+    ]
+)
+
+specified_directives = [
+    GraphQLIncludeDirective,
+    GraphQLSkipDirective,
+    GraphQLDeprecatedDirective
+]

graphql/type/schema.py

@@ -5,8 +5,7 @@
 from .definition import (GraphQLInputObjectType, GraphQLInterfaceType,
                          GraphQLList, GraphQLNonNull, GraphQLObjectType,
                          GraphQLUnionType)
-from .directives import (GraphQLDirective, GraphQLIncludeDirective,
-                         GraphQLSkipDirective)
+from .directives import (GraphQLDirective, specified_directives)
 from .introspection import IntrospectionSchema
 
 
@@ -20,20 +19,19 @@ class GraphQLSchema(object):
 
         MyAppSchema = GraphQLSchema(
             query=MyAppQueryRootType,
-            mutation=MyAppMutationRootType
+            mutation=MyAppMutationRootType,
         )
 
     Note: If an array of `directives` are provided to GraphQLSchema, that will be
     the exact list of directives represented and allowed. If `directives` is not
-    provided then a default set of the built-in `[ @include, @skip ]` directives
-    will be used. If you wish to provide *additional* directives to these
-    built-ins, you must explicitly declare them. Example:
-
-      directives: [
-        myCustomDirective,
-        GraphQLIncludeDirective,
-        GraphQLSkipDirective
-      ]
+    provided then a default set of the specified directives (e.g. @include and
+    @skip) will be used. If you wish to provide *additional* directives to these
+    specified directives, you must explicitly declare them. Example:
+
+      MyAppSchema = GraphQLSchema(
+          ...
+          directives=specified_directives.extend([MyCustomerDirective]),
+      )
     """
     __slots__ = '_query', '_mutation', '_subscription', '_type_map', '_directives', '_implementations', '_possible_type_map'
 
@@ -55,10 +53,7 @@ def __init__(self, query, mutation=None, subscription=None, directives=None, typ
         self._mutation = mutation
         self._subscription = subscription
         if directives is None:
-            directives = [
-                GraphQLIncludeDirective,
-                GraphQLSkipDirective
-            ]
+            directives = specified_directives
 
         assert all(isinstance(d, GraphQLDirective) for d in directives), \
             'Schema directives must be List[GraphQLDirective] if provided but got: {}.'.format(

graphql/utils/build_ast_schema.py

@@ -8,11 +8,12 @@
                     GraphQLInt, GraphQLInterfaceType, GraphQLList,
                     GraphQLNonNull, GraphQLObjectType, GraphQLScalarType,
                     GraphQLSchema, GraphQLSkipDirective, GraphQLString,
-                    GraphQLUnionType)
+                    GraphQLUnionType, GraphQLDeprecatedDirective)
 from ..type.introspection import (__Directive, __DirectiveLocation,
                                   __EnumValue, __Field, __InputValue, __Schema,
                                   __Type, __TypeKind)
 from ..utils.value_from_ast import value_from_ast
+from ..execution.values import get_argument_values
 
 
 def _build_wrapped_type(inner_type, input_type_ast):
@@ -179,7 +180,8 @@ def make_field_def_map(definition):
         return OrderedDict(
             (f.name.value, GraphQLField(
                 type=produce_type_def(f.type),
-                args=make_input_values(f.arguments, GraphQLArgument)
+                args=make_input_values(f.arguments, GraphQLArgument),
+                deprecation_reason=get_deprecation_reason(f.directives),
             ))
             for f in definition.fields
         )
@@ -204,11 +206,11 @@ def make_interface_def(definition):
         )
 
     def make_enum_def(definition):
+        values = OrderedDict((v.name.value, GraphQLEnumValue(deprecation_reason=get_deprecation_reason(v.directives)))
+                             for v in definition.values)
         return GraphQLEnumType(
             name=definition.name.value,
-            values=OrderedDict(
-                (v.name.value, GraphQLEnumValue()) for v in definition.values
-            )
+            values=values
         )
 
     def make_union_def(definition):
@@ -246,16 +248,20 @@ def make_input_object_def(definition):
     types = [type_def_named(definition.name.value) for definition in type_defs]
     directives = [get_directive(d) for d in directive_defs]
 
-    # If skip and include were not explicitly declared, add them.
+    # If specified directive were not explicitly declared, add them.
     find_skip_directive = (directive.name for directive in directives if directive.name == 'skip')
     find_include_directive = (directive.name for directive in directives if directive.name == 'include')
+    find_deprecated_directive = (directive.name for directive in directives if directive.name == 'deprecated')
 
     if not next(find_skip_directive, None):
         directives.append(GraphQLSkipDirective)
 
     if not next(find_include_directive, None):
         directives.append(GraphQLIncludeDirective)
 
+    if not next(find_deprecated_directive, None):
+        directives.append(GraphQLDeprecatedDirective)
+
     schema_kwargs = {'query': get_object_type(ast_map[query_type_name])}
 
     if mutation_type_name:
@@ -271,3 +277,15 @@ def make_input_object_def(definition):
         schema_kwargs['types'] = types
 
     return GraphQLSchema(**schema_kwargs)
+
+
+def get_deprecation_reason(directives):
+    deprecated_ast = next((directive for directive in directives
+                          if directive.name.value == GraphQLDeprecatedDirective.name),
+                          None)
+
+    if deprecated_ast:
+        args = get_argument_values(GraphQLDeprecatedDirective.args, deprecated_ast.arguments)
+        return args['reason']
+    else:
+        return None

graphql/utils/schema_printer.py

@@ -2,6 +2,7 @@
 from ..type.definition import (GraphQLEnumType, GraphQLInputObjectType,
                                GraphQLInterfaceType, GraphQLObjectType,
                                GraphQLScalarType, GraphQLUnionType)
+from ..type.directives import DEFAULT_DEPRECATION_REASON
 from .ast_from_value import ast_from_value
 
 
@@ -14,7 +15,7 @@ def print_introspection_schema(schema):
 
 
 def is_spec_directive(directive_name):
-    return directive_name in ('skip', 'include')
+    return directive_name in ('skip', 'include', 'deprecated')
 
 
 def _is_defined_type(typename):
@@ -117,7 +118,7 @@ def _print_enum(type):
         'enum {} {{\n'
         '{}\n'
         '}}'
-    ).format(type.name, '\n'.join('  ' + v.name for v in type.get_values()))
+    ).format(type.name, '\n'.join('  ' + v.name + _print_deprecated(v) for v in type.get_values()))
 
 
 def _print_input_object(type):
@@ -129,7 +130,19 @@ def _print_input_object(type):
 
 
 def _print_fields(type):
-    return '\n'.join('  {}{}: {}'.format(f.name, _print_args(f), f.type) for f in type.get_fields().values())
+    return '\n'.join('  {}{}: {}{}'.format(f.name, _print_args(f), f.type, _print_deprecated(f))
+                     for f in type.get_fields().values())
+
+
+def _print_deprecated(field_or_enum_value):
+    reason = field_or_enum_value.deprecation_reason
+
+    if reason is None:
+        return ''
+    elif reason in ('', DEFAULT_DEPRECATION_REASON):
+        return ' @deprecated'
+    else:
+        return ' @deprecated(reason: {})'.format(print_ast(ast_from_value(reason)))
 
 
 def _print_args(field_or_directives):