Add NoDeprecatedCustomRule and deprecate find_deprecated_usages

Replicates graphql/graphql-js@9735ac7

Author: Cito

src/graphql/__init__.py

@@ -321,6 +321,7 @@
     UniqueDirectiveNamesRule,
     PossibleTypeExtensionsRule,
     # Custom validation rules
+    NoDeprecatedCustomRule,
     NoSchemaIntrospectionCustomRule,
 )
 
@@ -398,6 +399,8 @@
     DangerousChangeType,
     find_breaking_changes,
     find_dangerous_changes,
+    # Report all deprecated usages within a GraphQL document (deprecated).
+    find_deprecated_usages,
 )
 
 # Utilities for compatibility with the Python language.
@@ -656,6 +659,7 @@
     "UniqueFieldDefinitionNamesRule",
     "UniqueDirectiveNamesRule",
     "PossibleTypeExtensionsRule",
+    "NoDeprecatedCustomRule",
     "NoSchemaIntrospectionCustomRule",
     "GraphQLError",
     "GraphQLSyntaxError",
@@ -691,6 +695,7 @@
     "is_valid_name_error",
     "find_breaking_changes",
     "find_dangerous_changes",
+    "find_deprecated_usages",
     "BreakingChange",
     "BreakingChangeType",
     "DangerousChange",

src/graphql/utilities/__init__.py

@@ -81,7 +81,7 @@
     find_dangerous_changes,
 )
 
-# Report all deprecated usages within a GraphQL document.
+# Report all deprecated usages within a GraphQL document (deprecated).
 from .find_deprecated_usages import find_deprecated_usages
 
 __all__ = [

src/graphql/utilities/find_deprecated_usages.py

@@ -1,56 +1,25 @@
-from typing import Any, List
+from typing import List
 
 from ..error import GraphQLError
-from ..language import DocumentNode, EnumValueNode, FieldNode, Visitor, visit
-from ..type import GraphQLSchema, get_named_type
-from .type_info import TypeInfo, TypeInfoVisitor
-
+from ..language import DocumentNode
+from ..type import GraphQLSchema
 
 __all__ = ["find_deprecated_usages"]
 
 
 def find_deprecated_usages(
     schema: GraphQLSchema, ast: DocumentNode
-) -> List[GraphQLError]:
-    """Get a list of GraphQLError instances describing each deprecated use."""
-
-    type_info = TypeInfo(schema)
-    visitor = FindDeprecatedUsages(type_info)
-    visit(ast, TypeInfoVisitor(type_info, visitor))
-    return visitor.errors
-
-
-class FindDeprecatedUsages(Visitor):
-    """A validation rule which reports deprecated usages."""
-
-    type_info: TypeInfo
-    errors: List[GraphQLError]
-
-    def __init__(self, type_info: TypeInfo):
-        super().__init__()
-        self.type_info = type_info
-        self.errors = []
-
-    def enter_field(self, node: FieldNode, *_args: Any) -> None:
-        parent_type = self.type_info.get_parent_type()
-        field_def = self.type_info.get_field_def()
-        if parent_type and field_def and field_def.deprecation_reason is not None:
-            self.errors.append(
-                GraphQLError(
-                    f"The field '{parent_type.name}.{node.name.value}'"
-                    " is deprecated. " + field_def.deprecation_reason,
-                    node,
-                )
-            )
-
-    def enter_enum_value(self, node: EnumValueNode, *_args: Any) -> None:
-        type_ = get_named_type(self.type_info.get_input_type())
-        enum_val = self.type_info.get_enum_value()
-        if type_ and enum_val and enum_val.deprecation_reason is not None:
-            self.errors.append(
-                GraphQLError(
-                    f"The enum value '{type_.name}.{node.value}'"
-                    " is deprecated. " + enum_val.deprecation_reason,
-                    node,
-                )
-            )
+) -> List[GraphQLError]:  # pragma: no cover
+    """Get a list of GraphQLError instances describing each deprecated use.
+
+    .. deprecated:: 3.1.3
+
+    Please use ``validate`` with ``NoDeprecatedCustomRule`` instead::
+
+        from graphql import validate, NoDeprecatedCustomRule
+
+        errors = validate(schema, document, [NoDeprecatedCustomRule])
+    """
+    from ..validation import validate, NoDeprecatedCustomRule
+
+    return validate(schema, ast, [NoDeprecatedCustomRule])

src/graphql/validation/__init__.py

@@ -105,6 +105,7 @@
 from .rules.possible_type_extensions import PossibleTypeExtensionsRule
 
 # Optional rules not defined by the GraphQL Specification
+from .rules.custom.no_deprecated import NoDeprecatedCustomRule
 from .rules.custom.no_schema_introspection import NoSchemaIntrospectionCustomRule
 
 __all__ = [
@@ -149,5 +150,6 @@
     "UniqueFieldDefinitionNamesRule",
     "UniqueDirectiveNamesRule",
     "PossibleTypeExtensionsRule",
+    "NoDeprecatedCustomRule",
     "NoSchemaIntrospectionCustomRule",
 ]

src/graphql/validation/rules/custom/no_deprecated.py

@@ -0,0 +1,46 @@
+from typing import Any
+
+from ....error import GraphQLError
+from ....language import FieldNode, EnumValueNode
+from ....type import get_named_type
+from .. import ValidationRule
+
+__all__ = ["NoDeprecatedCustomRule"]
+
+
+class NoDeprecatedCustomRule(ValidationRule):
+    """No deprecated
+
+    A GraphQL document is only valid if all selected fields and all used enum values
+    have not been deprecated.
+
+    Note: This rule is optional and is not part of the Validation section of the GraphQL
+    Specification. The main purpose of this rule is detection of deprecated usages and
+    not necessarily to forbid their use when querying a service.
+    """
+
+    def enter_field(self, node: FieldNode, *_args: Any) -> None:
+        context = self.context
+        field_def = context.get_field_def()
+        parent_type = context.get_parent_type()
+        if parent_type and field_def and field_def.deprecation_reason is not None:
+            self.report_error(
+                GraphQLError(
+                    f"The field {parent_type.name}.{node.name.value}"
+                    f" is deprecated. {field_def.deprecation_reason}",
+                    node,
+                )
+            )
+
+    def enter_enum_value(self, node: EnumValueNode, *_args: Any) -> None:
+        context = self.context
+        type_ = get_named_type(context.get_input_type())
+        enum_val = context.get_enum_value()
+        if type_ and enum_val and enum_val.deprecation_reason is not None:
+            self.report_error(
+                GraphQLError(
+                    f"The enum value '{type_.name}.{node.value}'"
+                    f" is deprecated. {enum_val.deprecation_reason}",
+                    node,
+                )
+            )

src/graphql/validation/validation_context.py

@@ -1,6 +1,5 @@
 from typing import Any, Callable, Dict, List, NamedTuple, Optional, Set, Union, cast
 
-from .. import GraphQLDirective
 from ..error import GraphQLError
 from ..language import (
     DocumentNode,
@@ -16,6 +15,8 @@
 from ..type import (
     GraphQLArgument,
     GraphQLCompositeType,
+    GraphQLDirective,
+    GraphQLEnumValue,
     GraphQLField,
     GraphQLInputType,
     GraphQLOutputType,
@@ -241,3 +242,6 @@ def get_directive(self) -> Optional[GraphQLDirective]:
 
     def get_argument(self) -> Optional[GraphQLArgument]:
         return self._type_info.get_argument()
+
+    def get_enum_value(self) -> Optional[GraphQLEnumValue]:
+        return self._type_info.get_enum_value()

tests/utilities/test_find_deprecated_usages.py

@@ -0,0 +1,119 @@
+from functools import partial
+
+from graphql.utilities import build_schema
+from graphql.validation import NoDeprecatedCustomRule
+
+from .harness import assert_validation_errors
+
+schema = build_schema(
+    """
+    enum EnumType {
+      NORMAL_VALUE
+      DEPRECATED_VALUE @deprecated(reason: "Some enum reason.")
+      DEPRECATED_VALUE_WITH_NO_REASON @deprecated
+    }
+
+    type Query {
+      normalField(enumArg: [EnumType]): String
+      deprecatedField: String @deprecated(reason: "Some field reason.")
+      deprecatedFieldWithNoReason: String @deprecated
+    }
+    """
+)
+
+assert_errors = partial(assert_validation_errors, NoDeprecatedCustomRule, schema=schema)
+
+assert_valid = partial(assert_errors, errors=[])
+
+
+def describe_validate_no_deprecated():
+    def ignores_fields_and_enum_values_that_are_not_deprecated():
+        assert_valid(
+            """
+            {
+              normalField(enumArg: [NORMAL_VALUE])
+            }
+            """
+        )
+
+    def ignores_unknown_fields_and_enum_values():
+        assert_valid(
+            """
+            fragment UnknownFragment on UnknownType {
+              unknownField(unknownArg: UNKNOWN_VALUE)
+            }
+
+            fragment QueryFragment on Query {
+              unknownField(unknownArg: UNKNOWN_VALUE)
+              normalField(enumArg: UNKNOWN_VALUE)
+            }
+            """
+        )
+
+    def reports_error_when_a_deprecated_field_is_selected():
+        assert_errors(
+            """
+            {
+              normalField
+              deprecatedField
+              deprecatedFieldWithNoReason
+            }
+            """,
+            [
+                {
+                    "message": "The field Query.deprecatedField is deprecated."
+                    " Some field reason.",
+                    "locations": [(4, 15)],
+                },
+                {
+                    "message": "The field Query.deprecatedFieldWithNoReason"
+                    " is deprecated. No longer supported",
+                    "locations": [(5, 15)],
+                },
+            ],
+        )
+
+    def reports_error_when_a_deprecated_enum_value_is_used():
+        assert_errors(
+            """
+            {
+              normalField(enumArg: [NORMAL_VALUE, DEPRECATED_VALUE])
+              normalField(enumArg: [DEPRECATED_VALUE_WITH_NO_REASON])
+            }
+            """,
+            [
+                {
+                    "message": "The enum value 'EnumType.DEPRECATED_VALUE'"
+                    " is deprecated. Some enum reason.",
+                    "locations": [(3, 51)],
+                },
+                {
+                    "message": "The enum value"
+                    " 'EnumType.DEPRECATED_VALUE_WITH_NO_REASON'"
+                    " is deprecated. No longer supported",
+                    "locations": [(4, 37)],
+                },
+            ],
+        )
+
+    def reports_error_when_deprecated_field_or_enum_value_is_used_inside_a_fragment():
+        assert_errors(
+            """
+            fragment QueryFragment on Query {
+              deprecatedField
+              normalField(enumArg: [NORMAL_VALUE, DEPRECATED_VALUE])
+            }
+            """,
+            [
+                {
+                    "message": "The field Query.deprecatedField is deprecated."
+                    " Some field reason.",
+                    "locations": [(3, 15)],
+                },
+                {
+                    "message": "The enum value 'EnumType.DEPRECATED_VALUE'"
+                    " is deprecated. Some enum reason.",
+                    "locations": [(4, 51)],
+                },
+            ],
+        )