pyutils: Add generic Path implementation

Replicates graphql/graphql-js@52820eb

Author: Cito

README.md

@@ -16,7 +16,7 @@ The current version 3.0.0a2 of GraphQL-core is up-to-date
 with GraphQL.js version 14.4.2.
 
 All parts of the API are covered by an extensive test suite
-of currently 1915 unit tests.
+of currently 1918 unit tests.
 
 
 ## Documentation

docs/modules/execution.rst

@@ -7,7 +7,6 @@ Execution
 
 .. autofunction:: execute
 .. autofunction:: default_field_resolver
-.. autofunction:: response_path_as_list
 
 .. autoclass:: ExecutionContext
 .. autoclass:: ExecutionResult

docs/modules/pyutils.rst

@@ -11,15 +11,20 @@ PyUtils
 .. autofunction:: dedent
 .. autofunction:: did_you_mean
 .. autoclass:: EventEmitter
+   :members:
 .. autoclass:: EventEmitterAsyncIterator
+   :members:
 .. autofunction:: identity_func
 .. autofunction:: inspect
 .. autofunction:: is_finite
 .. autofunction:: is_integer
 .. autofunction:: is_invalid
 .. autofunction:: is_nullish
 .. autoclass:: AwaitableOrValue
+   :members:
 .. autofunction:: suggestion_list
 .. autoclass:: FrozenError
 .. autoclass:: FrozenList
 .. autoclass:: FrozenDict
+.. autoclass:: Path
+   :members:

docs/modules/type.rst

@@ -100,7 +100,6 @@ Resolvers
 .. autoclass:: GraphQLIsTypeOfFn
 .. autoclass:: GraphQLResolveInfo
 .. autoclass:: GraphQLTypeResolver
-.. autoclass:: ResponsePath
 
 
 Directives

src/graphql/__init__.py

@@ -263,7 +263,6 @@
     execute,
     default_field_resolver,
     default_type_resolver,
-    response_path_as_list,
     get_directive_values,
     # Types
     ExecutionContext,
@@ -589,7 +588,6 @@
     "execute",
     "default_field_resolver",
     "default_type_resolver",
-    "response_path_as_list",
     "get_directive_values",
     "ExecutionContext",
     "ExecutionResult",

src/graphql/execution/__init__.py

@@ -8,7 +8,6 @@
     execute,
     default_field_resolver,
     default_type_resolver,
-    response_path_as_list,
     ExecutionContext,
     ExecutionResult,
     Middleware,
@@ -22,7 +21,6 @@
     "execute",
     "default_field_resolver",
     "default_type_resolver",
-    "response_path_as_list",
     "ExecutionContext",
     "ExecutionResult",
     "Middleware",

src/graphql/execution/execute.py

@@ -26,7 +26,14 @@
     OperationType,
     SelectionSetNode,
 )
-from ..pyutils import inspect, is_invalid, is_nullish, AwaitableOrValue, FrozenList
+from ..pyutils import (
+    inspect,
+    is_invalid,
+    is_nullish,
+    AwaitableOrValue,
+    FrozenList,
+    Path,
+)
 from ..utilities import get_operation_root_type, type_from_ast
 from ..type import (
     GraphQLAbstractType,
@@ -42,7 +49,6 @@
     GraphQLFieldResolver,
     GraphQLTypeResolver,
     GraphQLResolveInfo,
-    ResponsePath,
     SchemaMetaFieldDef,
     TypeMetaFieldDef,
     TypeNameMetaFieldDef,
@@ -57,13 +63,11 @@
 from .values import get_argument_values, get_directive_values, get_variable_values
 
 __all__ = [
-    "add_path",
     "assert_valid_execution_arguments",
     "default_field_resolver",
     "default_type_resolver",
     "execute",
     "get_field_def",
-    "response_path_as_list",
     "ExecutionResult",
     "ExecutionContext",
     "Middleware",
@@ -100,6 +104,7 @@ class ExecutionResult(NamedTuple):
     errors: Optional[List[GraphQLError]]
 
 
+# noinspection PyTypeHints
 ExecutionResult.__new__.__defaults__ = (None, None)  # type: ignore
 
 Middleware = Optional[Union[Tuple, List, MiddlewareManager]]
@@ -377,7 +382,7 @@ def execute_fields_serially(
         self,
         parent_type: GraphQLObjectType,
         source_value: Any,
-        path: Optional[ResponsePath],
+        path: Optional[Path],
         fields: Dict[str, List[FieldNode]],
     ) -> AwaitableOrValue[Dict[str, Any]]:
         """Execute the given fields serially.
@@ -386,7 +391,7 @@ def execute_fields_serially(
         """
         results: Dict[str, Any] = {}
         for response_name, field_nodes in fields.items():
-            field_path = add_path(path, response_name)
+            field_path = Path(path, response_name)
             result = self.resolve_field(
                 parent_type, source_value, field_nodes, field_path
             )
@@ -427,7 +432,7 @@ def execute_fields(
         self,
         parent_type: GraphQLObjectType,
         source_value: Any,
-        path: Optional[ResponsePath],
+        path: Optional[Path],
         fields: Dict[str, List[FieldNode]],
     ) -> AwaitableOrValue[Dict[str, Any]]:
         """Execute the given fields concurrently.
@@ -438,7 +443,7 @@ def execute_fields(
         awaitable_fields: List[str] = []
         append_awaitable = awaitable_fields.append
         for response_name, field_nodes in fields.items():
-            field_path = add_path(path, response_name)
+            field_path = Path(path, response_name)
             result = self.resolve_field(
                 parent_type, source_value, field_nodes, field_path
             )
@@ -559,7 +564,7 @@ def build_resolve_info(
         field_def: GraphQLField,
         field_nodes: List[FieldNode],
         parent_type: GraphQLObjectType,
-        path: ResponsePath,
+        path: Path,
     ) -> GraphQLResolveInfo:
         # The resolve function's first argument is a collection of information about
         # the current execution state.
@@ -582,7 +587,7 @@ def resolve_field(
         parent_type: GraphQLObjectType,
         source: Any,
         field_nodes: List[FieldNode],
-        path: ResponsePath,
+        path: Path,
     ) -> AwaitableOrValue[Any]:
         """Resolve the field on the given source object.
 
@@ -652,7 +657,7 @@ def complete_value_catching_error(
         return_type: GraphQLOutputType,
         field_nodes: List[FieldNode],
         info: GraphQLResolveInfo,
-        path: ResponsePath,
+        path: Path,
         result: Any,
     ) -> AwaitableOrValue[Any]:
         """Complete a value while catching an error.
@@ -694,10 +699,10 @@ def handle_field_error(
         self,
         raw_error: Exception,
         field_nodes: List[FieldNode],
-        path: ResponsePath,
+        path: Path,
         return_type: GraphQLOutputType,
     ) -> None:
-        error = located_error(raw_error, field_nodes, response_path_as_list(path))
+        error = located_error(raw_error, field_nodes, path.as_list())
 
         # If the field type is non-nullable, then it is resolved without any protection
         # from errors, however it still properly locates the error.
@@ -713,7 +718,7 @@ def complete_value(
         return_type: GraphQLOutputType,
         field_nodes: List[FieldNode],
         info: GraphQLResolveInfo,
-        path: ResponsePath,
+        path: Path,
         result: Any,
     ) -> AwaitableOrValue[Any]:
         """Complete a value.
@@ -797,7 +802,7 @@ def complete_list_value(
         return_type: GraphQLList[GraphQLOutputType],
         field_nodes: List[FieldNode],
         info: GraphQLResolveInfo,
-        path: ResponsePath,
+        path: Path,
         result: Iterable[Any],
     ) -> AwaitableOrValue[Any]:
         """Complete a list value.
@@ -821,7 +826,7 @@ def complete_list_value(
         for index, item in enumerate(result):
             # No need to modify the info object containing the path, since from here on
             # it is not ever accessed by resolver functions.
-            field_path = add_path(path, index)
+            field_path = path.add_key(index)
             completed_item = self.complete_value_catching_error(
                 item_type, field_nodes, info, field_path, item
             )
@@ -866,7 +871,7 @@ def complete_abstract_value(
         return_type: GraphQLAbstractType,
         field_nodes: List[FieldNode],
         info: GraphQLResolveInfo,
-        path: ResponsePath,
+        path: Path,
         result: Any,
     ) -> AwaitableOrValue[Any]:
         """Complete an abstract value.
@@ -947,7 +952,7 @@ def complete_object_value(
         return_type: GraphQLObjectType,
         field_nodes: List[FieldNode],
         info: GraphQLResolveInfo,
-        path: ResponsePath,
+        path: Path,
         result: Any,
     ) -> AwaitableOrValue[Dict[str, Any]]:
         """Complete an Object value by executing all sub-selections."""
@@ -981,7 +986,7 @@ def collect_and_execute_subfields(
         self,
         return_type: GraphQLObjectType,
         field_nodes: List[FieldNode],
-        path: ResponsePath,
+        path: Path,
         result: Any,
     ) -> AwaitableOrValue[Dict[str, Any]]:
         """Collect sub-fields to execute to complete this value."""
@@ -1041,29 +1046,6 @@ def assert_valid_execution_arguments(
         )
 
 
-def response_path_as_list(path: ResponsePath) -> List[Union[str, int]]:
-    """Get response path as a list.
-
-    Given a ResponsePath (found in the `path` entry in the information provided as the
-    last argument to a field resolver), return a list of the path keys.
-    """
-    flattened: List[Union[str, int]] = []
-    append = flattened.append
-    curr: Optional[ResponsePath] = path
-    while curr:
-        append(curr.key)
-        curr = curr.prev
-    return flattened[::-1]
-
-
-def add_path(prev: Optional[ResponsePath], key: Union[str, int]) -> ResponsePath:
-    """Add a key to a response path.
-
-    Given a ResponsePath and a key, return a new ResponsePath containing the new key.
-    """
-    return ResponsePath(prev, key)
-
-
 def get_field_def(
     schema: GraphQLSchema, parent_type: GraphQLObjectType, field_name: str
 ) -> GraphQLField:

src/graphql/pyutils/__init__.py

@@ -24,6 +24,7 @@
 from .frozen_error import FrozenError
 from .frozen_list import FrozenList
 from .frozen_dict import FrozenDict
+from .path import Path
 
 __all__ = [
     "camel_to_snake",
@@ -44,4 +45,5 @@
     "FrozenError",
     "FrozenList",
     "FrozenDict",
+    "Path",
 ]

src/graphql/pyutils/path.py

@@ -0,0 +1,26 @@
+from typing import Any, List, NamedTuple, Union
+
+__all__ = ["Path"]
+
+
+class Path(NamedTuple):
+    """A generic path of string or integer indices"""
+
+    prev: Any  # Optional['Path'] (python/mypy/issues/731)
+    """path with the previous indices"""
+    key: Union[str, int]
+    """current index in the path (string or integer)"""
+
+    def add_key(self, key: Union[str, int]) -> "Path":
+        """Return a new Path containing the given key."""
+        return Path(self, key)
+
+    def as_list(self) -> List[Union[str, int]]:
+        """Return a list of the path keys."""
+        flattened: List[Union[str, int]] = []
+        append = flattened.append
+        curr: Path = self
+        while curr:
+            append(curr.key)
+            curr = curr.prev
+        return flattened[::-1]

src/graphql/subscription/subscribe.py

@@ -3,15 +3,14 @@
 
 from ..error import GraphQLError, located_error
 from ..execution.execute import (
-    add_path,
     assert_valid_execution_arguments,
     execute,
     get_field_def,
-    response_path_as_list,
     ExecutionContext,
     ExecutionResult,
 )
 from ..language import DocumentNode
+from ..pyutils import Path
 from ..type import GraphQLFieldResolver, GraphQLSchema
 from ..utilities import get_operation_root_type
 from .map_async_iterator import MapAsyncIterator
@@ -153,7 +152,7 @@ async def create_source_event_stream(
     # AsyncIterable yielding raw payloads.
     resolve_fn = field_def.subscribe or context.field_resolver
 
-    path = add_path(None, response_name)
+    path = Path(None, response_name)
 
     info = context.build_resolve_info(field_def, field_nodes, type_, path)
 
@@ -166,7 +165,7 @@ async def create_source_event_stream(
     event_stream = await cast(Awaitable, result) if isawaitable(result) else result
     # If `event_stream` is an Error, rethrow a located error.
     if isinstance(event_stream, Exception):
-        raise located_error(event_stream, field_nodes, response_path_as_list(path))
+        raise located_error(event_stream, field_nodes, path.as_list())
 
     # Assert field returned an event stream, otherwise yield an error.
     if isinstance(event_stream, AsyncIterable):

src/graphql/type/__init__.py

@@ -3,6 +3,8 @@
 The :mod:`graphql.type` package is responsible for defining GraphQL types and schema.
 """
 
+from ..pyutils import Path as ResponsePath
+
 from .schema import (
     # Predicate
     is_schema,
@@ -91,7 +93,6 @@
     GraphQLTypeResolver,
     GraphQLIsTypeOfFn,
     GraphQLResolveInfo,
-    ResponsePath,
 )
 
 from .directives import (