Add extensions support to GraphQLRequest

Support the `extensions` field on GraphQL requests, as defined in the
GraphQL over HTTP spec. This allows passing protocol extensions (e.g.
persisted query IDs) as a top-level key in the request payload.

Closes #590

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: magicmark

gql/graphql_request.py

@@ -13,6 +13,7 @@ def __init__(
         *,
         variable_values: Optional[Dict[str, Any]] = None,
         operation_name: Optional[str] = None,
+        extensions: Optional[Dict[str, Any]] = None,
     ):
         """Initialize a GraphQL request.
 
@@ -21,6 +22,10 @@ def __init__(
         :param variable_values: Dictionary of input parameters (Default: None).
         :param operation_name: Name of the operation that shall be executed.
             Only required in multi-operation documents (Default: None).
+        :param extensions: Dictionary of protocol extensions (Default: None).
+            This is passed as the top-level ``extensions`` key in the request
+            payload, as defined in the `GraphQL over HTTP spec
+            <https://github.com/graphql/graphql-over-http>`_.
         :return: a :class:`GraphQLRequest <gql.GraphQLRequest>`
                  which can be later executed or subscribed by a
                  :class:`Client <gql.client.Client>`, by an
@@ -42,9 +47,12 @@ def __init__(
                 variable_values = request.variable_values
             if operation_name is None:
                 operation_name = request.operation_name
+            if extensions is None:
+                extensions = request.extensions
 
         self.variable_values: Optional[Dict[str, Any]] = variable_values
         self.operation_name: Optional[str] = operation_name
+        self.extensions: Optional[Dict[str, Any]] = extensions
 
     def serialize_variable_values(self, schema: GraphQLSchema) -> "GraphQLRequest":
 
@@ -61,6 +69,7 @@ def serialize_variable_values(self, schema: GraphQLSchema) -> "GraphQLRequest":
                 operation_name=self.operation_name,
             ),
             operation_name=self.operation_name,
+            extensions=self.extensions,
         )
 
     @property
@@ -74,6 +83,9 @@ def payload(self) -> Dict[str, Any]:
         if self.variable_values:
             payload["variables"] = self.variable_values
 
+        if self.extensions:
+            payload["extensions"] = self.extensions
+
         return payload
 
     def __str__(self):

tests/test_graphql_request.py

@@ -236,3 +236,57 @@ def test_graphql_request_init_with_graphql_request():
     assert request_1.variable_values["money"] == money_value_1
     assert request_2.variable_values["money"] == money_value_1
     assert request_3.variable_values["money"] == money_value_2
+
+
+def test_graphql_request_extensions_in_payload():
+    extensions = {"persistedQuery": {"version": 1, "sha256Hash": "abc123"}}
+    request = GraphQLRequest("{balance}", extensions=extensions)
+
+    payload = request.payload
+    assert payload["extensions"] == extensions
+
+
+def test_graphql_request_extensions_not_in_payload_when_none():
+    request = GraphQLRequest("{balance}")
+    assert "extensions" not in request.payload
+
+
+def test_graphql_request_extensions_copied_from_graphql_request():
+    extensions = {"persistedQuery": {"version": 1, "sha256Hash": "abc123"}}
+    request_1 = GraphQLRequest("{balance}", extensions=extensions)
+    request_2 = GraphQLRequest(request_1)
+
+    assert request_2.extensions == extensions
+    assert request_2.payload["extensions"] == extensions
+
+
+def test_graphql_request_extensions_override_from_graphql_request():
+    extensions_1 = {"persistedQuery": {"version": 1, "sha256Hash": "abc123"}}
+    extensions_2 = {"custom": "value"}
+    request_1 = GraphQLRequest("{balance}", extensions=extensions_1)
+    request_2 = GraphQLRequest(request_1, extensions=extensions_2)
+
+    assert request_2.extensions == extensions_2
+
+
+def test_graphql_request_extensions_preserved_by_serialize_variable_values():
+    extensions = {"persistedQuery": {"version": 1, "sha256Hash": "abc123"}}
+    money_value = Money(10, "DM")
+
+    request = GraphQLRequest(
+        "query myquery($money: Money) {toEuros(money: $money)}",
+        variable_values={"money": money_value},
+        extensions=extensions,
+    )
+
+    serialized = request.serialize_variable_values(schema)
+    assert serialized.extensions == extensions
+    assert serialized.payload["extensions"] == extensions
+
+
+def test_graphql_request_str_includes_extensions():
+    extensions = {"key": "value"}
+    request = GraphQLRequest("{balance}", extensions=extensions)
+    result = str(request)
+    assert "extensions" in result
+    assert "'key': 'value'" in result