Deprecate format_error

Also use TypedDict for formatted results,
and do not include unused keys any more.

Replicates graphql/graphql-js@8423d33

Author: Cito

docs/conf.py

@@ -96,6 +96,8 @@
 
 autodoc_type_aliases = {
     'AwaitableOrValue': 'graphql.pyutils.AwaitableOrValue',
+    'FormattedSourceLocation': 'graphql.language.FormattedSourceLocation',
+    'Middleware': 'graphql.execution.Middleware',
     'TypeMap': 'graphql.schema.TypeMap'
 }
 
@@ -131,6 +133,7 @@
 enum.Enum
 traceback
 types.TracebackType
+FormattedSourceLocation
 asyncio.events.AbstractEventLoop
 graphql.language.lexer.EscapeSequence
 graphql.subscription.map_async_iterator.MapAsyncIterator

docs/modules/error.rst

@@ -4,3 +4,15 @@ Error
 .. currentmodule:: graphql.error
 
 .. automodule:: graphql.error
+   :no-members:
+   :no-inherited-members:
+
+.. autoclass:: GraphQLError
+
+.. autoclass:: GraphQLSyntaxError
+
+.. autoclass:: GraphQLFormattedError
+   :no-inherited-members:
+   :no-special-members:
+
+.. autofunction:: located_error

docs/modules/execution.rst

@@ -4,3 +4,26 @@ Execution
 .. currentmodule:: graphql.execution
 
 .. automodule:: graphql.execution
+   :no-members:
+   :no-inherited-members:
+
+.. autofunction:: execute
+
+.. autofunction:: execute_sync
+
+.. autofunction:: default_field_resolver
+
+.. autofunction:: default_type_resolver
+
+.. autoclass:: ExecutionContext
+
+.. autoclass:: ExecutionResult
+
+.. autoclass:: FormattedExecutionResult
+   :no-inherited-members:
+
+.. autoclass:: Middleware
+
+.. autoclass:: MiddlewareManager
+
+.. autofunction:: get_directive_values

docs/modules/language.rst

@@ -105,6 +105,9 @@ Location
 .. autofunction:: get_location
 .. autoclass:: SourceLocation
 .. autofunction:: print_location
+.. autoclass:: FormattedSourceLocation
+   :no-inherited-members:
+
 
 Parser
 ------

pyproject.toml

@@ -50,6 +50,7 @@ pytest-benchmark = "^3.4"
 pytest-cov = "^2.12"
 pytest-describe = "^2.0"
 pytest-timeout = "^1.4"
+typing-extensions = { version = "^3.10", python = "<3.8" }
 black = [
     {version = "21.9b0", python = ">=3.6.2"},
     {version = "20.8b1", python = "<3.6.2"}

src/graphql/__init__.py

@@ -281,6 +281,7 @@
     # Types
     ExecutionContext,
     ExecutionResult,
+    FormattedExecutionResult,
     # Middleware
     Middleware,
     MiddlewareManager,
@@ -341,9 +342,9 @@
 # Create, format, and print GraphQL errors.
 from .error import (
     GraphQLError,
+    GraphQLFormattedError,
     GraphQLSyntaxError,
     located_error,
-    format_error
 )
 
 # Utilities for operating on GraphQL type schema and parsed sources.
@@ -637,6 +638,7 @@
     "get_directive_values",
     "ExecutionContext",
     "ExecutionResult",
+    "FormattedExecutionResult",
     "Middleware",
     "MiddlewareManager",
     "subscribe",
@@ -684,9 +686,9 @@
     "NoDeprecatedCustomRule",
     "NoSchemaIntrospectionCustomRule",
     "GraphQLError",
+    "GraphQLFormattedError",
     "GraphQLSyntaxError",
     "located_error",
-    "format_error",
     "get_introspection_query",
     "get_operation_ast",
     "get_operation_root_type",

src/graphql/error/__init__.py

@@ -4,15 +4,15 @@
 errors.
 """
 
-from .graphql_error import GraphQLError, format_error
+from .graphql_error import GraphQLError, GraphQLFormattedError
 
 from .syntax_error import GraphQLSyntaxError
 
 from .located_error import located_error
 
 __all__ = [
     "GraphQLError",
+    "GraphQLFormattedError",
     "GraphQLSyntaxError",
-    "format_error",
-    "located_error"
+    "located_error",
 ]

src/graphql/error/graphql_error.py

@@ -1,12 +1,39 @@
 from sys import exc_info
 from typing import Any, Collection, Dict, List, Optional, Union, TYPE_CHECKING
 
+try:
+    from typing import TypedDict
+except ImportError:  # Python < 3.8
+    from typing_extensions import TypedDict
+
 if TYPE_CHECKING:
     from ..language.ast import Node  # noqa: F401
-    from ..language.location import SourceLocation  # noqa: F401
+    from ..language.location import (
+        SourceLocation,
+        FormattedSourceLocation,
+    )  # noqa: F401
     from ..language.source import Source  # noqa: F401
 
-__all__ = ["GraphQLError"]
+__all__ = ["GraphQLError", "GraphQLFormattedError"]
+
+
+class GraphQLFormattedError(TypedDict, total=False):
+    """Formatted GraphQL error"""
+
+    # A short, human-readable summary of the problem that **SHOULD NOT** change
+    # from occurrence to occurrence of the problem, except for purposes of localization.
+    message: str
+    # If an error can be associated to a particular point in the requested
+    # GraphQL document, it should contain a list of locations.
+    locations: List["FormattedSourceLocation"]
+    # If an error can be associated to a particular field in the GraphQL result,
+    # it _must_ contain an entry with the key `path` that details the path of
+    # the response field which experienced the error. This allows clients to
+    # identify whether a null result is intentional or caused by a runtime error.
+    path: List[Union[str, int]]
+    # Reserved for implementors to extend the protocol however they see fit,
+    # and hence there are no additional restrictions on its contents.
+    extensions: Dict[str, Any]
 
 
 class GraphQLError(Exception):
@@ -186,23 +213,21 @@ def __ne__(self, other: Any) -> bool:
         return not self == other
 
     @property
-    def formatted(self) -> Dict[str, Any]:
+    def formatted(self) -> GraphQLFormattedError:
         """Get error formatted according to the specification.
 
         Given a GraphQLError, format it according to the rules described by the
         "Response Format, Errors" section of the GraphQL Specification.
         """
-        formatted: Dict[str, Any] = dict(  # noqa: E701 (pycqa/flake8#394)
-            message=self.message or "An unknown error occurred.",
-            locations=(
-                [location.formatted for location in self.locations]
-                if self.locations is not None
-                else None
-            ),
-            path=self.path,
-        )
+        formatted: GraphQLFormattedError = {
+            "message": self.message or "An unknown error occurred.",
+        }
+        if self.locations is not None:
+            formatted["locations"] = [location.formatted for location in self.locations]
+        if self.path is not None:
+            formatted["path"] = self.path
         if self.extensions:
-            formatted.update(extensions=self.extensions)
+            formatted["extensions"] = self.extensions
         return formatted
 
 
@@ -219,7 +244,7 @@ def print_error(error: GraphQLError) -> str:
     return str(error)
 
 
-def format_error(error: GraphQLError) -> Dict[str, Any]:
+def format_error(error: GraphQLError) -> GraphQLFormattedError:
     """Format a GraphQL error.
 
     Given a GraphQLError, format it according to the rules described by the "Response

src/graphql/execution/__init__.py

@@ -11,6 +11,7 @@
     default_type_resolver,
     ExecutionContext,
     ExecutionResult,
+    FormattedExecutionResult,
     Middleware,
 )
 
@@ -25,6 +26,7 @@
     "default_type_resolver",
     "ExecutionContext",
     "ExecutionResult",
+    "FormattedExecutionResult",
     "Middleware",
     "MiddlewareManager",
     "get_directive_values",

src/graphql/execution/execute.py

@@ -16,7 +16,12 @@
     cast,
 )
 
-from ..error import GraphQLError, located_error
+try:
+    from typing import TypedDict
+except ImportError:  # Python < 3.8
+    from typing_extensions import TypedDict
+
+from ..error import GraphQLError, GraphQLFormattedError, located_error
 from ..language import (
     DocumentNode,
     FieldNode,
@@ -69,6 +74,7 @@
     "get_field_def",
     "ExecutionResult",
     "ExecutionContext",
+    "FormattedExecutionResult",
     "Middleware",
 ]
 
@@ -92,6 +98,14 @@
 # 3) inline fragment "spreads" e.g. "...on Type { a }"
 
 
+class FormattedExecutionResult(TypedDict, total=False):
+    """Formatted execution result"""
+
+    errors: List[GraphQLFormattedError]
+    data: Optional[Dict[str, Any]]
+    extensions: Dict[str, Any]
+
+
 class ExecutionResult:
     """The result of GraphQL execution.
 
@@ -125,14 +139,14 @@ def __iter__(self) -> Iterable[Any]:
         return iter((self.data, self.errors))
 
     @property
-    def formatted(self) -> Dict[str, Any]:
+    def formatted(self) -> FormattedExecutionResult:
         """Get execution result formatted according to the specification."""
-        errors = (
-            None if self.errors is None else [error.formatted for error in self.errors]
-        )
-        if self.extensions is None:
-            return dict(data=self.data, errors=errors)
-        return dict(data=self.data, errors=errors, extensions=self.extensions)
+        formatted: FormattedExecutionResult = {"data": self.data}
+        if self.errors is not None:
+            formatted["errors"] = [error.formatted for error in self.errors]
+        if self.extensions is not None:
+            formatted["extensions"] = self.extensions
+        return formatted
 
     def __eq__(self, other: Any) -> bool:
         if isinstance(other, dict):