Skip to content

Apply positional-only service path parameters, and updat… #1920

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mark-kogan-stripe wants to merge 1 commit into
base: sdk-release/next-major
Choose a base branch
from
Open

Apply positional-only service path parameters, and updat… #1920

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions ...changes/2026-09-18_markisaackogan_mark-path-params-as-positional-only.change.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
title: Make path parameters positional-only in all service methods
pr_url: https://github.com/stripe/stripe-python/pull/1920
semver_level: major
---

Path parameters must now be passed positionally to service methods. Passing them by keyword is no longer supported. Resource methods are unaffected by this change.
18 changes: 18 additions & 0 deletions .hark/migration-guides/v16.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,3 +20,21 @@ response = stripe_object.request("get", "/v1/example")
client = stripe.StripeClient("sk_test_...")
response = client.raw_request("get", "/v1/example")
```

## Keyword arguments are no longer allowed in Stripe service methods

Path parameters in all service methods must now be passed positionally instead of by keyword. This prevents parameter names derived from the API specification from becoming part of the public interface.

For example, a customer ID that was previously accepted as a keyword argument:

```python
customer = client.v1.customers.retrieve(customer="cus_123")
```

must now be passed positionally:

```python
customer = client.v1.customers.retrieve("cus_123")
```

Update calls to service methods, including async service methods, to pass path parameters before any request parameters or options. Resource methods are unaffected by this change.
10 changes: 10 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,16 @@ Instead, edit a corresponding `.change.md` file and run `hark build`.

# Changelog

## Unreleased
* [#1904](https://github.com/stripe/stripe-python/pull/1904) Support `EventNotification`s with singleton related objects
* [#1909](https://github.com/stripe/stripe-python/pull/1909) Allow suppressing Stripe notices
Set the `STRIPE_SUPPRESS_NOTICES` environment variable to `true` to suppress Stripe notices in test and sandbox environments when not running under a detected AI agent. Notices remain enabled by default and continue to be shown to AI agents.
* [#1911](https://github.com/stripe/stripe-python/pull/1911) Fix account scoping for event notification handler callback clients
- Fix callback clients to use the event's Stripe context and preserve the original client's non-account configuration.
- Fix API errors when using an event notification handler with a client configured with a Stripe account.
* ⚠️ [#1919](https://github.com/stripe/stripe-python/pull/1919) Make path parameters positional-only in all service methods
Path parameters must now be passed positionally to service methods. Passing them by keyword is no longer supported. Resource methods are unaffected by this change.

## <a id="15-6-1"></a>15.6.1 - 2026-09-01
* [#1860](https://github.com/stripe/stripe-python/pull/1860) Dispatch discriminated union fields to their variant class
* [#1896](https://github.com/stripe/stripe-python/pull/1896) Harden API requestor code against malicious URLs
Expand Down
60 changes: 40 additions & 20 deletions stripe/_account.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1919,7 +1919,7 @@ async def list_async(

@classmethod
def _cls_persons(
cls, account: str, **params: Unpack["AccountPersonsParams"]
cls, account: str, /, **params: Unpack["AccountPersonsParams"]
) -> ListObject["Person"]:
"""
Returns a list of people associated with the account's legal entity. The people are returned sorted by creation date, with the most recent people appearing first.
Expand All @@ -1938,7 +1938,7 @@ def _cls_persons(
@overload
@staticmethod
def persons(
account: str, **params: Unpack["AccountPersonsParams"]
account: str, /, **params: Unpack["AccountPersonsParams"]
) -> ListObject["Person"]:
"""
Returns a list of people associated with the account's legal entity. The people are returned sorted by creation date, with the most recent people appearing first.
Expand Down Expand Up @@ -1974,7 +1974,7 @@ def persons( # pyright: ignore[reportGeneralTypeIssues]

@classmethod
async def _cls_persons_async(
cls, account: str, **params: Unpack["AccountPersonsParams"]
cls, account: str, /, **params: Unpack["AccountPersonsParams"]
) -> ListObject["Person"]:
"""
Returns a list of people associated with the account's legal entity. The people are returned sorted by creation date, with the most recent people appearing first.
Expand All @@ -1993,7 +1993,7 @@ async def _cls_persons_async(
@overload
@staticmethod
async def persons_async(
account: str, **params: Unpack["AccountPersonsParams"]
account: str, /, **params: Unpack["AccountPersonsParams"]
) -> ListObject["Person"]:
"""
Returns a list of people associated with the account's legal entity. The people are returned sorted by creation date, with the most recent people appearing first.
Expand Down Expand Up @@ -2029,7 +2029,7 @@ async def persons_async( # pyright: ignore[reportGeneralTypeIssues]

@classmethod
def _cls_reject(
cls, account: str, **params: Unpack["AccountRejectParams"]
cls, account: str, /, **params: Unpack["AccountRejectParams"]
) -> "Account":
"""
With [Connect](https://docs.stripe.com/connect), you can reject accounts that you have flagged as suspicious.
Expand All @@ -2050,7 +2050,7 @@ def _cls_reject(
@overload
@staticmethod
def reject(
account: str, **params: Unpack["AccountRejectParams"]
account: str, /, **params: Unpack["AccountRejectParams"]
) -> "Account":
"""
With [Connect](https://docs.stripe.com/connect), you can reject accounts that you have flagged as suspicious.
Expand Down Expand Up @@ -2090,7 +2090,7 @@ def reject( # pyright: ignore[reportGeneralTypeIssues]

@classmethod
async def _cls_reject_async(
cls, account: str, **params: Unpack["AccountRejectParams"]
cls, account: str, /, **params: Unpack["AccountRejectParams"]
) -> "Account":
"""
With [Connect](https://docs.stripe.com/connect), you can reject accounts that you have flagged as suspicious.
Expand All @@ -2111,7 +2111,7 @@ async def _cls_reject_async(
@overload
@staticmethod
async def reject_async(
account: str, **params: Unpack["AccountRejectParams"]
account: str, /, **params: Unpack["AccountRejectParams"]
) -> "Account":
"""
With [Connect](https://docs.stripe.com/connect), you can reject accounts that you have flagged as suspicious.
Expand Down Expand Up @@ -2153,7 +2153,7 @@ async def reject_async( # pyright: ignore[reportGeneralTypeIssues]

@classmethod
def _cls_unreject(
cls, account: str, **params: Unpack["AccountUnrejectParams"]
cls, account: str, /, **params: Unpack["AccountUnrejectParams"]
) -> "Account":
"""
With Connect, you can unreject accounts that you have previously rejected.
Expand All @@ -2176,7 +2176,7 @@ def _cls_unreject(
@overload
@staticmethod
def unreject(
account: str, **params: Unpack["AccountUnrejectParams"]
account: str, /, **params: Unpack["AccountUnrejectParams"]
) -> "Account":
"""
With Connect, you can unreject accounts that you have previously rejected.
Expand Down Expand Up @@ -2222,7 +2222,7 @@ def unreject( # pyright: ignore[reportGeneralTypeIssues]

@classmethod
async def _cls_unreject_async(
cls, account: str, **params: Unpack["AccountUnrejectParams"]
cls, account: str, /, **params: Unpack["AccountUnrejectParams"]
) -> "Account":
"""
With Connect, you can unreject accounts that you have previously rejected.
Expand All @@ -2245,7 +2245,7 @@ async def _cls_unreject_async(
@overload
@staticmethod
async def unreject_async(
account: str, **params: Unpack["AccountUnrejectParams"]
account: str, /, **params: Unpack["AccountUnrejectParams"]
) -> "Account":
"""
With Connect, you can unreject accounts that you have previously rejected.
Expand Down Expand Up @@ -2343,7 +2343,7 @@ def serialize(self, previous):

@classmethod
def list_capabilities(
cls, account: str, **params: Unpack["AccountListCapabilitiesParams"]
cls, account: str, /, **params: Unpack["AccountListCapabilitiesParams"]
) -> ListObject["Capability"]:
"""
Returns a list of capabilities associated with the account. The capabilities are returned sorted by creation date, with the most recent capability appearing first.
Expand All @@ -2361,7 +2361,7 @@ def list_capabilities(

@classmethod
async def list_capabilities_async(
cls, account: str, **params: Unpack["AccountListCapabilitiesParams"]
cls, account: str, /, **params: Unpack["AccountListCapabilitiesParams"]
) -> ListObject["Capability"]:
"""
Returns a list of capabilities associated with the account. The capabilities are returned sorted by creation date, with the most recent capability appearing first.
Expand All @@ -2382,6 +2382,7 @@ def retrieve_capability(
cls,
account: str,
capability: str,
/,
**params: Unpack["AccountRetrieveCapabilityParams"],
) -> "Capability":
"""
Expand All @@ -2404,6 +2405,7 @@ async def retrieve_capability_async(
cls,
account: str,
capability: str,
/,
**params: Unpack["AccountRetrieveCapabilityParams"],
) -> "Capability":
"""
Expand All @@ -2426,6 +2428,7 @@ def modify_capability(
cls,
account: str,
capability: str,
/,
**params: Unpack["AccountModifyCapabilityParams"],
) -> "Capability":
"""
Expand All @@ -2448,6 +2451,7 @@ async def modify_capability_async(
cls,
account: str,
capability: str,
/,
**params: Unpack["AccountModifyCapabilityParams"],
) -> "Capability":
"""
Expand All @@ -2470,6 +2474,7 @@ def delete_external_account(
cls,
account: str,
id: str,
/,
**params: Unpack["AccountDeleteExternalAccountParams"],
) -> Union["BankAccount", "Card"]:
"""
Expand All @@ -2491,6 +2496,7 @@ async def delete_external_account_async(
cls,
account: str,
id: str,
/,
**params: Unpack["AccountDeleteExternalAccountParams"],
) -> Union["BankAccount", "Card"]:
"""
Expand All @@ -2512,6 +2518,7 @@ def retrieve_external_account(
cls,
account: str,
id: str,
/,
**params: Unpack["AccountRetrieveExternalAccountParams"],
) -> Union["BankAccount", "Card"]:
"""
Expand All @@ -2533,6 +2540,7 @@ async def retrieve_external_account_async(
cls,
account: str,
id: str,
/,
**params: Unpack["AccountRetrieveExternalAccountParams"],
) -> Union["BankAccount", "Card"]:
"""
Expand All @@ -2554,6 +2562,7 @@ def modify_external_account(
cls,
account: str,
id: str,
/,
**params: Unpack["AccountModifyExternalAccountParams"],
) -> Union["BankAccount", "Card"]:
"""
Expand Down Expand Up @@ -2582,6 +2591,7 @@ async def modify_external_account_async(
cls,
account: str,
id: str,
/,
**params: Unpack["AccountModifyExternalAccountParams"],
) -> Union["BankAccount", "Card"]:
"""
Expand Down Expand Up @@ -2609,6 +2619,7 @@ async def modify_external_account_async(
def list_external_accounts(
cls,
account: str,
/,
**params: Unpack["AccountListExternalAccountsParams"],
) -> ListObject[Union["BankAccount", "Card"]]:
"""
Expand All @@ -2629,6 +2640,7 @@ def list_external_accounts(
async def list_external_accounts_async(
cls,
account: str,
/,
**params: Unpack["AccountListExternalAccountsParams"],
) -> ListObject[Union["BankAccount", "Card"]]:
"""
Expand All @@ -2649,6 +2661,7 @@ async def list_external_accounts_async(
def create_external_account(
cls,
account: str,
/,
**params: Unpack["AccountCreateExternalAccountParams"],
) -> Union["BankAccount", "Card"]:
"""
Expand All @@ -2669,6 +2682,7 @@ def create_external_account(
async def create_external_account_async(
cls,
account: str,
/,
**params: Unpack["AccountCreateExternalAccountParams"],
) -> Union["BankAccount", "Card"]:
"""
Expand All @@ -2687,7 +2701,7 @@ async def create_external_account_async(

@classmethod
def create_login_link(
cls, account: str, **params: Unpack["AccountCreateLoginLinkParams"]
cls, account: str, /, **params: Unpack["AccountCreateLoginLinkParams"]
) -> "LoginLink":
"""
Creates a login link for a connected account to access the Express Dashboard.
Expand All @@ -2707,7 +2721,7 @@ def create_login_link(

@classmethod
async def create_login_link_async(
cls, account: str, **params: Unpack["AccountCreateLoginLinkParams"]
cls, account: str, /, **params: Unpack["AccountCreateLoginLinkParams"]
) -> "LoginLink":
"""
Creates a login link for a connected account to access the Express Dashboard.
Expand All @@ -2730,6 +2744,7 @@ def delete_person(
cls,
account: str,
person: str,
/,
**params: Unpack["AccountDeletePersonParams"],
) -> "Person":
"""
Expand All @@ -2751,6 +2766,7 @@ async def delete_person_async(
cls,
account: str,
person: str,
/,
**params: Unpack["AccountDeletePersonParams"],
) -> "Person":
"""
Expand All @@ -2772,6 +2788,7 @@ def retrieve_person(
cls,
account: str,
person: str,
/,
**params: Unpack["AccountRetrievePersonParams"],
) -> "Person":
"""
Expand All @@ -2793,6 +2810,7 @@ async def retrieve_person_async(
cls,
account: str,
person: str,
/,
**params: Unpack["AccountRetrievePersonParams"],
) -> "Person":
"""
Expand All @@ -2814,6 +2832,7 @@ def modify_person(
cls,
account: str,
person: str,
/,
**params: Unpack["AccountModifyPersonParams"],
) -> "Person":
"""
Expand All @@ -2835,6 +2854,7 @@ async def modify_person_async(
cls,
account: str,
person: str,
/,
**params: Unpack["AccountModifyPersonParams"],
) -> "Person":
"""
Expand All @@ -2853,7 +2873,7 @@ async def modify_person_async(

@classmethod
def list_persons(
cls, account: str, **params: Unpack["AccountListPersonsParams"]
cls, account: str, /, **params: Unpack["AccountListPersonsParams"]
) -> ListObject["Person"]:
"""
Returns a list of people associated with the account's legal entity. The people are returned sorted by creation date, with the most recent people appearing first.
Expand All @@ -2871,7 +2891,7 @@ def list_persons(

@classmethod
async def list_persons_async(
cls, account: str, **params: Unpack["AccountListPersonsParams"]
cls, account: str, /, **params: Unpack["AccountListPersonsParams"]
) -> ListObject["Person"]:
"""
Returns a list of people associated with the account's legal entity. The people are returned sorted by creation date, with the most recent people appearing first.
Expand All @@ -2889,7 +2909,7 @@ async def list_persons_async(

@classmethod
def create_person(
cls, account: str, **params: Unpack["AccountCreatePersonParams"]
cls, account: str, /, **params: Unpack["AccountCreatePersonParams"]
) -> "Person":
"""
Creates a new person.
Expand All @@ -2907,7 +2927,7 @@ def create_person(

@classmethod
async def create_person_async(
cls, account: str, **params: Unpack["AccountCreatePersonParams"]
cls, account: str, /, **params: Unpack["AccountCreatePersonParams"]
) -> "Person":
"""
Creates a new person.
Expand Down
Loading
Loading