From 023a25c06a20f69859e8c10272466b702fdd3c2f Mon Sep 17 00:00:00 2001 From: zacchua-stripe Date: Tue, 10 Nov 2026 13:54:12 -0800 Subject: [PATCH 1/7] =?UTF-8?q?Omit=20API=20keys=20from=20StripeObject=20p?= =?UTF-8?q?ickles=20and=20add=20explicit=20key=20rebinding=20=F0=9F=AA=BF?= =?UTF-8?q?=E2=9C=A8=20(#1959)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [🪿] Omit API keys from StripeObject pickles Prevent credentials from leaking into pickle-backed caches and queues. Add graph-wide set_api_key() binding so consumers can supply their own credentials while preserving routing and destination-global fallback. Include regression tests and v16 migration guidance. Existing stored pickles remain sensitive and are not sanitized by this change. Committed-By-Agent: goose Orbit-Session-Id: 6c16ab70-1263-4d0e-a050-72c9b9f30280 * [🪿] try to deslop Consolidate overlapping pickle round-trip and credential-rebinding tests to remove duplicate setup and serialization. Retain coverage for supported pickle protocols, destination-global fallback, nested rebinding, routing preservation, and credential-free re-pickling without changing implementation behavior. Verified 172 targeted tests pass, along with formatting, linting, and git diff whitespace checks. Committed-By-Agent: goose Orbit-Session-Id: 6c16ab70-1263-4d0e-a050-72c9b9f30280 * [🪿] Align pickle credential migration with v17 Document global fallback and explicit recursive key rebinding. Strengthen nested requestor preservation coverage and remove task-specific README edits. Committed-By-Agent: goose Orbit-Session-Id: 6c16ab70-1263-4d0e-a050-72c9b9f30280 * [🪿] try to deslop Remove redundant nested-resource serialization and assertions already covered by payload equality and credential-absence checks on re-pickled bytes. Recursive rebinding, cycle handling, routing preservation, standalone metadata serialization, and request-boundary coverage remain intact. Validated with 101 passing StripeObject tests, formatting, linting, and git diff --check. Committed-By-Agent: goose Orbit-Session-Id: 6c16ab70-1263-4d0e-a050-72c9b9f30280 * [🪿] Update PyPI publishing action to v1.14.3 Fix the workflow security check failing on GHSA-5xjx-3w67-w9x9. Pin the patched release to its verified commit SHA. https: //github.com/advisories/GHSA-5xjx-3w67-w9x9 Committed-By-Agent: goose Orbit-Session-Id: 6c16ab70-1263-4d0e-a050-72c9b9f30280 * [🪿] Revert unrelated PyPI publishing action upgrade Keep CI configuration unchanged to scope this branch to pickle credentials. Committed-By-Agent: goose Orbit-Session-Id: 6c16ab70-1263-4d0e-a050-72c9b9f30280 * [🪿] Update pickle credential changefile wording and filename * [🪿] Simplify v17 pickle migration guidance Use concise examples to explain explicit API-key rebinding and global fallback. Clarify that rebinding preserves current requestor configuration, not the producer's custom HTTP client. * [🪿] Replace set_api_key with per-call API keys on instance methods Remove StripeObject.set_api_key() and instead accept an api_key on the instance methods that previously could not take one: refresh(), refresh_async(), save(), and auto_paging_iter() on ListObject, SearchResultObject, and their V2 equivalents. delete() and generated instance methods already accept per-call request options. Co-Authored-By: Claude Opus 5.5 Committed-By-Agent: claude * [🪿] Trim pickle credential changefile wording Co-Authored-By: Claude Opus 5.5 Committed-By-Agent: claude * Require explicit API key reattachment after unpickling Committed-By-Agent: codex Co-authored-by: codex * Keep serialized placeholders in requestors and guard requests centrally Committed-By-Agent: codex Co-authored-by: codex * Clarify API key reattachment wording in changefile Committed-By-Agent: codex Co-authored-by: codex * Clarify API key reattachment migration guidance Committed-By-Agent: codex Co-authored-by: codex * Address serialization documentation review feedback Committed-By-Agent: codex Co-authored-by: codex * Make migration guide before/after examples equivalent Keep the Before and After snippets identical apart from the reattach step, and move the list/event usage into a separate example. Co-Authored-By: Claude Opus 5.5 Committed-By-Agent: claude --------- Co-authored-by: Claude Opus 5.5 Co-authored-by: codex --- ...30_zacchua_omit-pickled-api-keys.change.md | 7 + .hark/migration-guides/v17.md | 37 ++ stripe/_api_requestor.py | 13 + stripe/_stripe_object.py | 49 ++- tests/api_resources/test_list_object.py | 91 +++++ tests/api_resources/test_list_object_v2.py | 28 ++ .../test_search_result_object.py | 30 ++ tests/test_stripe_object.py | 373 +++++++++++++++++- tests/test_v2_event.py | 28 ++ 9 files changed, 636 insertions(+), 20 deletions(-) create mode 100644 .hark/changes/2026-10-30_zacchua_omit-pickled-api-keys.change.md create mode 100644 .hark/migration-guides/v17.md diff --git a/.hark/changes/2026-10-30_zacchua_omit-pickled-api-keys.change.md b/.hark/changes/2026-10-30_zacchua_omit-pickled-api-keys.change.md new file mode 100644 index 000000000..76dc33045 --- /dev/null +++ b/.hark/changes/2026-10-30_zacchua_omit-pickled-api-keys.change.md @@ -0,0 +1,7 @@ +--- +title: Omit API keys from pickled StripeObjects +semver_level: major +--- +StripeObject pickles no longer preserve API keys. Before making requests through an unpickled object, call `reattach_api_key(api_key)`. This also reattaches API keys to nested objects. + +See the [v17 migration guide](https://github.com/stripe/stripe-python/blob/master/.hark/migration-guides/v17.md#api-keys-are-no-longer-preserved-in-pickled-stripeobjects) for details. diff --git a/.hark/migration-guides/v17.md b/.hark/migration-guides/v17.md new file mode 100644 index 000000000..a7a654b8c --- /dev/null +++ b/.hark/migration-guides/v17.md @@ -0,0 +1,37 @@ +# Migration guide for v17 +## API keys are no longer preserved in pickled StripeObjects +This affects integrations that persist StripeObjects in caches or queues and then make requests through the restored objects. + +Pickling now replaces API keys with a placeholder, including on nested objects. Unpickled objects retain their data, connected-account routing, and API version but have no API key. Before making requests through an unpickled object, call `reattach_api_key()` with a key from secure configuration: + +```python +# Before +customer = pickle.loads(trusted_cached_bytes) +customer.refresh() + +# After +customer = pickle.loads(trusted_cached_bytes) +customer.reattach_api_key(api_key) +customer.refresh() +``` + +Reattach the API key the same way on unpickled lists and events before making requests through them: + +```python +customers = pickle.loads(trusted_cached_list_bytes) +customers.reattach_api_key(api_key) +for customer in customers.auto_paging_iter(): + ... + +event = pickle.loads(trusted_cached_event_bytes) +event.reattach_api_key(api_key) +related_object = event.fetch_related_object() +``` + +`reattach_api_key()` also attaches API keys to nested unpickled objects. Each retains its saved API version and connected account. Nested objects that already have an API key keep it. Reattachment does not change `stripe.api_key`, and pickling the object again omits the reattached key. + +Requests before reattachment raise `AuthenticationError` with instructions to call `reattach_api_key()`, even if you set a global or per-call API key. + +Calling `reattach_api_key()` more than once, or on an object whose API key wasn't replaced with the serialization placeholder, raises `ValueError`. Passing an empty key or the serialization placeholder also raises `ValueError`. + +This behavior applies to pickles created with v17. Pickles created with earlier versions can still contain API keys. Remove or replace those stored pickles according to your application's storage policy. diff --git a/stripe/_api_requestor.py b/stripe/_api_requestor.py index 6224c5e6d..9d0bd36e6 100644 --- a/stripe/_api_requestor.py +++ b/stripe/_api_requestor.py @@ -61,6 +61,7 @@ from stripe._base_address import BaseAddress from stripe._api_mode import ApiMode +from stripe._stripe_object import API_KEY_SERIALIZATION_CONSTANT if TYPE_CHECKING: from stripe._app_info import AppInfo @@ -165,6 +166,12 @@ def _new_requestor_with_options( """ Returns a new _APIRequestor instance with the same HTTP client but a (potentially) updated set of options. Useful for ensuring the original isn't modified, but any options the original had are still used. """ + if self.api_key == API_KEY_SERIALIZATION_CONSTANT: + raise error.AuthenticationError( + "This object was unpickled without API credentials. " + "Call reattach_api_key(api_key) on the object before making requests." + ) + options = options or {} new_options = self._options.to_dict() for key in PERSISTENT_OPTIONS_KEYS: @@ -673,6 +680,12 @@ def _args_for_request_with_retries( """ Mechanism for issuing an API call. Used by request_raw and request_raw_async. """ + if self.api_key == API_KEY_SERIALIZATION_CONSTANT: + raise error.AuthenticationError( + "This object was unpickled without API credentials. " + "Call reattach_api_key(api_key) on the object before making requests." + ) + request_options = merge_options(self._options, options) # Special stripe_version handling for v2 requests: diff --git a/stripe/_stripe_object.py b/stripe/_stripe_object.py index 8fe6d87d7..56ac30eb8 100644 --- a/stripe/_stripe_object.py +++ b/stripe/_stripe_object.py @@ -49,6 +49,9 @@ from stripe._api_requestor import _APIRequestor # pyright: ignore[reportPrivateUsage] +API_KEY_SERIALIZATION_CONSTANT = "API_KEY_SERIALIZATION_CONSTANT" + + @overload def _compute_diff( current: Dict[str, Any], previous: Optional[Dict[str, Any]] @@ -156,6 +159,50 @@ def stripe_account(self): def stripe_version(self): return self._requestor.stripe_version + def reattach_api_key(self, api_key: str) -> None: + """Attach credentials to an unpickled object and its nested objects. + + Each object retains its saved API version and connected account. + Objects that already have credentials cannot be reattached. + """ + if self.api_key != API_KEY_SERIALIZATION_CONSTANT: + raise ValueError( + "API credentials can only be reattached to an unpickled " + "object that has not already been reattached." + ) + if ( + not isinstance(cast(object, api_key), str) + or not api_key.strip() + or api_key == API_KEY_SERIALIZATION_CONSTANT + ): + raise ValueError("api_key must be a non-empty, valid API key.") + + from stripe._api_requestor import _APIRequestor # pyright: ignore[reportPrivateUsage] + + seen: Set[int] = set() + + def reattach(value: Any) -> None: + if id(value) in seen: + return + seen.add(id(value)) + if isinstance(value, StripeObject): + if value.api_key == API_KEY_SERIALIZATION_CONSTANT: + value._requestor = _APIRequestor._global_with_options( # pyright: ignore[reportPrivateUsage] + api_key=api_key, + stripe_version=value.stripe_version, + stripe_account=value.stripe_account, + ) + for nested in value._data.values(): + reattach(nested) + elif isinstance(value, dict): + for nested in cast(Dict[Any, Any], value).values(): + reattach(nested) + elif isinstance(value, (list, tuple)): + for nested in cast(Union[List[Any], Tuple[Any, ...]], value): + reattach(nested) + + reattach(self) + @property def last_response(self) -> Optional[StripeResponse]: return self._last_response @@ -298,7 +345,7 @@ def __reduce__(self) -> Tuple[Any, ...]: type(self), # callable ( # args getattr(self, "id", None), - self.api_key, + API_KEY_SERIALIZATION_CONSTANT, self.stripe_version, self.stripe_account, ), diff --git a/tests/api_resources/test_list_object.py b/tests/api_resources/test_list_object.py index 02568c4b7..895094d36 100644 --- a/tests/api_resources/test_list_object.py +++ b/tests/api_resources/test_list_object.py @@ -1,4 +1,5 @@ import json +import pickle import pytest @@ -297,6 +298,68 @@ def test_iter_two_pages(self, http_client_mock): assert seen == ["pm_123", "pm_124", "pm_125", "pm_126"] + @pytest.fixture + def restored_list(self, monkeypatch): + lo = stripe.ListObject.construct_from( + self.pageable_model_response(["pm_123"], True), + "producer-key-sentinel", + stripe_account="example-account", + ) + monkeypatch.setattr(stripe, "api_key", None) + restored = pickle.loads(pickle.dumps(lo)) + restored.reattach_api_key("worker-key-sentinel") + return restored + + def test_iter_uses_reattached_api_key_on_every_page( + self, http_client_mock, restored_list + ): + http_client_mock.stub_request( + "get", + path="/v1/pageablemodels", + query_string="starting_after=pm_123", + rbody=json.dumps(self.pageable_model_response(["pm_124"], True)), + ) + http_client_mock.stub_request( + "get", + path="/v1/pageablemodels", + query_string="starting_after=pm_124", + rbody=json.dumps(self.pageable_model_response(["pm_125"], False)), + ) + + seen = [item["id"] for item in restored_list.auto_paging_iter()] + + assert seen == ["pm_123", "pm_124", "pm_125"] + for starting_after in ("pm_123", "pm_124"): + http_client_mock.assert_requested( + "get", + path="/v1/pageablemodels", + query_string=f"starting_after={starting_after}", + api_key="worker-key-sentinel", + stripe_account="example-account", + ) + + def test_iter_reverse_uses_reattached_api_key( + self, http_client_mock, restored_list + ): + restored_list._retrieve_params = {"ending_before": "pm_124"} + http_client_mock.stub_request( + "get", + path="/v1/pageablemodels", + query_string="ending_before=pm_123", + rbody=json.dumps(self.pageable_model_response(["pm_122"], False)), + ) + + seen = [item["id"] for item in restored_list.auto_paging_iter()] + + assert seen == ["pm_123", "pm_122"] + http_client_mock.assert_requested( + "get", + path="/v1/pageablemodels", + query_string="ending_before=pm_123", + api_key="worker-key-sentinel", + stripe_account="example-account", + ) + def test_iter_reverse(self, http_client_mock): lo = stripe.ListObject.construct_from( self.pageable_model_response(["pm_125", "pm_126"], True), "mykey" @@ -655,6 +718,34 @@ async def test_iter_one_page(self, http_client_mock): assert seen == ["pm_123", "pm_124"] + @pytest.mark.anyio + async def test_iter_uses_reattached_api_key( + self, http_client_mock, monkeypatch + ): + lo = stripe.ListObject.construct_from( + self.pageable_model_response(["pm_123"], True), + "producer-key-sentinel", + ) + monkeypatch.setattr(stripe, "api_key", None) + restored = pickle.loads(pickle.dumps(lo)) + restored.reattach_api_key("worker-key-sentinel") + http_client_mock.stub_request( + "get", + path="/v1/pageablemodels", + query_string="starting_after=pm_123", + rbody=json.dumps(self.pageable_model_response(["pm_124"], False)), + ) + + seen = [item["id"] async for item in restored.auto_paging_iter()] + + assert seen == ["pm_123", "pm_124"] + http_client_mock.assert_requested( + "get", + path="/v1/pageablemodels", + query_string="starting_after=pm_123", + api_key="worker-key-sentinel", + ) + @pytest.mark.anyio async def test_iter_two_pages(self, http_client_mock): lo = stripe.ListObject.construct_from( diff --git a/tests/api_resources/test_list_object_v2.py b/tests/api_resources/test_list_object_v2.py index 84759e873..a7581b142 100644 --- a/tests/api_resources/test_list_object_v2.py +++ b/tests/api_resources/test_list_object_v2.py @@ -1,6 +1,7 @@ from __future__ import absolute_import, division, print_function import json +import pickle import pytest @@ -147,6 +148,33 @@ def test_iter_forwards_api_key(self, http_client_mock: HTTPClientMock): api_key="sk_test_iter_forwards_options", ) + def test_iter_uses_reattached_api_key(self, http_client_mock, monkeypatch): + lo = ListObject.construct_from( + self.pageable_model_response( + ["pm_123"], "/v2/pageablemodels?page=page_2" + ), + "producer-key-sentinel", + ) + monkeypatch.setattr(stripe, "api_key", None) + restored = pickle.loads(pickle.dumps(lo)) + restored.reattach_api_key("worker-key-sentinel") + http_client_mock.stub_request( + "get", + path="/v2/pageablemodels", + query_string="page=page_2", + rbody=json.dumps(self.pageable_model_response(["pm_124"], None)), + ) + + seen = [item["id"] for item in restored.auto_paging_iter()] + + assert seen == ["pm_123", "pm_124"] + http_client_mock.assert_requested( + "get", + path="/v2/pageablemodels", + query_string="page=page_2", + api_key="worker-key-sentinel", + ) + class TestAutoPagingAsync: @staticmethod diff --git a/tests/api_resources/test_search_result_object.py b/tests/api_resources/test_search_result_object.py index 9db977921..5d640e374 100644 --- a/tests/api_resources/test_search_result_object.py +++ b/tests/api_resources/test_search_result_object.py @@ -1,4 +1,5 @@ import json +import pickle import pytest @@ -256,6 +257,35 @@ def test_iter_two_pages(self, http_client_mock): assert seen == ["pm_123", "pm_124", "pm_125", "pm_126"] + def test_iter_uses_reattached_api_key(self, http_client_mock, monkeypatch): + sro = stripe.SearchResultObject.construct_from( + self.pageable_model_response(["pm_123"], True, "token"), + "producer-key-sentinel", + stripe_account="example-account", + ) + monkeypatch.setattr(stripe, "api_key", None) + restored = pickle.loads(pickle.dumps(sro)) + restored.reattach_api_key("worker-key-sentinel") + http_client_mock.stub_request( + "get", + path="/v1/pageablemodels", + query_string="page=token", + rbody=json.dumps( + self.pageable_model_response(["pm_124"], False, None) + ), + ) + + seen = [item["id"] for item in restored.auto_paging_iter()] + + assert seen == ["pm_123", "pm_124"] + http_client_mock.assert_requested( + "get", + path="/v1/pageablemodels", + query_string="page=token", + api_key="worker-key-sentinel", + stripe_account="example-account", + ) + class TestAutoPagingAsync: @staticmethod diff --git a/tests/test_stripe_object.py b/tests/test_stripe_object.py index aecd64938..6873b915a 100644 --- a/tests/test_stripe_object.py +++ b/tests/test_stripe_object.py @@ -8,7 +8,7 @@ import stripe from stripe._invoice import Invoice -from stripe._stripe_object import StripeObject +from stripe._stripe_object import API_KEY_SERIALIZATION_CONSTANT, StripeObject # We use this because it has a map, "restriction.currency_options" from string -> CurrencyOptions nested class. SAMPLE_PROMOTION_CODE = json.loads( @@ -274,30 +274,365 @@ def test_repr(self): assert '"date": 1511136000' in res assert '"dec": "1.23"' in res - def test_pickling(self): - obj = StripeObject("foo", "bar", myparam=5) - - obj["object"] = "boo" - obj.refresh_from( + @pytest.mark.parametrize("protocol", range(pickle.HIGHEST_PROTOCOL + 1)) + @pytest.mark.parametrize( + "destination_key", [None, "destination-key-sentinel"] + ) + def test_pickling(self, protocol, destination_key, monkeypatch): + obj = stripe.Customer.construct_from( { - "fala": "lalala", - # ensures that empty strings are correctly unpickled in Py3 - "emptystring": "", + "id": "resource", + "object": "customer", + "description": "example", + "metadata": {"emptystring": ""}, }, - api_key="bar", - partial=True, + "producer-key-sentinel", + stripe_version="2017-08-15", + stripe_account="example-account", + ) + obj.metadata.api_key = "nested-key-sentinel" + nested = stripe.Customer.construct_from( + {"id": "nested-resource", "object": "customer"}, + "nested-key-sentinel", + stripe_version="2018-02-28", + stripe_account="nested-example-account", + ) + obj.containers = [{"nested": nested}] + original_requestor = obj._requestor + payload = obj.to_dict() + + for value in (obj.metadata, obj): + assert value.__reduce__()[1][1] == API_KEY_SERIALIZATION_CONSTANT + pickled = pickle.dumps(value, protocol=protocol) + assert b"producer-key-sentinel" not in pickled + assert b"nested-key-sentinel" not in pickled + + monkeypatch.setattr(stripe, "api_key", destination_key) + restored = pickle.loads(pickled) + + assert type(restored) is stripe.Customer + assert restored.to_dict() == payload + for value in (restored, restored.metadata): + assert value.api_key == API_KEY_SERIALIZATION_CONSTANT + assert value.stripe_version == "2017-08-15" + assert value.stripe_account == "example-account" + assert obj.api_key == "producer-key-sentinel" + assert obj.metadata.api_key == "nested-key-sentinel" + assert obj._requestor is original_requestor + assert obj.to_dict() == payload + + restored_nested = restored.containers[0]["nested"] + assert restored_nested.api_key == API_KEY_SERIALIZATION_CONSTANT + assert restored_nested.stripe_account == "nested-example-account" + assert restored_nested.stripe_version == "2018-02-28" + + restored.reattach_api_key("reattached-key-sentinel") + for value in (restored, restored.metadata, restored_nested): + assert value.api_key == "reattached-key-sentinel" + assert restored_nested.stripe_account == "nested-example-account" + assert restored_nested.stripe_version == "2018-02-28" + assert stripe.api_key == destination_key + + pickled = pickle.dumps(restored, protocol=protocol) + for key in ( + b"producer-key-sentinel", + b"nested-key-sentinel", + b"destination-key-sentinel", + b"reattached-key-sentinel", + ): + assert key not in pickled + + def test_pickling_verified_webhook(self, monkeypatch): + payload = json.dumps( + { + "object": "event", + "data": { + "object": {"object": "customer", "metadata": {"empty": ""}} + }, + } ) + monkeypatch.setattr(stripe, "api_key", "producer-key-sentinel") + signature = stripe.WebhookSignature.generate_signature_header( + payload, "webhook-test-secret" + ) + event = stripe.Webhook.construct_event( + payload, signature, "webhook-test-secret" + ) + pickled = pickle.dumps(event) + assert b"producer-key-sentinel" not in pickled + monkeypatch.setattr(stripe, "api_key", "destination-key-sentinel") + restored = pickle.loads(pickled) + + assert type(restored) is stripe.Event + assert type(restored.data.object) is stripe.Customer + assert restored.to_dict() == event.to_dict() + for value in ( + restored, + restored.data, + restored.data.object, + restored.data.object.metadata, + ): + assert value.api_key == API_KEY_SERIALIZATION_CONSTANT + assert event.api_key == "producer-key-sentinel" - assert obj.fala == "lalala" + @pytest.fixture + def restored_customer(self, monkeypatch): + obj = stripe.Customer.construct_from( + {"id": "resource", "object": "customer"}, + "producer-key-sentinel", + stripe_account="example-account", + ) + monkeypatch.setattr(stripe, "api_key", None) + return pickle.loads(pickle.dumps(obj)) + + @pytest.mark.parametrize("global_key", [None, "global-key-sentinel"]) + @pytest.mark.parametrize("per_call_key", [None, "per-call-key-sentinel"]) + def test_restored_delete_requires_reattachment( + self, + http_client_mock, + restored_customer, + monkeypatch, + global_key, + per_call_key, + ): + monkeypatch.setattr(stripe, "api_key", global_key) + with pytest.raises( + stripe.AuthenticationError, match="reattach_api_key" + ): + restored_customer.delete(api_key=per_call_key) + http_client_mock.assert_no_request() + + def test_reattach_api_key(self, http_client_mock, restored_customer): + restored_customer.reattach_api_key("worker-key-sentinel") + http_client_mock.stub_request( + "get", + path="/v1/customers/resource", + rbody='{"id": "resource", "object": "customer"}', + ) + restored_customer.refresh() + http_client_mock.assert_requested( + "get", + path="/v1/customers/resource", + api_key="worker-key-sentinel", + stripe_account="example-account", + ) + assert ( + pickle.loads(pickle.dumps(restored_customer)).api_key + == API_KEY_SERIALIZATION_CONSTANT + ) - pickled = pickle.dumps(obj) - newobj = pickle.loads(pickled) + @pytest.mark.parametrize( + "key", [None, "", " ", 123, API_KEY_SERIALIZATION_CONSTANT] + ) + def test_reattach_api_key_rejects_invalid_keys( + self, restored_customer, key + ): + with pytest.raises(ValueError, match="api_key"): + restored_customer.reattach_api_key(key) + assert restored_customer.api_key == API_KEY_SERIALIZATION_CONSTANT + + def test_reattach_api_key_rejects_attached_objects( + self, restored_customer + ): + with pytest.raises(ValueError, match="only be reattached"): + stripe.Customer("cus_123").reattach_api_key("key") + restored_customer.reattach_api_key("key") + with pytest.raises(ValueError, match="only be reattached"): + restored_customer.reattach_api_key("other-key") + assert restored_customer.api_key == "key" + + def test_reattach_api_key_handles_cycles_and_attached_children( + self, restored_customer + ): + attached = StripeObject(api_key="child-key") + restored_customer._data["nested"] = [ + restored_customer, + {"attached": attached}, + ] + restored_customer.reattach_api_key("key") + assert restored_customer.api_key == "key" + assert attached.api_key == "child-key" + + @pytest.mark.parametrize("copy_method", [copy, deepcopy]) + def test_copy_detached_object( + self, restored_customer, monkeypatch, copy_method + ): + monkeypatch.setattr(stripe, "api_key", "global-key") + copied = copy_method(restored_customer) + assert copied.api_key == API_KEY_SERIALIZATION_CONSTANT + assert copied.stripe_account == "example-account" + with pytest.raises( + stripe.AuthenticationError, match="reattach_api_key" + ): + copied._request( + "get", "/v1/customers/resource", base_address="api" + ) + + @pytest.mark.parametrize("method", ["_request", "_request_stream"]) + @pytest.mark.parametrize("per_call_key", [None, "per-call-key-sentinel"]) + def test_detached_request_guard( + self, restored_customer, method, http_client_mock, per_call_key + ): + with pytest.raises( + stripe.AuthenticationError, match="reattach_api_key" + ): + getattr(restored_customer, method)( + "get", + "/v1/customers/resource", + params={"api_key": per_call_key}, + ) + http_client_mock.assert_no_request() - assert newobj.id == "foo" - assert newobj.api_key == "bar" - assert newobj["object"] == "boo" - assert newobj.fala == "lalala" - assert newobj.emptystring == "" + @pytest.mark.anyio + @pytest.mark.parametrize( + "method", ["_request_async", "_request_stream_async"] + ) + @pytest.mark.parametrize("per_call_key", [None, "per-call-key-sentinel"]) + async def test_detached_async_request_guard( + self, restored_customer, method, http_client_mock, per_call_key + ): + with pytest.raises( + stripe.AuthenticationError, match="reattach_api_key" + ): + await getattr(restored_customer, method)( + "get", + "/v1/customers/resource", + params={"api_key": per_call_key}, + ) + http_client_mock.assert_no_request() + + def test_detached_option_setters_require_reattachment( + self, restored_customer + ): + with pytest.raises( + stripe.AuthenticationError, match="reattach_api_key" + ): + restored_customer.api_key = "key" + with pytest.raises( + stripe.AuthenticationError, match="reattach_api_key" + ): + restored_customer.refresh_from({}, api_key="key") + + def test_restored_refresh_uses_reattached_api_key( + self, http_client_mock, restored_customer + ): + restored_customer.reattach_api_key("worker-key-sentinel") + http_client_mock.stub_request( + "get", + path="/v1/customers/resource", + rbody='{"id": "resource", "object": "customer", "description": "refreshed"}', + ) + + assert restored_customer.refresh() is restored_customer + + http_client_mock.assert_requested( + "get", + path="/v1/customers/resource", + api_key="worker-key-sentinel", + stripe_account="example-account", + ) + assert restored_customer.description == "refreshed" + assert stripe.api_key is None + assert b"worker-key-sentinel" not in pickle.dumps(restored_customer) + + @pytest.mark.anyio + async def test_restored_refresh_async_uses_reattached_api_key( + self, http_client_mock, restored_customer + ): + restored_customer.reattach_api_key("worker-key-sentinel") + http_client_mock.stub_request( + "get", + path="/v1/customers/resource", + rbody='{"id": "resource", "object": "customer"}', + ) + + await restored_customer.refresh_async() + + http_client_mock.assert_requested( + "get", + path="/v1/customers/resource", + api_key="worker-key-sentinel", + stripe_account="example-account", + ) + + def test_refresh_preserves_retrieve_params(self, http_client_mock): + obj = stripe.Customer( + "resource", "producer-key-sentinel", expand=["sources"] + ) + http_client_mock.stub_request( + "get", + path="/v1/customers/resource", + query_string="expand[0]=sources", + rbody='{"id": "resource", "object": "customer"}', + ) + + obj.refresh() + + http_client_mock.assert_requested( + "get", + path="/v1/customers/resource", + query_string="expand[0]=sources", + api_key="producer-key-sentinel", + ) + + def test_restored_save_uses_reattached_api_key( + self, http_client_mock, restored_customer + ): + restored_customer.reattach_api_key("worker-key-sentinel") + restored_customer.description = "changed" + http_client_mock.stub_request( + "post", + path="/v1/customers/resource", + rbody='{"id": "resource", "object": "customer", "description": "changed"}', + ) + + restored_customer.save() + + http_client_mock.assert_requested( + "post", + path="/v1/customers/resource", + api_key="worker-key-sentinel", + stripe_account="example-account", + ) + + def test_save_keeps_positional_idempotency_key( + self, http_client_mock, restored_customer + ): + restored_customer.reattach_api_key("worker-key-sentinel") + restored_customer.description = "changed" + http_client_mock.stub_request( + "post", + path="/v1/customers/resource", + rbody='{"id": "resource", "object": "customer", "description": "changed"}', + ) + + restored_customer.save("idempotency-sentinel") + + http_client_mock.assert_requested( + "post", + path="/v1/customers/resource", + api_key="worker-key-sentinel", + idempotency_key="idempotency-sentinel", + ) + + def test_restored_delete_uses_reattached_api_key( + self, http_client_mock, restored_customer + ): + restored_customer.reattach_api_key("worker-key-sentinel") + http_client_mock.stub_request( + "delete", + path="/v1/customers/resource", + rbody='{"id": "resource", "object": "customer", "deleted": true}', + ) + + restored_customer.delete(api_key="worker-key-sentinel") + + http_client_mock.assert_requested( + "delete", + path="/v1/customers/resource", + api_key="worker-key-sentinel", + stripe_account="example-account", + ) def test_deletion(self): obj = StripeObject("id", "key") diff --git a/tests/test_v2_event.py b/tests/test_v2_event.py index 7f59ca3d5..7353821ff 100644 --- a/tests/test_v2_event.py +++ b/tests/test_v2_event.py @@ -1,4 +1,6 @@ import json +import pickle +import stripe from typing import Any, Callable, Dict, Optional, Union from typing_extensions import assert_type @@ -38,6 +40,32 @@ class TestV2Event(object): + def test_pickled_event_requires_reattachment( + self, http_client_mock, v2_payload_no_data + ): + event = V1BillingMeterErrorReportTriggeredEvent.construct_from( + json.loads(v2_payload_no_data), "producer-key-sentinel" + ) + restored = pickle.loads(pickle.dumps(event)) + with pytest.raises( + stripe.AuthenticationError, match="reattach_api_key" + ): + restored.fetch_related_object() + http_client_mock.assert_no_request() + restored.reattach_api_key("worker-key-sentinel") + http_client_mock.stub_request( + "get", + path="/v1/billing/meters/mtr_123", + rbody='{"id": "mtr_123", "object": "billing.meter"}', + ) + restored.fetch_related_object() + http_client_mock.assert_requested( + "get", + path="/v1/billing/meters/mtr_123", + api_key="worker-key-sentinel", + stripe_context="acct_123", + ) + @pytest.fixture(scope="function") def v2_payload_no_data(self): return json.dumps( From 22e7da79a337b81345b86723416b8b94a28b2359 Mon Sep 17 00:00:00 2001 From: Zachary Chua Date: Wed, 11 Nov 2026 11:53:13 -0800 Subject: [PATCH 2/7] Bump version to 17.0.0 --- ...10-12_orrc_webhook-signature-diagnostics.change.md | 1 + ...2026-10-30_zacchua_omit-pickled-api-keys.change.md | 2 ++ ...fix-event-related-object-account-scoping.change.md | 1 + ...11-06_jar_reject-pycurl-header-injection.change.md | 3 ++- .hark/releases.json | 6 ++++++ CHANGELOG.md | 11 +++++++++++ VERSION | 2 +- pyproject.toml | 2 +- stripe/_version.py | 2 +- 9 files changed, 26 insertions(+), 4 deletions(-) diff --git a/.hark/changes/2026-10-12_orrc_webhook-signature-diagnostics.change.md b/.hark/changes/2026-10-12_orrc_webhook-signature-diagnostics.change.md index af73a3475..7e037e3ca 100644 --- a/.hark/changes/2026-10-12_orrc_webhook-signature-diagnostics.change.md +++ b/.hark/changes/2026-10-12_orrc_webhook-signature-diagnostics.change.md @@ -1,6 +1,7 @@ --- title: Improve webhook signature verification error messages semver_level: patch +released_in_version: 17.0.0 --- - When diagnostic metadata is present in the `Stripe-Signature` header, error messages help identify an incorrect signing secret or altered request body. diff --git a/.hark/changes/2026-10-30_zacchua_omit-pickled-api-keys.change.md b/.hark/changes/2026-10-30_zacchua_omit-pickled-api-keys.change.md index 76dc33045..3642fa3ee 100644 --- a/.hark/changes/2026-10-30_zacchua_omit-pickled-api-keys.change.md +++ b/.hark/changes/2026-10-30_zacchua_omit-pickled-api-keys.change.md @@ -1,7 +1,9 @@ --- title: Omit API keys from pickled StripeObjects semver_level: major +released_in_version: 17.0.0 --- + StripeObject pickles no longer preserve API keys. Before making requests through an unpickled object, call `reattach_api_key(api_key)`. This also reattaches API keys to nested objects. See the [v17 migration guide](https://github.com/stripe/stripe-python/blob/master/.hark/migration-guides/v17.md#api-keys-are-no-longer-preserved-in-pickled-stripeobjects) for details. diff --git a/.hark/changes/2026-11-06_jar_fix-event-related-object-account-scoping.change.md b/.hark/changes/2026-11-06_jar_fix-event-related-object-account-scoping.change.md index 027e2fb54..a42be97cd 100644 --- a/.hark/changes/2026-11-06_jar_fix-event-related-object-account-scoping.change.md +++ b/.hark/changes/2026-11-06_jar_fix-event-related-object-account-scoping.change.md @@ -3,4 +3,5 @@ title: Fix stale Stripe-Account header when fetching an object related to a dire semver_level: patch jira_tickets_closed: - RUN_DEVSDK-3694 +released_in_version: 17.0.0 --- diff --git a/.hark/changes/2026-11-06_jar_reject-pycurl-header-injection.change.md b/.hark/changes/2026-11-06_jar_reject-pycurl-header-injection.change.md index 401ef8606..5a9f7a446 100644 --- a/.hark/changes/2026-11-06_jar_reject-pycurl-header-injection.change.md +++ b/.hark/changes/2026-11-06_jar_reject-pycurl-header-injection.change.md @@ -1,6 +1,7 @@ --- -title: "Reject header values containing CR, LF or NUL in the pycurl HTTP client" +title: Reject header values containing CR, LF or NUL in the pycurl HTTP client semver_level: patch jira_tickets_closed: - RUN_DEVSDK-3683 +released_in_version: 17.0.0 --- diff --git a/.hark/releases.json b/.hark/releases.json index 4f4653e70..9a4449ef1 100644 --- a/.hark/releases.json +++ b/.hark/releases.json @@ -4,6 +4,12 @@ "channel": "ga" }, "releases": [ + { + "version": "17.0.0", + "released_on": "2026-11-11", + "pinned_api_version": "2026-10-28.endive", + "minimum_runtime_version": "3.9" + }, { "version": "16.1.0", "released_on": "2026-10-29", diff --git a/CHANGELOG.md b/CHANGELOG.md index ba20189c7..168094b29 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,17 @@ Instead, edit a corresponding `.change.md` file and run `hark build`. # Changelog +## 17.0.0 - 2026-11-11 +* Improve webhook signature verification error messages + - When diagnostic metadata is present in the `Stripe-Signature` header, error messages help identify an incorrect signing secret or altered request body. +* ⚠️ Omit API keys from pickled StripeObjects + + StripeObject pickles no longer preserve API keys. Before making requests through an unpickled object, call `reattach_api_key(api_key)`. This also reattaches API keys to nested objects. + + See the [v17 migration guide](https://github.com/stripe/stripe-python/blob/master/.hark/migration-guides/v17.md#api-keys-are-no-longer-preserved-in-pickled-stripeobjects) for details. +* Fix stale Stripe-Account header when fetching an object related to a directly-retrieved Event +* Reject header values containing CR, LF or NUL in the pycurl HTTP client + ## 16.1.0 - 2026-10-29 This release changes the pinned API version to `2026-10-28.endive`. diff --git a/VERSION b/VERSION index e0228cf18..aac58983e 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -16.1.0 +17.0.0 diff --git a/pyproject.toml b/pyproject.toml index 638bb9092..60e87b3a8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "stripe" -version = "16.1.0" +version = "17.0.0" readme = "README.md" description = "Python bindings for the Stripe API" authors = [{ name = "Stripe", email = "support@stripe.com" }] diff --git a/stripe/_version.py b/stripe/_version.py index ca9fc3dc4..cf692abbb 100644 --- a/stripe/_version.py +++ b/stripe/_version.py @@ -1 +1 @@ -VERSION = "16.1.0" +VERSION = "17.0.0" From 38d853bcca96a22796a496705455ea18e2558a2e Mon Sep 17 00:00:00 2001 From: zacchua-stripe Date: Wed, 11 Nov 2026 12:15:03 -0800 Subject: [PATCH 3/7] Use a separate Curl handle per thread in PycurlClient (#1972) PycurlClient created one pycurl.Curl handle in its constructor and reconfigured it for every request with no synchronization. When one client was shared across threads, concurrent requests could overwrite each other's URL, body, and headers, sending one request with another request's API key and Stripe-Account. Each thread now lazily creates its own handle in the client's existing thread-local storage, so connections are still reused within a thread. close() closes the current thread's handle. Closes RUN_DEVSDK-3704 Committed-By-Agent: claude Co-authored-by: Claude Opus 5.5 --- ...cchua_pycurl-thread-local-handle.change.md | 6 + stripe/_http_client.py | 60 +++++---- tests/test_http_client.py | 114 ++++++++++++++++++ 3 files changed, 158 insertions(+), 22 deletions(-) create mode 100644 .hark/changes/2026-11-10_zacchua_pycurl-thread-local-handle.change.md diff --git a/.hark/changes/2026-11-10_zacchua_pycurl-thread-local-handle.change.md b/.hark/changes/2026-11-10_zacchua_pycurl-thread-local-handle.change.md new file mode 100644 index 000000000..f28c8faf3 --- /dev/null +++ b/.hark/changes/2026-11-10_zacchua_pycurl-thread-local-handle.change.md @@ -0,0 +1,6 @@ +--- +title: "Use a separate Curl handle per thread in PycurlClient so concurrent requests can't overwrite each other's URL, body, or headers" +semver_level: patch +jira_tickets_closed: +- RUN_DEVSDK-3704 +--- diff --git a/stripe/_http_client.py b/stripe/_http_client.py index 6f0815e91..51740e156 100644 --- a/stripe/_http_client.py +++ b/stripe/_http_client.py @@ -871,8 +871,6 @@ def __init__( _lib = pycurl self.pycurl = _lib - # Initialize this within the object so that we can reuse connections. - self._curl = _lib.Curl() self._parsed_proxy = {} # need to urlparse the proxy, since PyCurl @@ -886,6 +884,20 @@ def __init__( # but we know value to be a string because all the value types on Proxy_ are strings. self._parsed_proxy[scheme] = urlparse(cast(str, value)) + def _get_curl(self): + """ + Returns this thread's Curl handle, creating it on first use. + + A libcurl easy handle must never be used by more than one thread at a + time, so each thread gets its own. Reusing a handle within a thread + lets us keep its established connections. + """ + curl = getattr(self._thread_local, "curl", None) + if curl is None: + curl = self.pycurl.Curl() + self._thread_local.curl = curl + return curl + def parse_headers(self, data): if "\r\n" not in data: return {} @@ -944,48 +956,49 @@ def _request_internal( # pristine state, but notably reset() doesn't reset connections, so we # still get to take advantage of those by virtue of re-using the same # object. - self._curl.reset() + curl = self._get_curl() + curl.reset() proxy = self._get_proxy(url) if proxy: if proxy.hostname: - self._curl.setopt(self.pycurl.PROXY, proxy.hostname) + curl.setopt(self.pycurl.PROXY, proxy.hostname) if proxy.port: - self._curl.setopt(self.pycurl.PROXYPORT, proxy.port) + curl.setopt(self.pycurl.PROXYPORT, proxy.port) if proxy.username or proxy.password: - self._curl.setopt( + curl.setopt( self.pycurl.PROXYUSERPWD, "%s:%s" % (proxy.username, proxy.password), ) if method == "get": - self._curl.setopt(self.pycurl.HTTPGET, 1) + curl.setopt(self.pycurl.HTTPGET, 1) elif method == "post": - self._curl.setopt(self.pycurl.POST, 1) - self._curl.setopt(self.pycurl.POSTFIELDS, post_data) + curl.setopt(self.pycurl.POST, 1) + curl.setopt(self.pycurl.POSTFIELDS, post_data) else: - self._curl.setopt(self.pycurl.CUSTOMREQUEST, method.upper()) + curl.setopt(self.pycurl.CUSTOMREQUEST, method.upper()) # pycurl doesn't like unicode URLs - self._curl.setopt(self.pycurl.URL, url) + curl.setopt(self.pycurl.URL, url) - self._curl.setopt(self.pycurl.WRITEFUNCTION, b.write) - self._curl.setopt(self.pycurl.HEADERFUNCTION, rheaders.write) - self._curl.setopt(self.pycurl.NOSIGNAL, 1) - self._curl.setopt(self.pycurl.CONNECTTIMEOUT, 30) - self._curl.setopt(self.pycurl.TIMEOUT, 80) + curl.setopt(self.pycurl.WRITEFUNCTION, b.write) + curl.setopt(self.pycurl.HEADERFUNCTION, rheaders.write) + curl.setopt(self.pycurl.NOSIGNAL, 1) + curl.setopt(self.pycurl.CONNECTTIMEOUT, 30) + curl.setopt(self.pycurl.TIMEOUT, 80) _assert_no_header_injection(headers) - self._curl.setopt( + curl.setopt( self.pycurl.HTTPHEADER, ["%s: %s" % (k, v) for k, v in dict(headers).items()], ) if self._verify_ssl_certs: - self._curl.setopt(self.pycurl.CAINFO, stripe.ca_bundle_path) + curl.setopt(self.pycurl.CAINFO, stripe.ca_bundle_path) else: - self._curl.setopt(self.pycurl.SSL_VERIFYHOST, False) + curl.setopt(self.pycurl.SSL_VERIFYHOST, False) try: - self._curl.perform() + curl.perform() except self.pycurl.error as e: self._handle_request_error(e) @@ -995,7 +1008,7 @@ def _request_internal( else: rcontent = b.getvalue().decode("utf-8") - rcode = self._curl.getinfo(self.pycurl.RESPONSE_CODE) + rcode = curl.getinfo(self.pycurl.RESPONSE_CODE) headers = self.parse_headers(rheaders.getvalue().decode("utf-8")) return rcontent, rcode, headers @@ -1044,7 +1057,10 @@ def _get_proxy(self, url) -> Optional["ParseResult"]: return None def close(self): - pass + curl = getattr(self._thread_local, "curl", None) + if curl is not None: + curl.close() + self._thread_local.curl = None class UrllibClient(HTTPClient): diff --git a/tests/test_http_client.py b/tests/test_http_client.py index 0c6eaa557..937eec3fa 100644 --- a/tests/test_http_client.py +++ b/tests/test_http_client.py @@ -2,6 +2,7 @@ import base64 import json import sys +import threading from typing import Any, Callable, Dict, List, Optional from unittest.mock import MagicMock, Mock, call, patch @@ -1166,6 +1167,119 @@ def test_request_rejects_header_injection( with pytest.raises(ValueError): make_request("get", self.valid_url, headers, None) + @pytest.fixture + def created_curls(self, mocked_request_lib): + curls: List[Mock] = [] + + def make_curl(): + curl = Mock() + curl.getinfo.return_value = 200 + curls.append(curl) + return curl + + mocked_request_lib.Curl = Mock(side_effect=make_curl) + return curls + + @staticmethod + def setopt_values(curl, option): + return [ + c.args[1] + for c in curl.setopt.call_args_list + if c.args[0] == option + ] + + def test_uses_one_curl_handle_per_thread( + self, mocked_request_lib, created_curls + ): + client = self.REQUEST_CLIENT(proxy=self.PROXY, _lib=mocked_request_lib) + + client.request("get", self.valid_url, {}) + client.request("get", self.valid_url, {}) + assert len(created_curls) == 1 + + errors: List[BaseException] = [] + + def request_in_thread(): + try: + client.request("get", self.valid_url, {}) + except BaseException as e: + errors.append(e) + + thread = threading.Thread(target=request_in_thread) + thread.start() + thread.join(timeout=5) + + assert errors == [] + assert len(created_curls) == 2 + assert created_curls[0] is not created_curls[1] + + def test_concurrent_requests_do_not_share_curl_state( + self, mocked_request_lib + ): + client = self.REQUEST_CLIENT(proxy=self.PROXY, _lib=mocked_request_lib) + url_a = "https://api.stripe.com/v1/payouts" + url_b = "https://api.stripe.com/v1/transfers" + a_performing = threading.Event() + release_a = threading.Event() + errors: List[BaseException] = [] + + # Hold request A inside perform() until request B has fully run. If the + # threads shared a handle, B's settings would replace A's mid-request. + def block_first_perform(): + if not a_performing.is_set(): + a_performing.set() + assert release_a.wait(timeout=5) + + def request_a(): + try: + client.request( + "post", url_a, {"Authorization": "Bearer sk_test_A"}, "a=1" + ) + except BaseException as e: + errors.append(e) + + curl_a = Mock() + curl_a.getinfo.return_value = 200 + curl_a.perform.side_effect = block_first_perform + curl_b = Mock() + curl_b.getinfo.return_value = 200 + mocked_request_lib.Curl = Mock(side_effect=[curl_a, curl_b]) + + thread_a = threading.Thread(target=request_a) + thread_a.start() + assert a_performing.wait(timeout=5) + + client.request( + "post", url_b, {"Authorization": "Bearer sk_test_B"}, "b=2" + ) + release_a.set() + thread_a.join(timeout=5) + + assert errors == [] + lib = mocked_request_lib + assert self.setopt_values(curl_a, lib.URL) == [url_a] + assert self.setopt_values(curl_a, lib.POSTFIELDS) == ["a=1"] + assert self.setopt_values(curl_a, lib.HTTPHEADER) == [ + ["Authorization: Bearer sk_test_A"] + ] + assert self.setopt_values(curl_b, lib.URL) == [url_b] + assert self.setopt_values(curl_b, lib.POSTFIELDS) == ["b=2"] + assert self.setopt_values(curl_b, lib.HTTPHEADER) == [ + ["Authorization: Bearer sk_test_B"] + ] + + def test_close_closes_this_threads_curl_handle( + self, mocked_request_lib, created_curls + ): + client = self.REQUEST_CLIENT(proxy=self.PROXY, _lib=mocked_request_lib) + client.request("get", self.valid_url, {}) + + client.close() + + created_curls[0].close.assert_called_once_with() + client.request("get", self.valid_url, {}) + assert len(created_curls) == 2 + class TestPycurlClientHttpProxy(TestPycurlClient): PROXY = "http://user:withPwd@slap:8888/" From 22976b08f7f8f53f96993b82fe629c54db83c862 Mon Sep 17 00:00:00 2001 From: zacchua-stripe Date: Thu, 12 Nov 2026 10:12:33 -0800 Subject: [PATCH 4/7] Link v17 migration guide to the wiki (#1977) Point the major changefile's migration guide link at the published wiki page and rebuild CHANGELOG.md. The previous link pointed at a branch or repo path that can move or be deleted. Committed-By-Agent: claude Co-authored-by: Claude Opus 5.5 --- .../changes/2026-10-30_zacchua_omit-pickled-api-keys.change.md | 2 +- CHANGELOG.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.hark/changes/2026-10-30_zacchua_omit-pickled-api-keys.change.md b/.hark/changes/2026-10-30_zacchua_omit-pickled-api-keys.change.md index 3642fa3ee..bc7173ee9 100644 --- a/.hark/changes/2026-10-30_zacchua_omit-pickled-api-keys.change.md +++ b/.hark/changes/2026-10-30_zacchua_omit-pickled-api-keys.change.md @@ -6,4 +6,4 @@ released_in_version: 17.0.0 StripeObject pickles no longer preserve API keys. Before making requests through an unpickled object, call `reattach_api_key(api_key)`. This also reattaches API keys to nested objects. -See the [v17 migration guide](https://github.com/stripe/stripe-python/blob/master/.hark/migration-guides/v17.md#api-keys-are-no-longer-preserved-in-pickled-stripeobjects) for details. +See the [v17 migration guide](https://github.com/stripe/stripe-python/wiki/Migration-guide-for-v17#api-keys-are-no-longer-preserved-in-pickled-stripeobjects) for details. diff --git a/CHANGELOG.md b/CHANGELOG.md index 168094b29..2f1f0bb35 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,7 +12,7 @@ Instead, edit a corresponding `.change.md` file and run `hark build`. StripeObject pickles no longer preserve API keys. Before making requests through an unpickled object, call `reattach_api_key(api_key)`. This also reattaches API keys to nested objects. - See the [v17 migration guide](https://github.com/stripe/stripe-python/blob/master/.hark/migration-guides/v17.md#api-keys-are-no-longer-preserved-in-pickled-stripeobjects) for details. + See the [v17 migration guide](https://github.com/stripe/stripe-python/wiki/Migration-guide-for-v17#api-keys-are-no-longer-preserved-in-pickled-stripeobjects) for details. * Fix stale Stripe-Account header when fetching an object related to a directly-retrieved Event * Reject header values containing CR, LF or NUL in the pycurl HTTP client From 7254286570dcacb689f933db913e7cdf303818db Mon Sep 17 00:00:00 2001 From: itsrayeedscodespace Date: Fri, 13 Nov 2026 11:42:09 -0500 Subject: [PATCH 5/7] Allow configurable timeouts for PycurlClient (#1975) * fix: make PycurlClient timeouts configurable PycurlClient hardcoded CONNECTTIMEOUT=30 and TIMEOUT=80 on every request, unlike RequestsClient, HTTPXClient and AIOHTTPClient, which accept a `timeout` constructor argument. Add keyword-only `timeout` and `connect_timeout` arguments (defaults 80 and 30) after the existing parameters so positional callers are unaffected. Fixes #1962 * Remove unnecessary PycurlClient constructor docstring --- ...ace_pycurl-configurable-timeouts.change.md | 8 ++ stripe/_http_client.py | 9 +- tests/test_http_client.py | 101 ++++++++++++++++++ 3 files changed, 116 insertions(+), 2 deletions(-) create mode 100644 .hark/changes/2026-11-06_itsrayeedscodespace_pycurl-configurable-timeouts.change.md diff --git a/.hark/changes/2026-11-06_itsrayeedscodespace_pycurl-configurable-timeouts.change.md b/.hark/changes/2026-11-06_itsrayeedscodespace_pycurl-configurable-timeouts.change.md new file mode 100644 index 000000000..0e93637c7 --- /dev/null +++ b/.hark/changes/2026-11-06_itsrayeedscodespace_pycurl-configurable-timeouts.change.md @@ -0,0 +1,8 @@ +--- +title: Add configurable `timeout` and `connect_timeout` to `PycurlClient` +semver_level: minor +github_issues_resolved: +- https://github.com/stripe/stripe-python/issues/1962 +--- + +`PycurlClient` now accepts keyword-only `timeout` (total request time, curl's `TIMEOUT`) and `connect_timeout` (curl's `CONNECTTIMEOUT`) arguments, in whole seconds. They default to the previous hardcoded values of 80 and 30 seconds. diff --git a/stripe/_http_client.py b/stripe/_http_client.py index 51740e156..f11f6c600 100644 --- a/stripe/_http_client.py +++ b/stripe/_http_client.py @@ -858,12 +858,17 @@ def __init__( proxy: Optional[HTTPClient._Proxy] = None, async_fallback_client: Optional[HTTPClient] = None, _lib=None, # used for internal unit testing + *, + timeout: int = 80, + connect_timeout: int = 30, ): super(PycurlClient, self).__init__( verify_ssl_certs=verify_ssl_certs, proxy=proxy, async_fallback_client=async_fallback_client, ) + self._timeout = timeout + self._connect_timeout = connect_timeout if _lib is None: import pycurl # pyright: ignore[reportMissingModuleSource] @@ -985,8 +990,8 @@ def _request_internal( curl.setopt(self.pycurl.WRITEFUNCTION, b.write) curl.setopt(self.pycurl.HEADERFUNCTION, rheaders.write) curl.setopt(self.pycurl.NOSIGNAL, 1) - curl.setopt(self.pycurl.CONNECTTIMEOUT, 30) - curl.setopt(self.pycurl.TIMEOUT, 80) + curl.setopt(self.pycurl.CONNECTTIMEOUT, self._connect_timeout) + curl.setopt(self.pycurl.TIMEOUT, self._timeout) _assert_no_header_injection(headers) curl.setopt( self.pycurl.HTTPHEADER, diff --git a/tests/test_http_client.py b/tests/test_http_client.py index 937eec3fa..153704ed8 100644 --- a/tests/test_http_client.py +++ b/tests/test_http_client.py @@ -1167,6 +1167,107 @@ def test_request_rejects_header_injection( with pytest.raises(ValueError): make_request("get", self.valid_url, headers, None) + @pytest.mark.parametrize( + "client_kwargs,expected_connect_timeout,expected_timeout", + [ + ({}, 30, 80), + ({"connect_timeout": 5, "timeout": 10}, 5, 10), + ({"connect_timeout": 5}, 5, 80), + ({"timeout": 10}, 30, 10), + ], + ) + def test_timeout( + self, + mocked_request_lib, + mock_response, + make_request, + client_kwargs, + expected_connect_timeout, + expected_timeout, + ): + mock_response(mocked_request_lib, '{"foo": "baz"}', 200) + make_request( + "GET", self.valid_url, {}, None, client_kwargs=client_kwargs + ) + + curl_mock = mocked_request_lib.Curl() + curl_mock.setopt.assert_any_call( + mocked_request_lib.CONNECTTIMEOUT, expected_connect_timeout + ) + curl_mock.setopt.assert_any_call( + mocked_request_lib.TIMEOUT, expected_timeout + ) + + def test_timeout_stream( + self, mocked_request_lib, mock_response, make_streamed_request + ): + mock_response(mocked_request_lib, "some streamed content", 200) + make_streamed_request( + "GET", + self.valid_url, + {}, + None, + client_kwargs={"connect_timeout": 5, "timeout": 10}, + ) + + curl_mock = mocked_request_lib.Curl() + curl_mock.setopt.assert_any_call(mocked_request_lib.CONNECTTIMEOUT, 5) + curl_mock.setopt.assert_any_call(mocked_request_lib.TIMEOUT, 10) + + def test_timeout_reapplied_after_reset( + self, mocked_request_lib, mock_response, make_client + ): + mock_response(mocked_request_lib, '{"foo": "baz"}', 200) + client = make_client(connect_timeout=5, timeout=10) + + client.request("get", self.valid_url, {}) + client.request("get", self.valid_url, {}) + + curl_mock = mocked_request_lib.Curl() + # reset() clears every option, so each request must set the + # timeouts again after its own reset() call. + relevant_calls = [ + c + for c in curl_mock.mock_calls + if c == call.reset() + or ( + c[0] == "setopt" + and c[1][0] + in ( + mocked_request_lib.CONNECTTIMEOUT, + mocked_request_lib.TIMEOUT, + ) + ) + ] + assert ( + relevant_calls + == [ + call.reset(), + call.setopt(mocked_request_lib.CONNECTTIMEOUT, 5), + call.setopt(mocked_request_lib.TIMEOUT, 10), + ] + * 2 + ) + + def test_positional_args(self, mocked_request_lib): + client = self.REQUEST_CLIENT(False, None, None, mocked_request_lib) + + assert client.pycurl is mocked_request_lib + assert client._verify_ssl_certs is False + assert client._connect_timeout == 30 + assert client._timeout == 80 + + # Timeouts are keyword-only so they can't be confused with each + # other or with the existing positional parameters. + with pytest.raises(TypeError): + self.REQUEST_CLIENT( + False, + None, + None, + mocked_request_lib, + 10, # pyright: ignore[reportGeneralTypeIssues] + ) + @pytest.fixture def created_curls(self, mocked_request_lib): curls: List[Mock] = [] From 11ff99cbecb2eba530f23eee2fac65bd52144eb5 Mon Sep 17 00:00:00 2001 From: mark-kogan-stripe Date: Mon, 16 Nov 2026 06:26:17 -0800 Subject: [PATCH 6/7] Clean up supported python versions (#1992) --- deps/test-requirements.txt | 12 +++--------- pyproject.toml | 4 ++-- tests/test_http_client.py | 6 +----- 3 files changed, 6 insertions(+), 16 deletions(-) diff --git a/deps/test-requirements.txt b/deps/test-requirements.txt index e8ab486b2..a09422ca6 100644 --- a/deps/test-requirements.txt +++ b/deps/test-requirements.txt @@ -1,17 +1,11 @@ # packages needed to run unit tests (including extra supported http libraries) -# version requirements: all supported versions (currently 3.6-3.12) +# version requirements: all supported versions (currently 3.9-3.14) -# This is the last version of httpx compatible with Python 3.6 -httpx == 0.22.0; python_version == "3.6" -httpx >= 0.24.1; python_version == "3.7" -httpx >= 0.27.0; python_version >= "3.8" -aiohttp == 3.8.6; python_version <= "3.7" -aiohttp == 3.10.11; python_version == "3.8" -aiohttp == 3.12.15; python_version >= "3.9" +httpx >= 0.27.0 +aiohttp == 3.12.15 anyio[trio] == 3.6.2; python_version < "3.13" anyio[trio] == 4.11.0; python_version >= "3.13" pytest-mock >= 2.0.0 -mock >= 4.0; python_version < "3.8" pytest-xdist >= 1.31.0 pytest >= 6.0.0,<9.0.0 diff --git a/pyproject.toml b/pyproject.toml index 60e87b3a8..1123ce641 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -15,12 +15,12 @@ classifiers = [ "Programming Language :: Python", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only", - "Programming Language :: Python :: 3.7", - "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", + "Programming Language :: Python :: 3.14", "Programming Language :: Python :: Implementation :: CPython", "Programming Language :: Python :: Implementation :: PyPy", "Topic :: Software Development :: Libraries :: Python Modules", diff --git a/tests/test_http_client.py b/tests/test_http_client.py index 153704ed8..016bfa176 100644 --- a/tests/test_http_client.py +++ b/tests/test_http_client.py @@ -1,7 +1,6 @@ import io import base64 import json -import sys import threading from typing import Any, Callable, Dict, List, Optional from unittest.mock import MagicMock, Mock, call, patch @@ -9,10 +8,7 @@ import pytest from typing_extensions import Type -if sys.version_info >= (3, 8): - from unittest.mock import AsyncMock -else: - from mock import AsyncMock +from unittest.mock import AsyncMock from contextlib import contextmanager From a970e4aa5d816e6a9618157d46e87e9bbd2c4896 Mon Sep 17 00:00:00 2001 From: mark-kogan-stripe Date: Tue, 17 Nov 2026 11:32:45 -0800 Subject: [PATCH 7/7] Add support for using httpx2 for async requests (#1997) * Replace httpx with httpx2 for async requests httpx, which backs HTTPXClient and the default async client, is no longer maintained, so it won't receive security fixes. httpx2 is its community-accepted continuation, maintained by Pydantic, and keeps mostly the same API. Two calls needed adjusting for httpx2: - The encoded body is sent as `content=`, since passing raw bodies as `data=` is deprecated and emits a warning on every request. - Proxies are configured through client-level `mounts`, since the per-request `proxies=` argument isn't accepted. Closes #1886 * Restore support for httpx, preferring httpx2 when both are installed in an environment * Add short integration test asserting that the request passes successfully through httpx and httpx2 * Make it clearer that httpx is not a blessed path * Convert timeout to in-use httpx/httpx2 library on the fly to avoid breaking * Add note relating to httpx deprecation --- .claude/CLAUDE.md | 2 +- ...16_markisaackogan_httpx2-support.change.md | 8 ++ ...an_use-standard-params-on-httpx2.change.md | 6 + README.md | 11 +- deps/test-requirements.txt | 7 +- stripe/_http_client.py | 130 ++++++++++++++---- tests/test_http_client.py | 84 +++++++++-- tests/test_integration.py | 48 ++++++- 8 files changed, 252 insertions(+), 44 deletions(-) create mode 100644 .hark/changes/2026-11-16_markisaackogan_httpx2-support.change.md create mode 100644 .hark/changes/2026-11-17_markisaackogan_use-standard-params-on-httpx2.change.md diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index b65b38505..b9e11f38e 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -28,7 +28,7 @@ ## Conventions -- Uses `requests` library by default for sync HTTP, `httpx` for async +- Uses `requests` library by default for sync HTTP, `httpx2` (falling back to `httpx`) for async - Type hints throughout - Virtual env managed in `.venv/`; `just` recipes handle setup automatically - Work is not complete until `just test`, `just lint` and `just typecheck` complete successfully. diff --git a/.hark/changes/2026-11-16_markisaackogan_httpx2-support.change.md b/.hark/changes/2026-11-16_markisaackogan_httpx2-support.change.md new file mode 100644 index 000000000..ae0d72ac6 --- /dev/null +++ b/.hark/changes/2026-11-16_markisaackogan_httpx2-support.change.md @@ -0,0 +1,8 @@ +--- +title: "Support httpx2 for async requests, falling back to httpx when httpx2 isn't installed" +semver_level: minor +pr_url: https://github.com/stripe/stripe-python/pull/1997 +github_issues_resolved: +- https://github.com/stripe/stripe-python/issues/1886 +--- +`HTTPXClient` and the default async client now use `httpx2` when it's installed and fall back to `httpx` otherwise. `httpx` support is deprecated and will be removed in the next major version; we recommend installing `httpx2` for async use. diff --git a/.hark/changes/2026-11-17_markisaackogan_use-standard-params-on-httpx2.change.md b/.hark/changes/2026-11-17_markisaackogan_use-standard-params-on-httpx2.change.md new file mode 100644 index 000000000..89852fa3b --- /dev/null +++ b/.hark/changes/2026-11-17_markisaackogan_use-standard-params-on-httpx2.change.md @@ -0,0 +1,6 @@ +--- +title: "Fix `HTTPXClient` raising a network error when a proxy is configured" +semver_level: patch +pr_url: https://github.com/stripe/stripe-python/pull/1997 +--- +`HTTPXClient` passed `proxies` on each request, which httpx doesn't accept. Proxies are now configured on the client instead. Request bodies are also now sent as `content=`, which avoids httpx's deprecation warning for `data=`. diff --git a/README.md b/README.md index c40ed3e96..6dd63449e 100644 --- a/README.md +++ b/README.md @@ -370,9 +370,12 @@ async for c in await stripe.Customer.list_async().auto_paging_iter(): There is no `.save_async` as `.save` is [deprecated since stripe-python v5](https://github.com/stripe/stripe-python/wiki/Migration-guide-for-v5#deprecated). Please migrate to `.modify_async`. The default HTTP client uses `requests` for making synchronous requests but -`httpx` for making async requests. If you're migrating to async, we recommend -you to explicitly initialize your own http client and pass it to StripeClient -or set it as the global default. +`httpx2` for making async requests, falling back to `httpx` if `httpx2` isn't +installed (and to `aiohttp` if neither is). We recommend `pip install httpx2` +for async use, since `httpx` is no longer actively maintained. `httpx` support +is deprecated and will be removed in the next major version of stripe-python. +If you're migrating to async, we recommend you to explicitly initialize your own +http client and pass it to StripeClient or set it as the global default. If you don't already have a dependency on an async-compatible HTTP library, `pip install stripe[async]` will install one for you (new in `v13.0.1`). @@ -382,7 +385,7 @@ If you don't already have a dependency on an async-compatible HTTP library, `pip # make sure you don't unintentionally make a synchronous request. my_http_client = stripe.HTTPXClient() -# If you want to use httpx to make sync requests, you can disable this +# If you want to use httpx2 to make sync requests, you can disable this # behavior. my_http_client = stripe.HTTPXClient(allow_sync_methods=True) diff --git a/deps/test-requirements.txt b/deps/test-requirements.txt index a09422ca6..24fffcb55 100644 --- a/deps/test-requirements.txt +++ b/deps/test-requirements.txt @@ -1,10 +1,13 @@ # packages needed to run unit tests (including extra supported http libraries) # version requirements: all supported versions (currently 3.9-3.14) +httpx2 >= 2.0.0 +# fallback when httpx2 isn't installed +# TODO: (DEVSDK-3427) remove httpx in the next major version httpx >= 0.27.0 aiohttp == 3.12.15 -anyio[trio] == 3.6.2; python_version < "3.13" -anyio[trio] == 4.11.0; python_version >= "3.13" +# httpx2 requires anyio >= 4.10 since 2.9.0 +anyio[trio] == 4.10.0 pytest-mock >= 2.0.0 pytest-xdist >= 1.31.0 diff --git a/stripe/_http_client.py b/stripe/_http_client.py index f11f6c600..75f8d35bd 100644 --- a/stripe/_http_client.py +++ b/stripe/_http_client.py @@ -48,8 +48,10 @@ pass try: - from httpx import Timeout as HTTPXTimeout - from httpx import Client as HTTPXClientType + from httpx2 import Timeout as HTTPXTimeout + from httpx2 import Client as HTTPXClientType + from httpx2 import AsyncBaseTransport as HTTPXAsyncTransport + from httpx2 import BaseTransport as HTTPXSyncTransport except ImportError: pass @@ -1193,6 +1195,67 @@ def close(self): pass +def _get_httpx_async_mounts( + httpx: Any, + proxy: Optional[HTTPClient._Proxy], + verify: Union[ssl.SSLContext, bool], +) -> Optional[Dict[str, "HTTPXAsyncTransport"]]: + """ + Returns the `mounts` option that routes an `httpx.AsyncClient` (or the + `httpx2` equivalent) through `proxy`, or `None` when there's no proxy. + + httpx only accepts proxies at the client level, and needs a transport + mounted per URL scheme to use a different proxy for each one. + """ + if not proxy: + return None + + return { + f"{scheme}://": httpx.AsyncHTTPTransport( + proxy=proxy_url, verify=verify + ) + for scheme, proxy_url in proxy.items() + if proxy_url + } + + +def _get_httpx_sync_mounts( + httpx: Any, + proxy: Optional[HTTPClient._Proxy], + verify: Union[ssl.SSLContext, bool], +) -> Optional[Dict[str, "HTTPXSyncTransport"]]: + """ + The sync `Client` counterpart of `_get_httpx_async_mounts`, since sync + and async clients can't share transports. + """ + if not proxy: + return None + + return { + f"{scheme}://": httpx.HTTPTransport(proxy=proxy_url, verify=verify) + for scheme, proxy_url in proxy.items() + if proxy_url + } + + +# TODO: (DEVSDK-3427) No longer necessary in the next major version. +def _coerce_httpx_timeout(httpx_lib: Any, timeout: Any) -> Any: + """ + `httpx` and `httpx2` each define their own `Timeout` class and neither + recognizes the other's, so a `Timeout` from the library that isn't in use + is rebuilt as one from the library that is. + """ + if timeout is None or isinstance(timeout, (int, float, httpx_lib.Timeout)): + return timeout + + return httpx_lib.Timeout( + connect=timeout.connect, + read=timeout.read, + write=timeout.write, + pool=timeout.pool, + ) + + class HTTPXClient(HTTPClient): name = "httpx" @@ -1208,28 +1271,32 @@ def __init__( super(HTTPXClient, self).__init__(**kwargs) if _lib is None: - import httpx - - _lib = httpx - self.httpx = _lib + # TODO: (DEVSDK-3427) drop the httpx fallback in the next major version. + try: + import httpx2 as _lib + except ImportError: + import httpx as _lib + self.httpx: Any = _lib import anyio self.anyio = anyio - kwargs = {} + verify: Union[ssl.SSLContext, Literal[False]] = False if self._verify_ssl_certs: - kwargs["verify"] = ssl.create_default_context( - cafile=stripe.ca_bundle_path - ) - else: - kwargs["verify"] = False + verify = ssl.create_default_context(cafile=stripe.ca_bundle_path) - self._client_async = self.httpx.AsyncClient(**kwargs) + self._client_async = self.httpx.AsyncClient( + verify=verify, + mounts=_get_httpx_async_mounts(self.httpx, self._proxy, verify), + ) self._client = None if allow_sync_methods: - self._client = self.httpx.Client(**kwargs) - self._timeout = timeout + self._client = self.httpx.Client( + verify=verify, + mounts=_get_httpx_sync_mounts(self.httpx, self._proxy, verify), + ) + self._timeout = _coerce_httpx_timeout(self.httpx, timeout) def sleep_async(self, secs): return self.anyio.sleep(secs) @@ -1239,14 +1306,13 @@ def _get_request_args_kwargs( ): kwargs = {} - if self._proxy: - kwargs["proxies"] = self._proxy - if self._timeout: kwargs["timeout"] = self._timeout + # `post_data` is an already-encoded body, which httpx takes as + # `content`; passing it as `data` is deprecated. return [ (method, url), - {"headers": headers, "data": post_data or {}, **kwargs}, + {"headers": headers, "content": post_data or None, **kwargs}, ] def request( @@ -1498,9 +1564,9 @@ def __init__(self, **kwargs): def raise_async_client_import_error() -> Never: raise ImportError( ( - "Import httpx not found. To make async http requests," - "You must either install httpx or define your own" - "async http client by subclassing stripe.HTTPClient" + "Import httpx2 not found. To make async http requests, " + "you must either install httpx2 or define your own " + "async http client by subclassing stripe.HTTPClient " "and setting stripe.default_http_client to an instance of it." ) ) @@ -1521,7 +1587,7 @@ async def close_async(self): # --- Client resolution --- # Detect available HTTP libraries at module load time so the expensive imports -# (e.g. requests, httpx) happen during Python's init phase rather than when +# (e.g. requests, httpx2) happen during Python's init phase rather than when # StripeClient() is constructed. This matters in environments like AWS Lambda # where module loading has a generous timeout (10s) but handler invocation # does not (often 3s). @@ -1533,9 +1599,14 @@ async def close_async(self): # 4. urllib (stdlib fallback, basically always present) # # Async client precedence: -# 1. httpx + anyio (both required) -# 2. aiohttp -# 3. NoImportFoundAsyncClient (raises on use) +# 1. httpx2 + anyio (both required) +# 2. (deprecated, see note) httpx + anyio (both required) +# 3. aiohttp +# 4. NoImportFoundAsyncClient (raises on use) +# +# Note: httpx is no longer maintained, so we only fall back to it for users who +# haven't installed httpx2 yet. That fallback is deprecated and will be removed +# in the next major version (DEVSDK-3427). # # To add a new client: define the class above, then add it to the appropriate # cascade below. The resolved class is stored directly — new_default_http_client() @@ -1569,9 +1640,14 @@ def _resolve_sync_client(): def _resolve_async_client(): try: - import httpx # noqa: F401 import anyio # noqa: F401 + # TODO: (DEVSDK-3427) drop the httpx fallback in the next major version. + try: + import httpx2 # noqa: F401 + except ImportError: + import httpx # noqa: F401 + return HTTPXClient except ImportError: pass diff --git a/tests/test_http_client.py b/tests/test_http_client.py index 016bfa176..959d72104 100644 --- a/tests/test_http_client.py +++ b/tests/test_http_client.py @@ -1,3 +1,4 @@ +import importlib import io import base64 import json @@ -40,7 +41,15 @@ def mocked_request_lib(): SUPPORTED_LIBS = frozenset( - ("google.appengine.api", "requests", "pycurl", "httpx", "aiohttp", "anyio") + ( + "google.appengine.api", + "requests", + "pycurl", + "httpx2", + "httpx", # TODO: (DEVSDK-3427) drop in the next major version. + "aiohttp", + "anyio", + ) ) @@ -104,10 +113,15 @@ def test_default_httpclient_from_imports( @pytest.mark.parametrize( ["available_libs", "expected"], [ - # needs both httpx and anyio + # TODO: (DEVSDK-3427) delete the httpx-only cases in the next major version. + # needs both httpx2 (or httpx) and anyio + [["httpx2"], NoImportFoundAsyncClient], [["httpx"], NoImportFoundAsyncClient], [["anyio"], NoImportFoundAsyncClient], + [["httpx2", "anyio"], HTTPXClient], [["httpx", "anyio"], HTTPXClient], + [["httpx2", "httpx", "anyio"], HTTPXClient], + [["httpx", "anyio", "aiohttp"], HTTPXClient], # having only one required lib means we proceed [["anyio", "aiohttp"], AIOHTTPClient], [["aiohttp"], AIOHTTPClient], @@ -1420,7 +1434,7 @@ class TestHTTPXClient(ClientTestBase): @pytest.fixture def request_mock(self, mocked_request_lib): - # Set up the httpx library mock structure + # Set up the httpx2 library mock structure async_client_instance = Mock() sync_client_instance = Mock() @@ -1492,9 +1506,8 @@ def _check_call( args = (method, url) kwargs = { "headers": headers, - "data": post_data or {}, + "content": post_data or None, "timeout": timeout, - "proxies": {"http": "http://slap/", "https": "http://slap/"}, } if is_streaming: @@ -1521,9 +1534,8 @@ def _check_call_async( args = (method, url) kwargs = { "headers": headers, - "data": post_data, + "content": post_data or None, "timeout": timeout, - "proxies": {"http": "http://slap/", "https": "http://slap/"}, } if is_streaming: @@ -1828,6 +1840,62 @@ def test_timeout_async(self): pass +class TestHTTPXClientTimeout: + @pytest.fixture(params=["httpx2", "httpx"]) + def lib(self, request): + return importlib.import_module(request.param) + + @pytest.fixture + def other_lib(self, lib): + name = "httpx" if lib.__name__ == "httpx2" else "httpx2" + return importlib.import_module(name) + + @pytest.mark.parametrize("timeout", [None, 5, 2.5, 80]) + def test_numeric_timeout_is_unchanged(self, lib, timeout): + client = HTTPXClient(timeout=timeout, _lib=lib) + + assert client._timeout == timeout + + def test_timeout_from_same_lib_is_unchanged(self, lib): + timeout = lib.Timeout(30.0, connect=5.0) + + client = HTTPXClient(timeout=timeout, _lib=lib) + + assert client._timeout is timeout + + def test_timeout_from_other_lib_is_converted(self, lib, other_lib): + timeout = other_lib.Timeout(30.0, connect=5.0, read=10.0) + + client = HTTPXClient(timeout=timeout, _lib=lib) + + assert isinstance(client._timeout, lib.Timeout) + assert client._timeout == lib.Timeout(30.0, connect=5.0, read=10.0) + + @pytest.mark.anyio + async def test_converted_timeout_is_accepted_by_request( + self, lib, other_lib + ): + seen = {} + + def handler(request): + seen.update(request.extensions["timeout"]) + return lib.Response(200, request=request, content=b"{}") + + client = HTTPXClient( + timeout=other_lib.Timeout(5.0, read=1.0), _lib=lib + ) + client._client_async = lib.AsyncClient( + transport=lib.MockTransport(handler) + ) + + _, status, _ = await client.request_async( + "get", "https://api.stripe.com/", {}, None + ) + + assert status == 200 + assert seen == {"connect": 5.0, "read": 1.0, "write": 5.0, "pool": 5.0} + + class TestAIOHTTPClient(ClientTestBase): REQUEST_CLIENT: Type[_http_client.AIOHTTPClient] = ( _http_client.AIOHTTPClient @@ -2239,7 +2307,7 @@ class TestLiveHTTPClients: @pytest.mark.anyio async def test_httpx_request_async_https(self): """ - Test to ensure that httpx https calls succeed by making a live test call + Test to ensure that httpx2 https calls succeed by making a live test call to the public stripe API. """ method = "get" diff --git a/tests/test_integration.py b/tests/test_integration.py index 9572ff127..05d3b8534 100644 --- a/tests/test_integration.py +++ b/tests/test_integration.py @@ -1,3 +1,4 @@ +import importlib import platform from threading import Thread, Lock import json @@ -5,7 +6,7 @@ import warnings import time -import httpx +import httpx2 import aiohttp import sys import stripe @@ -227,6 +228,49 @@ class MockServerRequestHandler(MyTestHandler): assert MockServerRequestHandler.num_requests == 1 + # TODO: (DEVSDK-3427) drop the httpx param in the next major version. + @pytest.fixture(params=["httpx2", "httpx"]) + def httpx_lib(self, request): + return importlib.import_module(request.param) + + def test_hits_proxy_through_httpx_client(self, httpx_lib): + class MockServerRequestHandler(MyTestHandler): + pass + + self.setup_mock_server(MockServerRequestHandler) + + client = stripe.StripeClient( + "sk_test_123", + http_client=stripe.HTTPXClient( + proxy=f"http://{MOCK_HOST}:{self.mock_server_port}", + allow_sync_methods=True, + _lib=httpx_lib, + ), + base_addresses={"api": f"http://{MOCK_HOST}:12111"}, + ) + client.balance.retrieve() + + assert MockServerRequestHandler.num_requests == 1 + + @pytest.mark.anyio + async def test_hits_proxy_through_httpx_client_async(self, httpx_lib): + class MockServerRequestHandler(MyTestHandler): + pass + + self.setup_mock_server(MockServerRequestHandler) + + client = stripe.StripeClient( + "sk_test_123", + http_client=stripe.HTTPXClient( + proxy=f"http://{MOCK_HOST}:{self.mock_server_port}", + _lib=httpx_lib, + ), + base_addresses={"api": f"http://{MOCK_HOST}:12111"}, + ) + await client.balance.retrieve_async() + + assert MockServerRequestHandler.num_requests == 1 + def test_passes_client_telemetry_when_enabled(self): class MockServerRequestHandler(MyTestHandler): def do_request(self, req_num): @@ -420,7 +464,7 @@ def do_request(self, n): expected_message = "" if isinstance(hc, stripe.HTTPXClient): - hc._timeout = httpx.Timeout(None, read=0.01) + hc._timeout = httpx2.Timeout(None, read=0.01) expected_message = "A ReadTimeout was raised" elif isinstance(hc, stripe.AIOHTTPClient): hc._timeout = aiohttp.ClientTimeout(sock_read=0.01)