[RFC] Client Controlled Nullability experiment implementation w/o execution

Replicates graphql/graphql-js@699ec58

Author: Cito

docs/modules/language.rst

@@ -31,6 +31,7 @@ Each kind of AST node has its own class:
 .. autoclass:: EnumTypeExtensionNode
 .. autoclass:: EnumValueDefinitionNode
 .. autoclass:: EnumValueNode
+.. autoclass:: ErrorBoundaryNode
 .. autoclass:: ExecutableDefinitionNode
 .. autoclass:: FieldDefinitionNode
 .. autoclass:: FieldNode
@@ -44,11 +45,14 @@ Each kind of AST node has its own class:
 .. autoclass:: IntValueNode
 .. autoclass:: InterfaceTypeDefinitionNode
 .. autoclass:: InterfaceTypeExtensionNode
+.. autoclass:: ListNullabilityOperatorNode
 .. autoclass:: ListTypeNode
 .. autoclass:: ListValueNode
 .. autoclass:: NameNode
 .. autoclass:: NamedTypeNode
+.. autoclass:: NonNullAssertionNode
 .. autoclass:: NonNullTypeNode
+.. autoclass:: NullabilityAssertionNode
 .. autoclass:: NullValueNode
 .. autoclass:: ObjectFieldNode
 .. autoclass:: ObjectTypeDefinitionNode

src/graphql/__init__.py

@@ -83,6 +83,7 @@
     # Predicates
     is_definition_node,
     is_executable_definition_node,
+    is_nullability_assertion_node,
     is_selection_node,
     is_value_node,
     is_const_value_node,
@@ -110,6 +111,10 @@
     SelectionNode,
     FieldNode,
     ArgumentNode,
+    NullabilityAssertionNode,
+    NonNullAssertionNode,
+    ErrorBoundaryNode,
+    ListNullabilityOperatorNode,
     ConstArgumentNode,
     FragmentSpreadNode,
     InlineFragmentNode,
@@ -606,6 +611,7 @@
     "DirectiveLocation",
     "is_definition_node",
     "is_executable_definition_node",
+    "is_nullability_assertion_node",
     "is_selection_node",
     "is_value_node",
     "is_const_value_node",
@@ -630,6 +636,10 @@
     "SelectionNode",
     "FieldNode",
     "ArgumentNode",
+    "NullabilityAssertionNode",
+    "NonNullAssertionNode",
+    "ErrorBoundaryNode",
+    "ListNullabilityOperatorNode",
     "ConstArgumentNode",
     "FragmentSpreadNode",
     "InlineFragmentNode",

src/graphql/language/__init__.py

@@ -46,6 +46,10 @@
     SelectionSetNode,
     SelectionNode,
     FieldNode,
+    NullabilityAssertionNode,
+    NonNullAssertionNode,
+    ErrorBoundaryNode,
+    ListNullabilityOperatorNode,
     ArgumentNode,
     ConstArgumentNode,
     FragmentSpreadNode,
@@ -98,6 +102,7 @@
 from .predicates import (
     is_definition_node,
     is_executable_definition_node,
+    is_nullability_assertion_node,
     is_selection_node,
     is_value_node,
     is_const_value_node,
@@ -147,6 +152,10 @@
     "SelectionSetNode",
     "SelectionNode",
     "FieldNode",
+    "NullabilityAssertionNode",
+    "NonNullAssertionNode",
+    "ErrorBoundaryNode",
+    "ListNullabilityOperatorNode",
     "ArgumentNode",
     "ConstArgumentNode",
     "FragmentSpreadNode",
@@ -197,6 +206,7 @@
     "InputObjectTypeExtensionNode",
     "is_definition_node",
     "is_executable_definition_node",
+    "is_nullability_assertion_node",
     "is_selection_node",
     "is_value_node",
     "is_const_value_node",

src/graphql/language/ast.py

@@ -28,6 +28,10 @@
     "SelectionSetNode",
     "SelectionNode",
     "FieldNode",
+    "NullabilityAssertionNode",
+    "NonNullAssertionNode",
+    "ErrorBoundaryNode",
+    "ListNullabilityOperatorNode",
     "ArgumentNode",
     "ConstArgumentNode",
     "FragmentSpreadNode",
@@ -258,8 +262,22 @@ class OperationType(Enum):
     "variable_definition": ("variable", "type", "default_value", "directives"),
     "variable": ("name",),
     "selection_set": ("selections",),
-    "field": ("alias", "name", "arguments", "directives", "selection_set"),
+    "field": (
+        "alias",
+        "name",
+        "arguments",
+        "directives",
+        "selection_set",
+        # note: Client controlled Nullability is experimental and may be changed
+        # or removed in the future.
+        "nullability_assertion",
+    ),
     "argument": ("name", "value"),
+    # note: Client controlled Nullability is experimental and may be changed
+    # or removed in the future.
+    "list_nullability_operator": ("nullability_assertion",),
+    "non_null_assertion": ("nullability_assertion",),
+    "error_boundary": ("nullability_assertion",),
     "fragment_spread": ("name", "directives"),
     "inline_fragment": ("type_condition", "directives", "selection_set"),
     "fragment_definition": (
@@ -462,14 +480,34 @@ class SelectionNode(Node):
 
 
 class FieldNode(SelectionNode):
-    __slots__ = "alias", "name", "arguments", "selection_set"
+    __slots__ = "alias", "name", "arguments", "nullability_assertion", "selection_set"
 
     alias: Optional[NameNode]
     name: NameNode
     arguments: Tuple[ArgumentNode, ...]
+    # Note: Client Controlled Nullability is experimental
+    # and may be changed or removed in the future.
+    nullability_assertion: NullabilityAssertionNode
     selection_set: Optional[SelectionSetNode]
 
 
+class NullabilityAssertionNode(Node):
+    __slots__ = ("nullability_assertion",)
+    nullability_assertion: Optional["NullabilityAssertionNode"]
+
+
+class ListNullabilityOperatorNode(NullabilityAssertionNode):
+    pass
+
+
+class NonNullAssertionNode(NullabilityAssertionNode):
+    nullability_assertion: ListNullabilityOperatorNode
+
+
+class ErrorBoundaryNode(NullabilityAssertionNode):
+    nullability_assertion: ListNullabilityOperatorNode
+
+
 class ArgumentNode(Node):
     __slots__ = "name", "value"
 

src/graphql/language/lexer.py

@@ -458,6 +458,7 @@ def read_name(self, start: int) -> Token:
 _punctuator_token_kinds = frozenset(
     [
         TokenKind.BANG,
+        TokenKind.QUESTION_MARK,
         TokenKind.DOLLAR,
         TokenKind.AMP,
         TokenKind.PAREN_L,
@@ -485,6 +486,7 @@ def is_punctuator_token_kind(kind: TokenKind) -> bool:
 
 _KIND_FOR_PUNCT = {
     "!": TokenKind.BANG,
+    "?": TokenKind.QUESTION_MARK,
     "$": TokenKind.DOLLAR,
     "&": TokenKind.AMP,
     "(": TokenKind.PAREN_L,

src/graphql/language/parser.py

@@ -16,6 +16,7 @@
     EnumTypeExtensionNode,
     EnumValueDefinitionNode,
     EnumValueNode,
+    ErrorBoundaryNode,
     FieldDefinitionNode,
     FieldNode,
     FloatValueNode,
@@ -28,12 +29,15 @@
     InterfaceTypeDefinitionNode,
     InterfaceTypeExtensionNode,
     IntValueNode,
+    ListNullabilityOperatorNode,
     ListTypeNode,
     ListValueNode,
     Location,
     NamedTypeNode,
     NameNode,
+    NonNullAssertionNode,
     NonNullTypeNode,
+    NullabilityAssertionNode,
     NullValueNode,
     ObjectFieldNode,
     ObjectTypeDefinitionNode,
@@ -81,6 +85,7 @@ def parse(
     source: SourceType,
     no_location: bool = False,
     allow_legacy_fragment_variables: bool = False,
+    experimental_client_controlled_nullability: bool = False,
 ) -> DocumentNode:
     """Given a GraphQL source, parse it into a Document.
 
@@ -103,11 +108,31 @@ def parse(
         fragment A($var: Boolean = false) on T  {
           ...
         }
+
+    EXPERIMENTAL:
+
+    If enabled, the parser will understand and parse Client Controlled Nullability
+    Designators contained in Fields. They'll be represented in the
+    :attr:`~graphql.language.FieldNode.nullability_assertion` field
+    of the :class:`~graphql.language.FieldNode`.
+
+    The syntax looks like the following::
+
+       {
+         nullableField!
+         nonNullableField?
+         nonNullableSelectionSet? {
+           childField!
+        }
+      }
+
+    Note: this feature is experimental and may change or be removed in the future.
     """
     parser = Parser(
         source,
         no_location=no_location,
         allow_legacy_fragment_variables=allow_legacy_fragment_variables,
+        experimental_client_controlled_nullability=experimental_client_controlled_nullability,  # noqa
     )
     return parser.parse_document()
 
@@ -200,19 +225,24 @@ class Parser:
     _lexer: Lexer
     _no_location: bool
     _allow_legacy_fragment_variables: bool
+    _experimental_client_controlled_nullability: bool
 
     def __init__(
         self,
         source: SourceType,
         no_location: bool = False,
         allow_legacy_fragment_variables: bool = False,
+        experimental_client_controlled_nullability: bool = False,
     ):
         if not is_source(source):
             source = Source(cast(str, source))
 
         self._lexer = Lexer(source)
         self._no_location = no_location
         self._allow_legacy_fragment_variables = allow_legacy_fragment_variables
+        self._experimental_client_controlled_nullability = (
+            experimental_client_controlled_nullability
+        )
 
     def parse_name(self) -> NameNode:
         """Convert a name lex token into a name parse node."""
@@ -376,13 +406,46 @@ def parse_field(self) -> FieldNode:
             alias=alias,
             name=name,
             arguments=self.parse_arguments(False),
+            # Experimental support for Client Controlled Nullability changes
+            # the grammar of Field:
+            nullability_assertion=self.parse_nullability_assertion(),
             directives=self.parse_directives(False),
             selection_set=self.parse_selection_set()
             if self.peek(TokenKind.BRACE_L)
             else None,
             loc=self.loc(start),
         )
 
+    def parse_nullability_assertion(self) -> Optional[NullabilityAssertionNode]:
+        """NullabilityAssertion (grammar not yet finalized)
+
+        # Note: Client Controlled Nullability is experimental and may be changed or
+        # removed in the future.
+        """
+        if not self._experimental_client_controlled_nullability:
+            return None
+
+        start = self._lexer.token
+        nullability_assertion: Optional[NullabilityAssertionNode] = None
+
+        if self.expect_optional_token(TokenKind.BRACKET_L):
+            inner_modifier = self.parse_nullability_assertion()
+            self.expect_token(TokenKind.BRACKET_R)
+            nullability_assertion = ListNullabilityOperatorNode(
+                nullability_assertion=inner_modifier, loc=self.loc(start)
+            )
+
+        if self.expect_optional_token(TokenKind.BANG):
+            nullability_assertion = NonNullAssertionNode(
+                nullability_assertion=nullability_assertion, loc=self.loc(start)
+            )
+        elif self.expect_optional_token(TokenKind.QUESTION_MARK):
+            nullability_assertion = ErrorBoundaryNode(
+                nullability_assertion=nullability_assertion, loc=self.loc(start)
+            )
+
+        return nullability_assertion
+
     def parse_arguments(self, is_const: bool) -> List[ArgumentNode]:
         """Arguments[Const]: (Argument[?Const]+)"""
         item = self.parse_const_argument if is_const else self.parse_argument

src/graphql/language/predicates.py

@@ -5,6 +5,7 @@
     ExecutableDefinitionNode,
     ListValueNode,
     Node,
+    NullabilityAssertionNode,
     ObjectValueNode,
     SchemaExtensionNode,
     SelectionNode,
@@ -26,6 +27,7 @@
 __all__ = [
     "is_definition_node",
     "is_executable_definition_node",
+    "is_nullability_assertion_node",
     "is_selection_node",
     "is_value_node",
     "is_const_value_node",
@@ -52,6 +54,11 @@ def is_selection_node(node: Node) -> TypeGuard[SelectionNode]:
     return isinstance(node, SelectionNode)
 
 
+def is_nullability_assertion_node(node: Node) -> TypeGuard[NullabilityAssertionNode]:
+    """Check whether the given node represents a nullability assertion node."""
+    return isinstance(node, NullabilityAssertionNode)
+
+
 def is_value_node(node: Node) -> TypeGuard[ValueNode]:
     """Check whether the given node represents a value."""
     return isinstance(node, ValueNode)