From 023a25c06a20f69859e8c10272466b702fdd3c2f Mon Sep 17 00:00:00 2001 From: zacchua-stripe Date: Tue, 10 Nov 2026 13:54:12 -0800 Subject: [PATCH 1/5] =?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/5] 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/5] 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/5] 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/5] 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] = []