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))

src/graphql/pyutils/inspect.py

@@ -1,10 +1,10 @@
 from typing import Any
 
-from ..error import INVALID
+from .undefined import Undefined
 
 __all__ = ["is_invalid"]
 
 
 def is_invalid(value: Any) -> bool:
     """Return true if a value is undefined, or NaN."""
-    return value is INVALID or value != value
+    return value is Undefined or value != value

src/graphql/pyutils/is_invalid.py

@@ -1,13 +1,15 @@
 from math import isnan
 from typing import Any
 
-from ..error import INVALID
+from .undefined import Undefined
 
 __all__ = ["is_nullish"]
 
 
 def is_nullish(value: Any) -> bool:
     """Return true if a value is null, undefined, or NaN."""
     return (
-        value is None or value is INVALID or (isinstance(value, float) and isnan(value))
+        value is None
+        or value is Undefined
+        or (isinstance(value, float) and isnan(value))
     )

src/graphql/pyutils/is_nullish.py

@@ -0,0 +1,32 @@
+__all__ = ["Undefined", "UndefinedType"]
+
+
+class UndefinedType(ValueError):
+    """Auxiliary class for creating the Undefined singleton."""
+
+    def __repr__(self):
+        return "Undefined"
+
+    __str__ = __repr__
+
+    def __hash__(self):
+        return hash(UndefinedType)
+
+    def __bool__(self):
+        return False
+
+    def __eq__(self, other):
+        return other is Undefined
+
+    def __ne__(self, other):
+        return not self == other
+
+
+# Used to indicate undefined or invalid values (like "undefined" in JavaScript):
+Undefined = UndefinedType()
+
+Undefined.__doc__ = """Symbol for undefined values
+
+This singleton object is used to describe undefined or invalid  values.
+It can be used in places where you would use ``undefined`` in GraphQL.js.
+"""