Deprecate print_error function

Replicates graphql/graphql-js@da685ee

Author: Cito

src/graphql/__init__.py

@@ -343,8 +343,7 @@
     GraphQLError,
     GraphQLSyntaxError,
     located_error,
-    format_error,
-    print_error,
+    format_error
 )
 
 # Utilities for operating on GraphQL type schema and parsed sources.
@@ -688,7 +687,6 @@
     "GraphQLSyntaxError",
     "located_error",
     "format_error",
-    "print_error",
     "get_introspection_query",
     "get_operation_ast",
     "get_operation_root_type",

src/graphql/error/__init__.py

@@ -4,7 +4,7 @@
 errors.
 """
 
-from .graphql_error import GraphQLError, format_error, print_error
+from .graphql_error import GraphQLError, format_error
 
 from .syntax_error import GraphQLSyntaxError
 
@@ -14,6 +14,5 @@
     "GraphQLError",
     "GraphQLSyntaxError",
     "format_error",
-    "located_error",
-    "print_error",
+    "located_error"
 ]

src/graphql/error/graphql_error.py

@@ -6,7 +6,7 @@
     from ..language.location import SourceLocation  # noqa: F401
     from ..language.source import Source  # noqa: F401
 
-__all__ = ["GraphQLError", "format_error", "print_error"]
+__all__ = ["GraphQLError"]
 
 
 class GraphQLError(Exception):
@@ -137,7 +137,21 @@ def __init__(
             self.__traceback__ = exc_info()[2]
 
     def __str__(self) -> str:
-        return print_error(self)
+        # Lazy import to avoid a cyclic dependency between error and language
+        from ..language.print_location import print_location, print_source_location
+
+        output = [self.message]
+
+        if self.nodes:
+            for node in self.nodes:
+                if node.loc:
+                    output.append(print_location(node.loc))
+        elif self.source and self.locations:
+            source = self.source
+            for location in self.locations:
+                output.append(print_source_location(source, location))
+
+        return "\n\n".join(output)
 
     def __repr__(self) -> str:
         args = [repr(self.message)]
@@ -173,49 +187,47 @@ def __ne__(self, other: Any) -> bool:
 
     @property
     def formatted(self) -> Dict[str, Any]:
-        """Get error formatted according to the specification."""
-        return format_error(self)
+        """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,
+        )
+        if self.extensions:
+            formatted.update(extensions=self.extensions)
+        return formatted
 
 
 def print_error(error: GraphQLError) -> str:
     """Print a GraphQLError to a string.
 
     Represents useful location information about the error's position in the source.
-    """
-    # Lazy import to avoid a cyclic dependency between error and language
-    from ..language.print_location import print_location, print_source_location
-
-    output = [error.message]
 
-    if error.nodes:
-        for node in error.nodes:
-            if node.loc:
-                output.append(print_location(node.loc))
-    elif error.source and error.locations:
-        source = error.source
-        for location in error.locations:
-            output.append(print_source_location(source, location))
-
-    return "\n\n".join(output)
+    .. deprecated:: 3.2
+       Please use ``str(error)`` instead. Will be removed in v3.3.
+    """
+    if not isinstance(error, GraphQLError):
+        raise TypeError("Expected a GraphQLError.")
+    return str(error)
 
 
 def format_error(error: GraphQLError) -> Dict[str, Any]:
     """Format a GraphQL error.
 
     Given a GraphQLError, format it according to the rules described by the "Response
     Format, Errors" section of the GraphQL Specification.
+
+    .. deprecated:: 3.2
+       Please use ``error.formatted`` instead. Will be removed in v3.3.
     """
     if not isinstance(error, GraphQLError):
         raise TypeError("Expected a GraphQLError.")
-    formatted: Dict[str, Any] = dict(  # noqa: E701 (pycqa/flake8#394)
-        message=error.message or "An unknown error occurred.",
-        locations=(
-            [location.formatted for location in error.locations]
-            if error.locations is not None
-            else None
-        ),
-        path=error.path,
-    )
-    if error.extensions:
-        formatted.update(extensions=error.extensions)
-    return formatted
+    return error.formatted

tests/error/test_graphql_error.py

@@ -1,6 +1,8 @@
 from typing import cast, List, Union
 
-from graphql.error import GraphQLError, print_error
+from pytest import raises
+
+from graphql.error import GraphQLError
 from graphql.language import (
     parse,
     OperationDefinitionNode,
@@ -129,16 +131,26 @@ def serializes_to_include_message_and_locations():
         assert repr(e) == (
             "GraphQLError('msg', locations=[SourceLocation(line=2, column=3)])"
         )
+        assert e.formatted == {
+            "locations": [{"column": 3, "line": 2}],
+            "message": "msg",
+            "path": None,
+        }
 
     def repr_includes_extensions():
         e = GraphQLError("msg", extensions={"foo": "bar"})
-        assert repr(e) == ("GraphQLError('msg', extensions={'foo': 'bar'})")
+        assert repr(e) == "GraphQLError('msg', extensions={'foo': 'bar'})"
 
     def serializes_to_include_path():
         path: List[Union[int, str]] = ["path", 3, "to", "field"]
         e = GraphQLError("msg", path=path)
         assert e.path is path
         assert repr(e) == "GraphQLError('msg', path=['path', 3, 'to', 'field'])"
+        assert e.formatted == {
+            "locations": None,
+            "message": "msg",
+            "path": ["path", 3, "to", "field"],
+        }
 
     def always_stores_path_as_list():
         path: List[Union[int, str]] = ["path", 3, "to", "field"]
@@ -171,17 +183,27 @@ def hashes_are_unique_per_instance():
         assert hash(e1) != hash(e2)
 
 
-def describe_print_error():
+def describe_to_string():
+    def deprecated_prints_an_error_using_print_error():
+        # noinspection PyProtectedMember
+        from graphql.error.graphql_error import print_error
+        error = GraphQLError("Error")
+        assert print_error(error) == "Error"
+        with raises(TypeError) as exc_info:
+            # noinspection PyTypeChecker
+            print_error(Exception)  # type: ignore
+        assert str(exc_info.value) == "Expected a GraphQLError."
+
     def prints_an_error_without_location():
         error = GraphQLError("Error without location")
-        assert print_error(error) == "Error without location"
+        assert str(error) == "Error without location"
 
     def prints_an_error_using_node_without_location():
         error = GraphQLError(
             "Error attached to node without location",
             parse("{ foo }", no_location=True),
         )
-        assert print_error(error) == "Error attached to node without location"
+        assert str(error) == "Error attached to node without location"
 
     def prints_an_error_with_nodes_from_different_sources():
         doc_a = parse(
@@ -221,8 +243,7 @@ def prints_an_error_with_nodes_from_different_sources():
             "Example error with two nodes", [field_a.type, field_b.type]
         )
 
-        printed_error = print_error(error)
-        assert printed_error == dedent(
+        assert str(error) == dedent(
             """
             Example error with two nodes
 
@@ -239,4 +260,3 @@ def prints_an_error_with_nodes_from_different_sources():
             3 | }
             """
         )
-        assert str(error) == printed_error