Remove obsolete resource helpers

.hark/changes/2026-09-18_zacchua_remove-unneeded-python-helpers.change.md

@@ -0,0 +1,9 @@
+---
+title: Remove unneeded Python resource helpers
+pr_url: https://github.com/stripe/stripe-python/pull/1922
+semver_level: major
+jira_tickets_closed:
+- DEVSDK-1704
+---
+
+Removed the `SingletonAPIResource` and `nested_resource_class_methods` infrastructure helpers. Concrete resource methods continue to work without changes. Users who imported either helper directly should follow the v16 migration guide.

.hark/migration-guides/v16.md

@@ -20,3 +20,40 @@ response = stripe_object.request("get", "/v1/example")
 client = stripe.StripeClient("sk_test_...")
 response = client.raw_request("get", "/v1/example")
 ```
+
+## Resource infrastructure helpers have been removed
+
+The `SingletonAPIResource` base class and `nested_resource_class_methods`
+decorator have been removed. These were implementation helpers used by
+generated resource classes. Generated singleton and nested-resource methods
+continue to work as before, so most users do not need to make any changes.
+
+If a custom resource subclasses `SingletonAPIResource`, subclass `APIResource`
+and define `instance_url()` directly instead:
+
+```python
+# Before
+from stripe import SingletonAPIResource
+
+
+class MySingleton(SingletonAPIResource["MySingleton"]):
+    @classmethod
+    def class_url(cls):
+        return "/v1/my_singleton"
+
+
+# After
+from stripe import APIResource
+
+
+class MySingleton(APIResource["MySingleton"]):
+    @classmethod
+    def class_url(cls):
+        return "/v1/my_singleton"
+
+    def instance_url(self):
+        return self.class_url()
+```
+
+If custom code uses `nested_resource_class_methods`, remove the decorator and
+define the required nested-resource methods directly on the class.

stripe/__init__.py

@@ -365,9 +365,6 @@ def set_app_info(
     from stripe._login_link import LoginLink as LoginLink
     from stripe._mandate import Mandate as Mandate
     from stripe._mandate_service import MandateService as MandateService
-    from stripe._nested_resource_class_methods import (
-        nested_resource_class_methods as nested_resource_class_methods,
-    )
     from stripe._oauth import OAuth as OAuth
     from stripe._oauth_service import OAuthService as OAuthService
     from stripe._payment_attempt_record import (
@@ -469,9 +466,6 @@ def set_app_info(
         ShippingRateService as ShippingRateService,
     )
     from stripe._sigma_service import SigmaService as SigmaService
-    from stripe._singleton_api_resource import (
-        SingletonAPIResource as SingletonAPIResource,
-    )
     from stripe._source import Source as Source
     from stripe._source_mandate_notification import (
         SourceMandateNotification as SourceMandateNotification,
@@ -764,10 +758,6 @@ def set_app_info(
     "LoginLink": ("stripe._login_link", False),
     "Mandate": ("stripe._mandate", False),
     "MandateService": ("stripe._mandate_service", False),
-    "nested_resource_class_methods": (
-        "stripe._nested_resource_class_methods",
-        False,
-    ),
     "OAuth": ("stripe._oauth", False),
     "OAuthService": ("stripe._oauth_service", False),
     "PaymentAttemptRecord": ("stripe._payment_attempt_record", False),
@@ -847,7 +837,6 @@ def set_app_info(
     "ShippingRate": ("stripe._shipping_rate", False),
     "ShippingRateService": ("stripe._shipping_rate_service", False),
     "SigmaService": ("stripe._sigma_service", False),
-    "SingletonAPIResource": ("stripe._singleton_api_resource", False),
     "Source": ("stripe._source", False),
     "SourceMandateNotification": (
         "stripe._source_mandate_notification",

stripe/_account.py

@@ -5,7 +5,6 @@
 from stripe._expandable_field import ExpandableField
 from stripe._list_object import ListObject
 from stripe._listable_api_resource import ListableAPIResource
-from stripe._nested_resource_class_methods import nested_resource_class_methods
 from stripe._oauth import OAuth
 from stripe._person import Person
 from stripe._stripe_object import StripeObject, UntypedStripeObject
@@ -71,10 +70,6 @@
     from stripe.params._account_unreject_params import AccountUnrejectParams
 
 
-@nested_resource_class_methods("capability")
-@nested_resource_class_methods("external_account")
-@nested_resource_class_methods("login_link")
-@nested_resource_class_methods("person")
 class Account(
     CreateableAPIResource["Account"],
     DeletableAPIResource["Account"],

stripe/_application_fee.py

@@ -3,7 +3,6 @@
 from stripe._expandable_field import ExpandableField
 from stripe._list_object import ListObject
 from stripe._listable_api_resource import ListableAPIResource
-from stripe._nested_resource_class_methods import nested_resource_class_methods
 from stripe._stripe_object import StripeObject
 from stripe._util import class_method_variant, sanitize_id
 from typing import ClassVar, Optional, Union, cast, overload
@@ -38,7 +37,6 @@
     )
 
 
-@nested_resource_class_methods("refund")
 class ApplicationFee(ListableAPIResource["ApplicationFee"]):
     OBJECT_NAME: ClassVar[Literal["application_fee"]] = "application_fee"
 

stripe/_balance.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 # File generated from our OpenAPI spec
-from stripe._singleton_api_resource import SingletonAPIResource
+from stripe._api_resource import APIResource
 from stripe._stripe_object import StripeObject
 from typing import ClassVar, List, Optional
 from typing_extensions import Literal, Unpack, TYPE_CHECKING
@@ -9,7 +9,7 @@
     from stripe.params._balance_retrieve_params import BalanceRetrieveParams
 
 
-class Balance(SingletonAPIResource["Balance"]):
+class Balance(APIResource["Balance"]):
     """
     This is an object representing your Stripe balance. You can retrieve it to see
     the balance currently on your Stripe account.
@@ -307,6 +307,9 @@ async def retrieve_async(
     def class_url(cls):
         return "/v1/balance"
 
+    def instance_url(self):
+        return self.class_url()
+
     _inner_class_types = {
         "available": Available,
         "connect_reserved": ConnectReserved,

stripe/_balance_settings.py

@@ -1,6 +1,5 @@
 # -*- coding: utf-8 -*-
 # File generated from our OpenAPI spec
-from stripe._singleton_api_resource import SingletonAPIResource
 from stripe._stripe_object import StripeObject, UntypedStripeObject
 from stripe._updateable_api_resource import UpdateableAPIResource
 from typing import ClassVar, List, Optional, Union, cast
@@ -15,10 +14,7 @@
     )
 
 
-class BalanceSettings(
-    SingletonAPIResource["BalanceSettings"],
-    UpdateableAPIResource["BalanceSettings"],
-):
+class BalanceSettings(UpdateableAPIResource["BalanceSettings"]):
     """
     Options for customizing account balances and payout settings for a Stripe platform's connected accounts.
     """
@@ -211,4 +207,7 @@ async def retrieve_async(
     def class_url(cls):
         return "/v1/balance_settings"
 
+    def instance_url(self):
+        return self.class_url()
+
     _inner_class_types = {"payments": Payments}

stripe/_charge.py

@@ -4,7 +4,6 @@
 from stripe._expandable_field import ExpandableField
 from stripe._list_object import ListObject
 from stripe._listable_api_resource import ListableAPIResource
-from stripe._nested_resource_class_methods import nested_resource_class_methods
 from stripe._search_result_object import SearchResultObject
 from stripe._searchable_api_resource import SearchableAPIResource
 from stripe._stripe_object import StripeObject, UntypedStripeObject
@@ -51,7 +50,6 @@
     from stripe.params._charge_search_params import ChargeSearchParams
 
 
-@nested_resource_class_methods("refund")
 class Charge(
     CreateableAPIResource["Charge"],
     ListableAPIResource["Charge"],

stripe/_credit_note.py

@@ -4,7 +4,6 @@
 from stripe._expandable_field import ExpandableField
 from stripe._list_object import ListObject
 from stripe._listable_api_resource import ListableAPIResource
-from stripe._nested_resource_class_methods import nested_resource_class_methods
 from stripe._stripe_object import StripeObject, UntypedStripeObject
 from stripe._updateable_api_resource import UpdateableAPIResource
 from stripe._util import class_method_variant, sanitize_id
@@ -43,7 +42,6 @@
     )
 
 
-@nested_resource_class_methods("line")
 class CreditNote(
     CreateableAPIResource["CreditNote"],
     ListableAPIResource["CreditNote"],

stripe/_customer.py

@@ -5,7 +5,6 @@
 from stripe._expandable_field import ExpandableField
 from stripe._list_object import ListObject
 from stripe._listable_api_resource import ListableAPIResource
-from stripe._nested_resource_class_methods import nested_resource_class_methods
 from stripe._search_result_object import SearchResultObject
 from stripe._searchable_api_resource import SearchableAPIResource
 from stripe._stripe_object import StripeObject, UntypedStripeObject
@@ -114,10 +113,6 @@
     from stripe.test_helpers._test_clock import TestClock
 
 
-@nested_resource_class_methods("balance_transaction")
-@nested_resource_class_methods("cash_balance_transaction")
-@nested_resource_class_methods("source")
-@nested_resource_class_methods("tax_id")
 class Customer(
     CreateableAPIResource["Customer"],
     DeletableAPIResource["Customer"],

stripe/_invoice.py

@@ -5,7 +5,6 @@
 from stripe._expandable_field import ExpandableField
 from stripe._list_object import ListObject
 from stripe._listable_api_resource import ListableAPIResource
-from stripe._nested_resource_class_methods import nested_resource_class_methods
 from stripe._search_result_object import SearchResultObject
 from stripe._searchable_api_resource import SearchableAPIResource
 from stripe._stripe_object import StripeObject, UntypedStripeObject
@@ -79,7 +78,6 @@
     from stripe.test_helpers._test_clock import TestClock
 
 
-@nested_resource_class_methods("line")
 class Invoice(
     CreateableAPIResource["Invoice"],
     DeletableAPIResource["Invoice"],

stripe/_payment_intent.py

@@ -4,7 +4,6 @@
 from stripe._expandable_field import ExpandableField
 from stripe._list_object import ListObject
 from stripe._listable_api_resource import ListableAPIResource
-from stripe._nested_resource_class_methods import nested_resource_class_methods
 from stripe._search_result_object import SearchResultObject
 from stripe._searchable_api_resource import SearchableAPIResource
 from stripe._stripe_object import StripeObject, UntypedStripeObject
@@ -75,7 +74,6 @@
     )
 
 
-@nested_resource_class_methods("amount_details_line_item")
 class PaymentIntent(
     CreateableAPIResource["PaymentIntent"],
     ListableAPIResource["PaymentIntent"],

stripe/_product.py

@@ -5,7 +5,6 @@
 from stripe._expandable_field import ExpandableField
 from stripe._list_object import ListObject
 from stripe._listable_api_resource import ListableAPIResource
-from stripe._nested_resource_class_methods import nested_resource_class_methods
 from stripe._search_result_object import SearchResultObject
 from stripe._searchable_api_resource import SearchableAPIResource
 from stripe._stripe_object import StripeObject, UntypedStripeObject
@@ -47,7 +46,6 @@
     from stripe.params._product_search_params import ProductSearchParams
 
 
-@nested_resource_class_methods("feature")
 class Product(
     CreateableAPIResource["Product"],
     DeletableAPIResource["Product"],