Use 'Undefined' instead of 'INVALID'

This is more similar to undefined in JavaScript and
to the spelling of None in Python as capitalized word.

INVALID can still be imported as an alias from the root level,
but is now considered deprecated.

Author: Cito

docs/modules/error.rst

@@ -13,5 +13,3 @@ Error
 .. autofunction:: format_error
 .. autofunction:: located_error
 .. autofunction:: print_error
-
-.. autodata:: INVALID

docs/modules/pyutils.rst

@@ -31,3 +31,5 @@ PyUtils
 .. autoclass:: Path
    :members:
 .. autofunction:: print_path_list
+
+.. autodata:: Undefined

src/graphql/__init__.py

@@ -327,7 +327,6 @@
     located_error,
     format_error,
     print_error,
-    INVALID,
 )
 
 # Utilities for operating on GraphQL type schema and parsed sources.
@@ -397,6 +396,11 @@
     find_dangerous_changes,
 )
 
+# Utilities for compatibility with the Python language.
+from .pyutils import Undefined, UndefinedType
+
+INVALID = Undefined  # deprecated alias
+
 # The GraphQL-core version info.
 __version__ = version
 __version_info__ = version_info
@@ -651,7 +655,6 @@
     "located_error",
     "format_error",
     "print_error",
-    "INVALID",
     "get_introspection_query",
     "get_operation_ast",
     "get_operation_root_type",
@@ -685,4 +688,6 @@
     "BreakingChangeType",
     "DangerousChange",
     "DangerousChangeType",
+    "Undefined",
+    "UndefinedType",
 ]

src/graphql/error/__init__.py

@@ -12,11 +12,7 @@
 
 from .format_error import format_error
 
-from .invalid import INVALID, InvalidType
-
 __all__ = [
-    "INVALID",
-    "InvalidType",
     "GraphQLError",
     "GraphQLSyntaxError",
     "format_error",

src/graphql/error/invalid.py

@@ -15,7 +15,7 @@
     cast,
 )
 
-from ..error import GraphQLError, INVALID, located_error
+from ..error import GraphQLError, located_error
 from ..language import (
     DocumentNode,
     FieldNode,
@@ -33,6 +33,7 @@
     AwaitableOrValue,
     FrozenList,
     Path,
+    Undefined,
 )
 from ..utilities.get_operation_root_type import get_operation_root_type
 from ..utilities.type_from_ast import type_from_ast
@@ -382,7 +383,7 @@ def execute_fields_serially(
             result = self.resolve_field(
                 parent_type, source_value, field_nodes, field_path
             )
-            if result is INVALID:
+            if result is Undefined:
                 continue
             if isawaitable(results):
                 # noinspection PyShadowingNames
@@ -434,7 +435,7 @@ def execute_fields(
             result = self.resolve_field(
                 parent_type, source_value, field_nodes, field_path
             )
-            if result is not INVALID:
+            if result is not Undefined:
                 results[response_name] = result
                 if isawaitable(result):
                     append_awaitable(response_name)
@@ -592,7 +593,7 @@ def resolve_field(
 
         field_def = get_field_def(self.schema, parent_type, field_name)
         if not field_def:
-            return INVALID
+            return Undefined
 
         resolve_fn = field_def.resolve or self.field_resolver
 
@@ -762,7 +763,7 @@ def complete_value(
                 )
             return completed
 
-        # If result value is null-ish (null, INVALID, or NaN) then return null.
+        # If result value is null-ish (null, Undefined, or NaN) then return null.
         if is_nullish(result):
             return None
 

src/graphql/execution/execute.py

@@ -1,6 +1,6 @@
 from typing import Any, Callable, Dict, List, Optional, Union, cast
 
-from ..error import GraphQLError, INVALID
+from ..error import GraphQLError
 from ..language import (
     DirectiveNode,
     ExecutableDefinitionNode,
@@ -14,7 +14,7 @@
     VariableNode,
     print_ast,
 )
-from ..pyutils import inspect, print_path_list, FrozenList
+from ..pyutils import inspect, print_path_list, FrozenList, Undefined
 from ..type import (
     GraphQLDirective,
     GraphQLField,
@@ -161,7 +161,7 @@ def get_argument_values(
         argument_node = arg_node_map.get(name)
 
         if argument_node is None:
-            if arg_def.default_value is not INVALID:
+            if arg_def.default_value is not Undefined:
                 coerced_values[arg_def.out_name or name] = arg_def.default_value
             elif is_non_null_type(arg_type):
                 raise GraphQLError(
@@ -177,7 +177,7 @@ def get_argument_values(
         if isinstance(value_node, VariableNode):
             variable_name = value_node.name.value
             if variable_values is None or variable_name not in variable_values:
-                if arg_def.default_value is not INVALID:
+                if arg_def.default_value is not Undefined:
                     coerced_values[arg_def.out_name or name] = arg_def.default_value
                 elif is_non_null_type(arg_type):
                     raise GraphQLError(
@@ -196,7 +196,7 @@ def get_argument_values(
             )
 
         coerced_value = value_from_ast(value_node, arg_type, variable_values)
-        if coerced_value is INVALID:
+        if coerced_value is Undefined:
             # Note: `values_of_correct_type` validation should catch this before
             # execution. This is a runtime check to ensure execution does not
             # continue with an invalid argument value.

src/graphql/execution/values.py

@@ -33,6 +33,7 @@
 from .frozen_dict import FrozenDict
 from .path import Path
 from .print_path_list import print_path_list
+from .undefined import Undefined, UndefinedType
 
 __all__ = [
     "camel_to_snake",
@@ -60,4 +61,6 @@
     "FrozenDict",
     "Path",
     "print_path_list",
+    "Undefined",
+    "UndefinedType",
 ]

src/graphql/pyutils/__init__.py

@@ -1,13 +1,13 @@
 from typing import cast, Any, TypeVar
 
-from ..error import INVALID
+from .undefined import Undefined
 
 __all__ = ["identity_func"]
 
 
 T = TypeVar("T")
 
 
-def identity_func(x: T = cast(Any, INVALID), *_args: Any) -> T:
+def identity_func(x: T = cast(Any, Undefined), *_args: Any) -> T:
     """Return the first received argument."""
     return x

src/graphql/pyutils/identity_func.py

@@ -11,7 +11,7 @@
 )
 from typing import Any, List
 
-from ..error import INVALID
+from .undefined import Undefined
 
 __all__ = ["inspect"]
 
@@ -35,7 +35,7 @@ def inspect(value: Any) -> str:
 
 
 def inspect_recursive(value: Any, seen_values: List) -> str:
-    if value is None or value is INVALID or isinstance(value, (bool, float, complex)):
+    if value is None or value is Undefined or isinstance(value, (bool, float, complex)):
         return repr(value)
     if isinstance(value, (int, str, bytes, bytearray)):
         return trunc_str(repr(value))