add value_to_literal()

Replicates graphql/graphql-js@c05c7e2

Author: Cito

docs/modules/utilities.rst

@@ -66,6 +66,14 @@ Create a GraphQL language AST from a Python value:
 
 .. autofunction:: ast_from_value
 
+Create a GraphQL literal (AST) from a Python value:
+
+.. autofunction:: value_to_literal
+
+Replace any variables in an AST value with their literal values:
+
+.. autofunction:: replace_variables
+
 A helper to use within recursive-descent visitors which need to be aware of the GraphQL
 type system:
 

src/graphql/__init__.py

@@ -199,6 +199,10 @@
     value_from_ast_untyped,
     # Create a GraphQL language AST from a Python value.
     ast_from_value,
+    # Create a GraphQL literal (AST) from a Python value.
+    value_to_literal,
+    # Replace any variables in an AST value with their literal values.
+    replace_variables,
     # A helper to use within recursive-descent visitors which need to be aware of the
     # GraphQL type system.
     TypeInfo,
@@ -356,6 +360,8 @@
     GraphQLScalarSerializer,
     GraphQLScalarValueParser,
     GraphQLScalarLiteralParser,
+    GraphQLScalarConstLiteralParser,
+    GraphQLScalarValueToLiteral,
     GraphQLDefaultValueUsage,
     GraphQLIsTypeOfFn,
     GraphQLResolveInfo,
@@ -579,11 +585,13 @@
     "GraphQLOneOfDirective",
     "GraphQLOutputType",
     "GraphQLResolveInfo",
+    "GraphQLScalarConstLiteralParser",
     "GraphQLScalarLiteralParser",
     "GraphQLScalarSerializer",
     "GraphQLScalarType",
     "GraphQLScalarTypeKwargs",
     "GraphQLScalarValueParser",
+    "GraphQLScalarValueToLiteral",
     "GraphQLSchema",
     "GraphQLSchemaKwargs",
     "GraphQLSkipDirective",
@@ -803,6 +811,7 @@
     "print_source_location",
     "print_type",
     "recommended_rules",
+    "replace_variables",
     "resolve_thunk",
     "separate_operations",
     "specified_directives",
@@ -815,6 +824,7 @@
     "validate_schema",
     "value_from_ast",
     "value_from_ast_untyped",
+    "value_to_literal",
     "version",
     "version_info",
     "version_info_js",

src/graphql/type/__init__.py

@@ -103,6 +103,8 @@
     GraphQLScalarSerializer,
     GraphQLScalarValueParser,
     GraphQLScalarLiteralParser,
+    GraphQLScalarConstLiteralParser,
+    GraphQLScalarValueToLiteral,
     GraphQLDefaultValueUsage,
     # Keyword Args
     GraphQLArgumentKwargs,
@@ -234,11 +236,13 @@
     "GraphQLOneOfDirective",
     "GraphQLOutputType",
     "GraphQLResolveInfo",
+    "GraphQLScalarConstLiteralParser",
     "GraphQLScalarLiteralParser",
     "GraphQLScalarSerializer",
     "GraphQLScalarType",
     "GraphQLScalarTypeKwargs",
     "GraphQLScalarValueParser",
+    "GraphQLScalarValueToLiteral",
     "GraphQLSchema",
     "GraphQLSchemaKwargs",
     "GraphQLSkipDirective",

src/graphql/type/definition.py

@@ -109,11 +109,13 @@
     "GraphQLObjectTypeKwargs",
     "GraphQLOutputType",
     "GraphQLResolveInfo",
+    "GraphQLScalarConstLiteralParser",
     "GraphQLScalarLiteralParser",
     "GraphQLScalarSerializer",
     "GraphQLScalarType",
     "GraphQLScalarTypeKwargs",
     "GraphQLScalarValueParser",
+    "GraphQLScalarValueToLiteral",
     "GraphQLType",
     "GraphQLTypeResolver",
     "GraphQLUnionType",
@@ -316,6 +318,8 @@ def resolve_thunk(thunk: Thunk[T]) -> T:
 GraphQLScalarLiteralParser: TypeAlias = Callable[
     [ValueNode, dict[str, Any] | None], Any
 ]
+GraphQLScalarConstLiteralParser: TypeAlias = Callable[[ConstValueNode], Any]
+GraphQLScalarValueToLiteral: TypeAlias = Callable[[Any], "ConstValueNode | None"]
 
 
 class GraphQLScalarTypeKwargs(GraphQLNamedTypeKwargs, total=False):
@@ -324,6 +328,8 @@ class GraphQLScalarTypeKwargs(GraphQLNamedTypeKwargs, total=False):
     serialize: GraphQLScalarSerializer | None
     parse_value: GraphQLScalarValueParser | None
     parse_literal: GraphQLScalarLiteralParser | None
+    parse_const_literal: GraphQLScalarConstLiteralParser | None
+    value_to_literal: GraphQLScalarValueToLiteral | None
     specified_by_url: str | None
 
 
@@ -359,12 +365,16 @@ def serialize_odd(value: Any) -> int:
     ast_node: ScalarTypeDefinitionNode | None
     extension_ast_nodes: tuple[ScalarTypeExtensionNode, ...]
 
+    value_to_literal: GraphQLScalarValueToLiteral | None
+
     def __init__(
         self,
         name: str,
         serialize: GraphQLScalarSerializer | None = None,
         parse_value: GraphQLScalarValueParser | None = None,
         parse_literal: GraphQLScalarLiteralParser | None = None,
+        parse_const_literal: GraphQLScalarConstLiteralParser | None = None,
+        value_to_literal: GraphQLScalarValueToLiteral | None = None,
         description: str | None = None,
         specified_by_url: str | None = None,
         extensions: dict[str, Any] | None = None,
@@ -385,11 +395,20 @@ def __init__(
             self.parse_value = parse_value  # type: ignore
         if parse_literal is not None:
             self.parse_literal = parse_literal  # type: ignore
+        if parse_const_literal is not None:
+            self.parse_const_literal = parse_const_literal  # type: ignore
+        self.value_to_literal = value_to_literal
         if parse_literal is not None and parse_value is None:
             msg = (
                 f"{name} must provide both 'parse_value' and 'parse_literal' functions."
             )
             raise TypeError(msg)
+        if parse_const_literal is not None and parse_value is None:
+            msg = (
+                f"{name} must provide both 'parse_value'"
+                " and 'parse_const_literal' functions."
+            )
+            raise TypeError(msg)
         self.specified_by_url = specified_by_url
 
     def __repr__(self) -> str:
@@ -423,9 +442,21 @@ def parse_literal(
 
         This default method uses the parse_value method and should be replaced
         with a more specific version when creating a scalar type.
+
+        .. deprecated:: 3.3
+            Use ``replace_variables()`` and ``parse_const_literal()`` instead.
+            ``parse_literal()`` will be removed in a future version.
         """
         return self.parse_value(value_from_ast_untyped(node, variables))
 
+    def parse_const_literal(self, node: ConstValueNode) -> Any:
+        """Parses an externally provided const literal value to use as an input.
+
+        This default method uses the parse_value method and should be replaced
+        with a more specific version when creating a scalar type.
+        """
+        return self.parse_value(value_from_ast_untyped(node))
+
     def to_kwargs(self) -> GraphQLScalarTypeKwargs:
         """Get corresponding arguments."""
         return GraphQLScalarTypeKwargs(
@@ -440,6 +471,11 @@ def to_kwargs(self) -> GraphQLScalarTypeKwargs:
             if getattr(self.parse_literal, "__func__", None)
             is GraphQLScalarType.parse_literal
             else self.parse_literal,
+            parse_const_literal=None
+            if getattr(self.parse_const_literal, "__func__", None)
+            is GraphQLScalarType.parse_const_literal
+            else self.parse_const_literal,
+            value_to_literal=self.value_to_literal,
             specified_by_url=self.specified_by_url,
         )
 
@@ -1228,8 +1264,17 @@ def parse_value(self, input_value: str) -> Any:
     def parse_literal(
         self, value_node: ValueNode, _variables: dict[str, Any] | None = None
     ) -> Any:
-        """Parse literal value."""
+        """Parse literal value.
+
+        .. deprecated:: 3.3
+            Use ``parse_const_literal()`` instead. ``parse_literal()`` will be
+            removed in a future version.
+        """
         # Note: variables will be resolved before calling this method.
+        return self.parse_const_literal(cast("ConstValueNode", value_node))
+
+    def parse_const_literal(self, value_node: ConstValueNode) -> Any:
+        """Parse const literal value."""
         if isinstance(value_node, EnumValueNode):
             try:
                 enum_value = self.values[value_node.value]
@@ -1248,6 +1293,12 @@ def parse_literal(
         )
         raise GraphQLError(msg, value_node)
 
+    def value_to_literal(self, value: Any) -> ConstValueNode | None:
+        """Convert an external value to an enum literal (AST)."""
+        if isinstance(value, str) and self.values.get(value):
+            return EnumValueNode(value=value)
+        return None
+
 
 def is_enum_type(type_: Any) -> TypeGuard[GraphQLEnumType]:
     """Check whether this is a GraphQL enum type."""

src/graphql/type/scalars.py

@@ -2,24 +2,29 @@
 
 from __future__ import annotations
 
+import re
 from math import isfinite
 from typing import TYPE_CHECKING, Any, TypeGuard
 
 from ..error import GraphQLError
 from ..language.ast import (
     BooleanValueNode,
+    ConstValueNode,
     FloatValueNode,
     IntValueNode,
     StringValueNode,
     ValueNode,
 )
 from ..language.printer import print_ast
 from ..pyutils import inspect
+from ..utilities.value_to_literal import default_scalar_value_to_literal
 from .definition import GraphQLNamedType, GraphQLScalarType
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
 
+_re_integer_string = re.compile("^-?(?:0|[1-9][0-9]*)$")
+
 __all__ = [
     "GRAPHQL_MAX_INT",
     "GRAPHQL_MIN_INT",
@@ -104,14 +109,28 @@ def parse_int_literal(value_node: ValueNode, _variables: Any = None) -> int:
     return num
 
 
+def int_value_to_literal(value: Any) -> ConstValueNode | None:
+    """Convert an integer value to an Int literal in the AST."""
+    if (
+        isinstance(value, (int, float))
+        and not isinstance(value, bool)
+        and isfinite(value)
+        and value == int(value)
+        and GRAPHQL_MIN_INT <= value <= GRAPHQL_MAX_INT
+    ):
+        return IntValueNode(value=str(int(value)))
+    return None
+
+
 GraphQLInt = GraphQLScalarType(
     name="Int",
     description="The `Int` scalar type represents"
     " non-fractional signed whole numeric values."
     " Int can represent values between -(2^31) and 2^31 - 1.",
     serialize=serialize_int,
     parse_value=coerce_int,
-    parse_literal=parse_int_literal,
+    parse_const_literal=parse_int_literal,
+    value_to_literal=int_value_to_literal,
 )
 
 
@@ -151,6 +170,14 @@ def parse_float_literal(value_node: ValueNode, _variables: Any = None) -> float:
     return float(value_node.value)
 
 
+def float_value_to_literal(value: Any) -> ConstValueNode | None:
+    """Convert a float value to a Float literal in the AST."""
+    literal = default_scalar_value_to_literal(value)
+    if isinstance(literal, (FloatValueNode, IntValueNode)):
+        return literal
+    return None
+
+
 GraphQLFloat = GraphQLScalarType(
     name="Float",
     description="The `Float` scalar type represents"
@@ -159,7 +186,8 @@ def parse_float_literal(value_node: ValueNode, _variables: Any = None) -> float:
     "(https://en.wikipedia.org/wiki/IEEE_floating_point).",
     serialize=serialize_float,
     parse_value=coerce_float,
-    parse_literal=parse_float_literal,
+    parse_const_literal=parse_float_literal,
+    value_to_literal=float_value_to_literal,
 )
 
 
@@ -197,6 +225,14 @@ def parse_string_literal(value_node: ValueNode, _variables: Any = None) -> str:
     return value_node.value
 
 
+def string_value_to_literal(value: Any) -> ConstValueNode | None:
+    """Convert a string value to a String literal in the AST."""
+    literal = default_scalar_value_to_literal(value)
+    if isinstance(literal, StringValueNode):
+        return literal
+    return None
+
+
 GraphQLString = GraphQLScalarType(
     name="String",
     description="The `String` scalar type represents textual data,"
@@ -205,7 +241,8 @@ def parse_string_literal(value_node: ValueNode, _variables: Any = None) -> str:
     " to represent free-form human-readable text.",
     serialize=serialize_string,
     parse_value=coerce_string,
-    parse_literal=parse_string_literal,
+    parse_const_literal=parse_string_literal,
+    value_to_literal=string_value_to_literal,
 )
 
 
@@ -239,12 +276,21 @@ def parse_boolean_literal(value_node: ValueNode, _variables: Any = None) -> bool
     return value_node.value
 
 
+def boolean_value_to_literal(value: Any) -> ConstValueNode | None:
+    """Convert a boolean value to a Boolean literal in the AST."""
+    literal = default_scalar_value_to_literal(value)
+    if isinstance(literal, BooleanValueNode):
+        return literal
+    return None
+
+
 GraphQLBoolean = GraphQLScalarType(
     name="Boolean",
     description="The `Boolean` scalar type represents `true` or `false`.",
     serialize=serialize_boolean,
     parse_value=coerce_boolean,
-    parse_literal=parse_boolean_literal,
+    parse_const_literal=parse_boolean_literal,
+    value_to_literal=boolean_value_to_literal,
 )
 
 
@@ -291,6 +337,27 @@ def parse_id_literal(value_node: ValueNode, _variables: Any = None) -> str:
     return value_node.value
 
 
+def id_value_to_literal(value: Any) -> ConstValueNode | None:
+    """Convert an ID value to an Int or String literal in the AST."""
+    # ID types can use number values and Int literals.
+    string_value: Any = (
+        str(int(value))
+        if isinstance(value, (int, float))
+        and not isinstance(value, bool)
+        and isfinite(value)
+        and value == int(value)
+        else value
+    )
+    if isinstance(string_value, str):
+        # Will parse as an IntValue if it consists only of integer digits.
+        return (
+            IntValueNode(value=string_value)
+            if _re_integer_string.match(string_value)
+            else StringValueNode(value=string_value, block=False)
+        )
+    return None
+
+
 GraphQLID = GraphQLScalarType(
     name="ID",
     description="The `ID` scalar type represents a unique identifier,"
@@ -301,7 +368,8 @@ def parse_id_literal(value_node: ValueNode, _variables: Any = None) -> str:
     " `4`) input value will be accepted as an ID.",
     serialize=serialize_id,
     parse_value=coerce_id,
-    parse_literal=parse_id_literal,
+    parse_const_literal=parse_id_literal,
+    value_to_literal=id_value_to_literal,
 )
 
 specified_scalar_types: Mapping[str, GraphQLScalarType] = {