refactor(execution): track pending work

GraphQL-core needs no AsyncWorkTracker class or shared execution context:
the Executor's existing background-settling machinery (settle_in_background
plus background_futures) already serves as the tracker; it is exposed to
resolvers via the new async_helpers field on GraphQLResolveInfo instead of
a getAsyncHelpers getter.

Replicates graphql/graphql-js@2e97665

Author: Cito

docs/modules/type.rst

@@ -112,6 +112,7 @@ Resolvers
 .. autoclass:: GraphQLFieldResolver
 .. autoclass:: GraphQLIsTypeOfFn
 .. autoclass:: GraphQLResolveInfo
+.. autoclass:: GraphQLResolveInfoHelpers
 .. autoclass:: GraphQLTypeResolver
 
 

src/graphql/__init__.py

@@ -407,6 +407,7 @@
     GraphQLDefaultInput,
     GraphQLIsTypeOfFn,
     GraphQLResolveInfo,
+    GraphQLResolveInfoHelpers,
     ResponsePath,
     GraphQLTypeResolver,
     # Keyword args
@@ -649,6 +650,7 @@
     "GraphQLOutputType",
     "GraphQLParseFn",
     "GraphQLResolveInfo",
+    "GraphQLResolveInfoHelpers",
     "GraphQLScalarInputLiteralCoercer",
     "GraphQLScalarInputValueCoercer",
     "GraphQLScalarLiteralParser",

src/graphql/execution/execute.py

@@ -31,7 +31,6 @@
     Any,
     Generic,
     NamedTuple,
-    NoReturn,
     TypeVar,
     cast,
 )
@@ -71,6 +70,7 @@
     GraphQLObjectType,
     GraphQLOutputType,
     GraphQLResolveInfo,
+    GraphQLResolveInfoHelpers,
     GraphQLSchema,
     GraphQLStreamDirective,
     GraphQLTypeResolver,
@@ -218,6 +218,7 @@ class Executor(IncrementalPublisherContext):
     enable_early_execution: bool
     hide_suggestions: bool
     abort_signal: AbortSignal | None
+    async_helpers: GraphQLResolveInfoHelpers
     errors: list[GraphQLError] | None
     cancellable_streams: set[CancellableStreamRecord] | None
     pending_incremental_futures: set[Future[Any]]
@@ -267,6 +268,7 @@ def __init__(  # noqa: PLR0913
         self.enable_early_execution = enable_early_execution
         self.hide_suggestions = hide_suggestions
         self.abort_signal = abort_signal
+        self.async_helpers = GraphQLResolveInfoHelpers(track=self.track_async_work)
         self.middleware_manager = middleware_manager
         self.error_propagation = not any(
             directive.name.value == GraphQLDisableErrorPropagationDirective.name
@@ -817,6 +819,7 @@ def build_resolve_info(
             self.context_value,
             self.is_awaitable,
             self.abort_signal,
+            self.async_helpers,
         )
 
     def handle_field_error(
@@ -1061,6 +1064,20 @@ def settle_in_background(self, awaitables: list[Awaitable[Any]]) -> None:
         background_futures.add(future)
         future.add_done_callback(background_futures.discard)
 
+    def track_async_work(self, values: Sequence[Any]) -> None:
+        """Track possibly awaitable values as pending asynchronous work.
+
+        Awaitables among the given values are settled in the background, so that
+        they are still settled and their errors observed when they would otherwise
+        be abandoned. Non-awaitable values are ignored.
+        """
+        is_awaitable = self.is_awaitable
+        awaitables: list[Awaitable[Any]] = [
+            value for value in values if is_awaitable(value)
+        ]
+        if awaitables:
+            self.settle_in_background(awaitables)
+
     def cancellable_iterable(self, iterable: AsyncIterable[T]) -> AsyncIterable[T]:
         """Wrap an async iterable so pending iteration is cancelled on abort.
 
@@ -2709,25 +2726,13 @@ def default_type_resolver(
                     append_awaitable_type(type_)
                 elif is_type_of_result:
                     if awaitable_is_type_of_results:
-
-                        async def await_is_type_of_and_return_type(
-                            resolved_type_name: str = type_.name,
-                        ) -> str:
-                            with suppress(Exception):
-                                await gather_with_cancel(*awaitable_is_type_of_results)
-                            return resolved_type_name
-
-                        return await_is_type_of_and_return_type()
+                        info.async_helpers.track(awaitable_is_type_of_results)
                     return type_.name
-    except Exception as error:
+    except Exception:
         if awaitable_is_type_of_results:
-            # Settle the pending isTypeOf results so that their errors can be
-            # observed before they would be orphaned.
-            async def settle_and_raise(error: Exception = error) -> NoReturn:
-                await gather(*awaitable_is_type_of_results, return_exceptions=True)
-                raise error  # noqa: TRY201
-
-            return settle_and_raise()
+            # Settle the pending isTypeOf results in the background so that
+            # their errors can be observed before they would be orphaned.
+            info.async_helpers.track(awaitable_is_type_of_results)
         raise
 
     if awaitable_is_type_of_results:

src/graphql/type/__init__.py

@@ -133,6 +133,7 @@
     GraphQLTypeResolver,
     GraphQLIsTypeOfFn,
     GraphQLResolveInfo,
+    GraphQLResolveInfoHelpers,
 )
 
 from .directives import (
@@ -246,6 +247,7 @@
     "GraphQLOneOfDirective",
     "GraphQLOutputType",
     "GraphQLResolveInfo",
+    "GraphQLResolveInfoHelpers",
     "GraphQLScalarInputLiteralCoercer",
     "GraphQLScalarInputValueCoercer",
     "GraphQLScalarLiteralParser",

src/graphql/type/definition.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from collections.abc import Awaitable, Callable, Collection, Mapping
+from collections.abc import Awaitable, Callable, Collection, Mapping, Sequence
 from enum import Enum
 from typing import (
     TYPE_CHECKING,
@@ -110,6 +110,7 @@
     "GraphQLObjectTypeKwargs",
     "GraphQLOutputType",
     "GraphQLResolveInfo",
+    "GraphQLResolveInfoHelpers",
     "GraphQLScalarInputLiteralCoercer",
     "GraphQLScalarInputValueCoercer",
     "GraphQLScalarLiteralParser",
@@ -630,6 +631,18 @@ def assert_field(field: Any) -> GraphQLField:
 
 TContext = TypeVar("TContext")  # pylint: disable=invalid-name
 
+
+class GraphQLResolveInfoHelpers(NamedTuple):
+    """Helpers for resolvers to interact with the execution engine.
+
+    The ``track`` helper registers possibly awaitable values as pending
+    asynchronous work of the execution, so that they are still settled and
+    their errors observed when they would otherwise be abandoned.
+    """
+
+    track: Callable[[Sequence[Any]], None]
+
+
 try:
 
     class GraphQLResolveInfo(NamedTuple, Generic[TContext]):  # pyright: ignore
@@ -656,6 +669,7 @@ class GraphQLResolveInfo(NamedTuple, Generic[TContext]):  # pyright: ignore
         context: TContext
         is_awaitable: Callable[[Any], TypeGuard[Awaitable]]
         abort_signal: AbortSignal | None
+        async_helpers: GraphQLResolveInfoHelpers
 except TypeError as error:  # pragma: no cover
     if "Multiple inheritance with NamedTuple is not supported" not in str(error):
         raise  # only catch expected error for Python 3.10
@@ -684,6 +698,7 @@ class GraphQLResolveInfo(NamedTuple):  # type: ignore[no-redef]
         context: Any
         is_awaitable: Callable[[Any], TypeGuard[Awaitable]]
         abort_signal: AbortSignal | None
+        async_helpers: GraphQLResolveInfoHelpers
 
 
 # Note: Contrary to the Javascript implementation of GraphQLFieldResolver,

tests/execution/test_executor.py

@@ -26,6 +26,7 @@
     GraphQLNonNull,
     GraphQLObjectType,
     GraphQLResolveInfo,
+    GraphQLResolveInfoHelpers,
     GraphQLScalarType,
     GraphQLSchema,
     GraphQLStreamDirective,
@@ -254,6 +255,13 @@ def resolve(_obj, info):
         execute_sync(schema, document, root_value, variable_values=variable_values)
 
         assert len(resolved_infos) == 1
+        async_helpers = resolved_infos[0].async_helpers
+        assert isinstance(async_helpers, GraphQLResolveInfoHelpers)
+        assert async_helpers._fields == ("track",)
+        track = async_helpers.track
+        assert callable(track)
+        track(["not awaitable"])  # non-awaitable values are ignored
+
         operation = cast("OperationDefinitionNode", document.definitions[0])
         assert operation
         assert operation.kind == "operation_definition"
@@ -285,6 +293,7 @@ def resolve(_obj, info):
             context=None,
             is_awaitable=resolved_infos[0].is_awaitable,
             abort_signal=None,
+            async_helpers=async_helpers,
         )
 
     def it_populates_path_correctly_with_complex_types():

tests/execution/test_union_interface.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from asyncio import sleep
+
 import pytest
 
 from graphql.execution import ExecutionResult, execute, execute_sync
@@ -579,8 +581,7 @@ async def handles_rejections_from_is_type_of_after_an_is_type_of_returns_true():
         context_value = {"authToken": "123abc"}
 
         result = execute(schema, document, root_value, context_value)
-        assert not isinstance(result, ExecutionResult)
-        result = await result
+        # the synchronous isTypeOf match keeps the result synchronous
         assert isinstance(result, ExecutionResult)
 
         assert result == (
@@ -592,6 +593,10 @@ async def handles_rejections_from_is_type_of_after_an_is_type_of_returns_true():
             None,
         )
 
+        # give the pending isTypeOf rejection a chance to settle in the background
+        await sleep(0)
+        await sleep(0)
+
     @pytest.mark.filterwarnings("error:.*was never awaited:RuntimeWarning")
     async def handles_pending_is_type_of_rejections_when_a_later_one_throws_sync():
         throwing_searchable_interface = GraphQLInterfaceType(
@@ -656,10 +661,13 @@ def is_type_of_throwing(_value, _info) -> bool:
         )
 
         result = execute(schema_with_throwing_is_type_of, document)
-        assert not isinstance(result, ExecutionResult)
-        result = await result
+        # the synchronously throwing isTypeOf keeps the result synchronous
         assert isinstance(result, ExecutionResult)
 
         assert result.data == {"search": None}
         assert result.errors
         assert result.errors[0].message == "TypeThrowing_isTypeOf_threw"
+
+        # give the pending isTypeOf rejection a chance to settle in the background
+        await sleep(0)
+        await sleep(0)

tests/type/test_definition.py

@@ -54,6 +54,7 @@
     GraphQLObjectType,
     GraphQLOutputType,
     GraphQLResolveInfo,
+    GraphQLResolveInfoHelpers,
     GraphQLScalarType,
     GraphQLSchema,
     GraphQLString,
@@ -1613,6 +1614,7 @@ class InfoArgs(TypedDict):
         variable_values: VariableValues
         is_awaitable: Callable[[Any], TypeGuard[Awaitable[Any]]]
         abort_signal: AbortSignal | None
+        async_helpers: GraphQLResolveInfoHelpers
 
     info_args: InfoArgs = {
         "field_name": "foo",
@@ -1629,6 +1631,7 @@ class InfoArgs(TypedDict):
         "variable_values": VariableValues({}, {}),
         "is_awaitable": is_awaitable,
         "abort_signal": None,
+        "async_helpers": GraphQLResolveInfoHelpers(track=lambda _values: None),
     }
 
     def resolve_info_with_unspecified_context_type_can_use_any_type():