Deprecate fragments with variables and reflect that in naming

Replicates graphql/graphql-js@920b45a

Author: Cito

src/graphql/language/parser.py

@@ -71,7 +71,7 @@
 def parse(
     source: SourceType,
     no_location: bool = False,
-    experimental_fragment_variables: bool = False,
+    allow_legacy_fragment_variables: bool = False,
 ) -> DocumentNode:
     """Given a GraphQL source, parse it into a Document.
 
@@ -81,9 +81,9 @@ def parse(
     they correspond to. The ``no_location`` option disables that behavior for
     performance or testing.
 
-    Experimental features:
+    Legacy feature (will be removed in v3.3):
 
-    If ``experimental_fragment_variables`` is set to ``True``, the parser will
+    If ``allow_legacy_fragment_variables`` is set to ``True``, the parser will
     understand and parse variable definitions contained in a fragment definition.
     They'll be represented in the
     :attr:`~graphql.language.FragmentDefinitionNode.variable_definitions` field
@@ -98,15 +98,15 @@ def parse(
     parser = Parser(
         source,
         no_location=no_location,
-        experimental_fragment_variables=experimental_fragment_variables,
+        allow_legacy_fragment_variables=allow_legacy_fragment_variables,
     )
     return parser.parse_document()
 
 
 def parse_value(
     source: SourceType,
     no_location: bool = False,
-    experimental_fragment_variables: bool = False,
+    allow_legacy_fragment_variables: bool = False,
 ) -> ValueNode:
     """Parse the AST for a given string containing a GraphQL value.
 
@@ -121,7 +121,7 @@ def parse_value(
     parser = Parser(
         source,
         no_location=no_location,
-        experimental_fragment_variables=experimental_fragment_variables,
+        allow_legacy_fragment_variables=allow_legacy_fragment_variables,
     )
     parser.expect_token(TokenKind.SOF)
     value = parser.parse_value_literal(False)
@@ -132,7 +132,7 @@ def parse_value(
 def parse_type(
     source: SourceType,
     no_location: bool = False,
-    experimental_fragment_variables: bool = False,
+    allow_legacy_fragment_variables: bool = False,
 ) -> TypeNode:
     """Parse the AST for a given string containing a GraphQL Type.
 
@@ -147,7 +147,7 @@ def parse_type(
     parser = Parser(
         source,
         no_location=no_location,
-        experimental_fragment_variables=experimental_fragment_variables,
+        allow_legacy_fragment_variables=allow_legacy_fragment_variables,
     )
     parser.expect_token(TokenKind.SOF)
     type_ = parser.parse_type_reference()
@@ -169,21 +169,21 @@ class Parser:
 
     _lexer: Lexer
     _no_Location: bool
-    _experimental_fragment_variables: bool
+    _allow_legacy_fragment_variables: bool
 
     def __init__(
         self,
         source: SourceType,
         no_location: bool = False,
-        experimental_fragment_variables: bool = False,
+        allow_legacy_fragment_variables: bool = False,
     ):
         source = (
             cast(Source, source) if is_source(source) else Source(cast(str, source))
         )
 
         self._lexer = Lexer(source)
         self._no_location = no_location
-        self._experimental_fragment_variables = experimental_fragment_variables
+        self._allow_legacy_fragment_variables = allow_legacy_fragment_variables
 
     def parse_name(self) -> NameNode:
         """Convert a name lex token into a name parse node."""
@@ -389,9 +389,9 @@ def parse_fragment_definition(self) -> FragmentDefinitionNode:
         """FragmentDefinition"""
         start = self._lexer.token
         self.expect_keyword("fragment")
-        # Experimental support for defining variables within fragments changes
+        # Legacy support for defining variables within fragments changes
         # the grammar of FragmentDefinition
-        if self._experimental_fragment_variables:
+        if self._allow_legacy_fragment_variables:
             return FragmentDefinitionNode(
                 name=self.parse_fragment_name(),
                 variable_definitions=self.parse_variable_definitions(),

src/graphql/language/printer.py

@@ -134,8 +134,7 @@ def leave_inline_fragment(node: PrintedNode, *_args: Any) -> str:
 
     @staticmethod
     def leave_fragment_definition(node: PrintedNode, *_args: Any) -> str:
-        # Note: fragment variable definitions are experimental and may be changed or
-        # removed in the future.
+        # Note: fragment variable definitions are deprecated and will be removed in v3.3
         return (
             f"fragment {node.name}"
             f"{wrap('(', join(node.variable_definitions, ', '), ')')}"

src/graphql/language/visitor.py

@@ -69,8 +69,7 @@ class VisitorActionEnum(Enum):
     "fragment_spread": ("name", "directives"),
     "inline_fragment": ("type_condition", "directives", "selection_set"),
     "fragment_definition": (
-        # Note: fragment variable definitions are experimental and may be changed or
-        # removed in the future.
+        # Note: fragment variable definitions are deprecated and will be removed in v3.3
         "name",
         "variable_definitions",
         "type_condition",

src/graphql/utilities/build_ast_schema.py

@@ -80,14 +80,14 @@ def build_schema(
     assume_valid: bool = False,
     assume_valid_sdl: bool = False,
     no_location: bool = False,
-    experimental_fragment_variables: bool = False,
+    allow_legacy_fragment_variables: bool = False,
 ) -> GraphQLSchema:
     """Build a GraphQLSchema directly from a source document."""
     return build_ast_schema(
         parse(
             source,
             no_location=no_location,
-            experimental_fragment_variables=experimental_fragment_variables,
+            allow_legacy_fragment_variables=allow_legacy_fragment_variables,
         ),
         assume_valid=assume_valid,
         assume_valid_sdl=assume_valid_sdl,

tests/language/test_parser.py

@@ -351,9 +351,9 @@ def allows_parsing_without_source_location_information():
         result = parse("{ id }", no_location=True)
         assert result.loc is None
 
-    def experimental_allows_parsing_fragment_defined_variables():
+    def legacy_allows_parsing_fragment_defined_variables():
         document = "fragment a($v: Boolean = false) on t { f(v: $v) }"
-        parse(document, experimental_fragment_variables=True)
+        parse(document, allow_legacy_fragment_variables=True)
         with raises(GraphQLSyntaxError):
             parse(document)
 

tests/language/test_printer.py

@@ -114,10 +114,10 @@ def puts_arguments_on_multiple_lines_if_line_has_more_than_80_chars():
             """
         )
 
-    def experimental_prints_fragment_with_variable_directives():
+    def legacy_prints_fragment_with_variable_directives():
         query_ast_with_variable_directive = parse(
             "fragment Foo($foo: TestType @test) on TestType @testDirective { id }",
-            experimental_fragment_variables=True,
+            allow_legacy_fragment_variables=True,
         )
         assert print_ast(query_ast_with_variable_directive) == dedent(
             """
@@ -127,13 +127,13 @@ def experimental_prints_fragment_with_variable_directives():
             """
         )
 
-    def experimental_correctly_prints_fragment_defined_variables():
+    def legacy_correctly_prints_fragment_defined_variables():
         source = """
             fragment Foo($a: ComplexType, $b: Boolean = false) on TestType {
               id
             }
             """
-        fragment_with_variable = parse(source, experimental_fragment_variables=True)
+        fragment_with_variable = parse(source, allow_legacy_fragment_variables=True)
         assert print_ast(fragment_with_variable) == dedent(source)
 
     # noinspection PyShadowingNames

tests/language/test_visitor.py

@@ -540,11 +540,11 @@ def leave_selection_set(*args):
             ["leave", "selection_set", None],
         ]
 
-    def experimental_visits_variables_defined_in_fragments():
+    def legacy_visits_variables_defined_in_fragments():
         ast = parse(
             "fragment a($v: Boolean = false) on t { f }",
             no_location=True,
-            experimental_fragment_variables=True,
+            allow_legacy_fragment_variables=True,
         )
         visited = []