Redesign Ref to use _APIRequestor instead of StripeClient

Ref now stores _requestor and uses requestor.request() for fetch,
matching the Event.fetch_related_object pattern. Added _construct_from
classmethod so the deserialization pipeline can instantiate Ref with
the requestor. Updated _convert_to_stripe_object to handle Ref types.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Committed-By-Agent: claude

Author: jar-stripe

stripe/_util.py

@@ -268,12 +268,21 @@ def _convert_to_stripe_object(
         else:
             klass = StripeObject
 
-        obj = klass._construct_from(
-            values=resp,
-            last_response=stripe_response,
-            requestor=requestor,
-            api_mode=api_mode,
-        )
+        from stripe.v2._ref import Ref
+
+        if issubclass(klass, Ref):
+            obj = klass._construct_from(
+                values=resp,
+                requestor=requestor,
+                api_mode=api_mode,
+            )
+        else:
+            obj = klass._construct_from(
+                values=resp,
+                last_response=stripe_response,
+                requestor=requestor,
+                api_mode=api_mode,
+            )
 
         # We only need to update _retrieve_params when special params were
         # actually passed. Otherwise, leave it as is as the list / search result

stripe/v2/_ref.py

@@ -4,10 +4,11 @@
 
 from typing_extensions import TYPE_CHECKING
 
-from stripe._util import get_api_mode
+from stripe._api_mode import ApiMode
 
 if TYPE_CHECKING:
-    from stripe._stripe_client import StripeClient
+    from stripe._api_requestor import _APIRequestor
+    from stripe._stripe_response import StripeResponse
 
 T = TypeVar("T")
 
@@ -30,50 +31,69 @@ class Ref(Generic[T]):
     url: str
     """The URL path that can be used to fetch the referenced resource."""
 
-    _client: Optional["StripeClient"]
+    _requestor: Optional["_APIRequestor"]
 
     def __init__(
-        self, parsed_body: Dict[str, Any], client: Optional["StripeClient"]
+        self,
+        parsed_body: Dict[str, Any],
+        requestor: Optional["_APIRequestor"],
     ) -> None:
         self.type = parsed_body["type"]
         self.id = parsed_body["id"]
         self.url = parsed_body["url"]
-        self._client = client
+        self._requestor = requestor
+
+    @classmethod
+    def _construct_from(
+        cls,
+        *,
+        values: Dict[str, Any],
+        last_response: Optional["StripeResponse"] = None,
+        requestor: "_APIRequestor",
+        api_mode: ApiMode,
+    ) -> "Ref[Any]":
+        return cls(values, requestor=requestor)
 
     def fetch(self) -> T:
         """
         Fetches the full API resource that this reference points to.
 
-        Raises ``RuntimeError`` if no client is associated with this ``Ref``.
+        Raises ``RuntimeError`` if no requestor is associated with this ``Ref``.
         """
-        if self._client is None:
+        if self._requestor is None:
             raise RuntimeError(
-                "Cannot call fetch() on a Ref that has no associated StripeClient."
+                "Cannot call fetch() on a Ref that has no associated requestor."
             )
-        response = self._client.raw_request(
-            "get",
-            self.url,
-            usage=["ref_fetch"],
+        return cast(
+            T,
+            self._requestor.request(
+                "get",
+                self.url,
+                base_address="api",
+                usage=["ref_fetch"],
+            ),
         )
-        return cast(T, self._client.deserialize(response, api_mode=get_api_mode(self.url)))
 
     async def fetch_async(self) -> T:
         """
         Fetches the full API resource that this reference points to,
         using an async HTTP request.
 
-        Raises ``RuntimeError`` if no client is associated with this ``Ref``.
+        Raises ``RuntimeError`` if no requestor is associated with this ``Ref``.
         """
-        if self._client is None:
+        if self._requestor is None:
             raise RuntimeError(
-                "Cannot call fetch_async() on a Ref that has no associated StripeClient."
+                "Cannot call fetch_async() on a Ref that has no associated requestor."
             )
-        response = await self._client.raw_request_async(
-            "get",
-            self.url,
-            usage=["ref_fetch", "ref_fetch_async"],
+        return cast(
+            T,
+            await self._requestor.request_async(
+                "get",
+                self.url,
+                base_address="api",
+                usage=["ref_fetch", "ref_fetch_async"],
+            ),
         )
-        return cast(T, self._client.deserialize(response, api_mode=get_api_mode(self.url)))
 
     def __repr__(self) -> str:
         return f"<Ref type={self.type} id={self.id} url={self.url}>"

tests/test_v2_ref.py

@@ -14,7 +14,7 @@ def test_construction(self):
             "id": "mtr_123",
             "url": "/v1/billing/meters/mtr_123",
         }
-        ref: Ref[Meter] = Ref(parsed, client=None)
+        ref: Ref[Meter] = Ref(parsed, requestor=None)
 
         assert ref.type == "billing.meter"
         assert ref.id == "mtr_123"
@@ -26,29 +26,29 @@ def test_repr(self):
             "id": "mtr_123",
             "url": "/v1/billing/meters/mtr_123",
         }
-        ref: Ref[Meter] = Ref(parsed, client=None)
+        ref: Ref[Meter] = Ref(parsed, requestor=None)
         assert repr(ref) == "<Ref type=billing.meter id=mtr_123 url=/v1/billing/meters/mtr_123>"
 
-    def test_fetch_raises_without_client(self):
+    def test_fetch_raises_without_requestor(self):
         parsed = {
             "type": "billing.meter",
             "id": "mtr_123",
             "url": "/v1/billing/meters/mtr_123",
         }
-        ref: Ref[Meter] = Ref(parsed, client=None)
+        ref: Ref[Meter] = Ref(parsed, requestor=None)
 
-        with pytest.raises(RuntimeError, match="no associated StripeClient"):
+        with pytest.raises(RuntimeError, match="no associated requestor"):
             ref.fetch()
 
-    def test_fetch_async_raises_without_client(self):
+    def test_fetch_async_raises_without_requestor(self):
         parsed = {
             "type": "billing.meter",
             "id": "mtr_123",
             "url": "/v1/billing/meters/mtr_123",
         }
-        ref: Ref[Meter] = Ref(parsed, client=None)
+        ref: Ref[Meter] = Ref(parsed, requestor=None)
 
-        with pytest.raises(RuntimeError, match="no associated StripeClient"):
+        with pytest.raises(RuntimeError, match="no associated requestor"):
             import asyncio
             asyncio.get_event_loop().run_until_complete(ref.fetch_async())
 
@@ -78,7 +78,7 @@ def test_fetch_v1_resource(self, http_client_mock: HTTPClientMock):
             "id": "mtr_123",
             "url": meter_path,
         }
-        ref: Ref[Meter] = Ref(parsed, client=client)
+        ref: Ref[Meter] = Ref(parsed, requestor=client._requestor)
         result = ref.fetch()
 
         http_client_mock.assert_requested(
@@ -121,7 +121,7 @@ def test_fetch_v2_resource(self, http_client_mock: HTTPClientMock):
             "id": "evt_123",
             "url": event_path,
         }
-        ref: Ref[Event] = Ref(parsed, client=client)
+        ref: Ref[Event] = Ref(parsed, requestor=client._requestor)
         result = ref.fetch()
 
         http_client_mock.assert_requested(