Types for CRUDL methods on parents (#1032)

flake8_stripe/flake8_stripe.py

@@ -41,6 +41,7 @@ class TypingImportsChecker:
         "overload",
         "Dict",
         "List",
+        "Generic",
     ]
 
     def __init__(self, tree: ast.AST):

stripe/api_resources/abstract/api_resource.py

@@ -3,17 +3,19 @@
 from stripe import api_requestor, error, util
 from stripe.stripe_object import StripeObject
 from urllib.parse import quote_plus
-from typing import ClassVar
+from typing import ClassVar, Generic, TypeVar, cast
 
+T = TypeVar("T", bound=StripeObject)
 
-class APIResource(StripeObject):
+
+class APIResource(StripeObject, Generic[T]):
     OBJECT_NAME: ClassVar[str]
 
     @classmethod
-    def retrieve(cls, id, api_key=None, **params):
+    def retrieve(cls, id, api_key=None, **params) -> T:
         instance = cls(id, api_key, **params)
         instance.refresh()
-        return instance
+        return cast(T, instance)
 
     def refresh(self):
         return self._request_and_refresh("get", self.instance_url())

stripe/api_resources/abstract/createable_api_resource.py

@@ -1,9 +1,13 @@
 from __future__ import absolute_import, division, print_function
 
 from stripe.api_resources.abstract.api_resource import APIResource
+from typing import TypeVar, cast
+from stripe.stripe_object import StripeObject
 
+T = TypeVar("T", bound=StripeObject)
 
-class CreateableAPIResource(APIResource):
+
+class CreateableAPIResource(APIResource[T]):
     @classmethod
     def create(
         cls,
@@ -12,13 +16,16 @@ def create(
         stripe_version=None,
         stripe_account=None,
         **params
-    ):
-        return cls._static_request(
-            "post",
-            cls.class_url(),
-            api_key,
-            idempotency_key,
-            stripe_version,
-            stripe_account,
-            params,
+    ) -> T:
+        return cast(
+            T,
+            cls._static_request(
+                "post",
+                cls.class_url(),
+                api_key,
+                idempotency_key,
+                stripe_version,
+                stripe_account,
+                params,
+            ),
         )

stripe/api_resources/abstract/deletable_api_resource.py

@@ -3,16 +3,23 @@
 from stripe import util
 from stripe.api_resources.abstract.api_resource import APIResource
 from urllib.parse import quote_plus
+from typing import TypeVar, cast
+from stripe.stripe_object import StripeObject
 
+T = TypeVar("T", bound=StripeObject)
 
-class DeletableAPIResource(APIResource):
+
+class DeletableAPIResource(APIResource[T]):
     @classmethod
-    def _cls_delete(cls, sid, **params):
+    def _cls_delete(cls, sid, **params) -> T:
         url = "%s/%s" % (cls.class_url(), quote_plus(sid))
-        return cls._static_request("delete", url, params=params)
+        return cast(T, cls._static_request("delete", url, params=params))
 
     @util.class_method_variant("_cls_delete")
-    def delete(self, **params):
-        return self._request_and_refresh(
-            "delete", self.instance_url(), params=params
+    def delete(self, **params) -> T:
+        return cast(
+            T,
+            self._request_and_refresh(
+                "delete", self.instance_url(), params=params
+            ),
         )

stripe/api_resources/abstract/listable_api_resource.py

@@ -2,17 +2,21 @@
 
 from stripe.api_resources.abstract.api_resource import APIResource
 from stripe.api_resources.list_object import ListObject
+from stripe.stripe_object import StripeObject
+from typing import TypeVar
 
+T = TypeVar("T", bound=StripeObject)
 
-class ListableAPIResource(APIResource):
+
+class ListableAPIResource(APIResource[T]):
     @classmethod
     def auto_paging_iter(cls, *args, **params):
         return cls.list(*args, **params).auto_paging_iter()
 
     @classmethod
     def list(
         cls, api_key=None, stripe_version=None, stripe_account=None, **params
-    ) -> ListObject:
+    ) -> ListObject[T]:
         result = cls._static_request(
             "get",
             cls.class_url(),

stripe/api_resources/abstract/searchable_api_resource.py

@@ -2,9 +2,14 @@
 
 from stripe.api_resources.abstract.api_resource import APIResource
 from stripe.api_resources.search_result_object import SearchResultObject
+from typing import TypeVar
+from stripe.stripe_object import StripeObject
 
 
-class SearchableAPIResource(APIResource):
+T = TypeVar("T", bound=StripeObject)
+
+
+class SearchableAPIResource(APIResource[T]):
     @classmethod
     def _search(
         cls,

stripe/api_resources/abstract/singleton_api_resource.py

@@ -2,10 +2,15 @@
 
 from stripe.api_resources.abstract.api_resource import APIResource
 
+from typing import TypeVar
+from stripe.stripe_object import StripeObject
 
-class SingletonAPIResource(APIResource):
+T = TypeVar("T", bound=StripeObject)
+
+
+class SingletonAPIResource(APIResource[T]):
     @classmethod
-    def retrieve(cls, **params):
+    def retrieve(cls, **params) -> T:
         return super(SingletonAPIResource, cls).retrieve(None, **params)
 
     @classmethod

stripe/api_resources/abstract/test_helpers.py

@@ -5,10 +5,9 @@
 
 from typing import TypeVar, ClassVar, Any
 from typing_extensions import Protocol
+from stripe.api_resources.abstract import APIResource
 
-from stripe.api_resources.abstract.api_resource import APIResource
-
-T = TypeVar("T", bound=APIResource)
+T = TypeVar("T", bound=APIResource[Any])
 
 
 class APIResourceTestHelpers(Protocol[T]):

stripe/api_resources/abstract/updateable_api_resource.py

@@ -3,13 +3,17 @@
 from stripe import util
 from stripe.api_resources.abstract.api_resource import APIResource
 from urllib.parse import quote_plus
+from typing import TypeVar, cast
+from stripe.stripe_object import StripeObject
 
+T = TypeVar("T", bound=StripeObject)
 
-class UpdateableAPIResource(APIResource):
+
+class UpdateableAPIResource(APIResource[T]):
     @classmethod
-    def modify(cls, sid, **params):
+    def modify(cls, sid, **params) -> T:
         url = "%s/%s" % (cls.class_url(), quote_plus(sid))
-        return cls._static_request("post", url, params=params)
+        return cast(T, cls._static_request("post", url, params=params))
 
     def save(self, idempotency_key=None):
         """

stripe/api_resources/account.py

@@ -31,10 +31,10 @@
     operations=["create", "retrieve", "update", "delete", "list"],
 )
 class Account(
-    CreateableAPIResource,
-    DeletableAPIResource,
-    ListableAPIResource,
-    UpdateableAPIResource,
+    CreateableAPIResource["Account"],
+    DeletableAPIResource["Account"],
+    ListableAPIResource["Account"],
+    UpdateableAPIResource["Account"],
 ):
     """
     This is an object representing a Stripe account. You can retrieve it to see

stripe/api_resources/account_link.py

@@ -5,7 +5,7 @@
 from stripe.api_resources.abstract import CreateableAPIResource
 
 
-class AccountLink(CreateableAPIResource):
+class AccountLink(CreateableAPIResource["AccountLink"]):
     """
     Account Links are the means by which a Connect platform grants a connected account permission to access
     Stripe-hosted applications, such as Connect Onboarding.

stripe/api_resources/apple_pay_domain.py

@@ -8,9 +8,9 @@
 
 
 class ApplePayDomain(
-    CreateableAPIResource,
-    DeletableAPIResource,
-    ListableAPIResource,
+    CreateableAPIResource["ApplePayDomain"],
+    DeletableAPIResource["ApplePayDomain"],
+    ListableAPIResource["ApplePayDomain"],
 ):
     OBJECT_NAME = "apple_pay_domain"
 

stripe/api_resources/application_fee.py

@@ -11,7 +11,7 @@
     "refund",
     operations=["create", "retrieve", "update", "list"],
 )
-class ApplicationFee(ListableAPIResource):
+class ApplicationFee(ListableAPIResource["ApplicationFee"]):
     OBJECT_NAME = "application_fee"
 
     @classmethod

stripe/api_resources/application_fee_refund.py

@@ -7,7 +7,7 @@
 from urllib.parse import quote_plus
 
 
-class ApplicationFeeRefund(UpdateableAPIResource):
+class ApplicationFeeRefund(UpdateableAPIResource["ApplicationFeeRefund"]):
     """
     `Application Fee Refund` objects allow you to refund an application fee that
     has previously been created but not yet refunded. Funds will be refunded to

stripe/api_resources/apps/secret.py

@@ -6,7 +6,7 @@
 from stripe.api_resources.abstract import ListableAPIResource
 
 
-class Secret(CreateableAPIResource, ListableAPIResource):
+class Secret(CreateableAPIResource["Secret"], ListableAPIResource["Secret"]):
     """
     Secret Store is an API that allows Stripe Apps developers to securely persist secrets for use by UI Extensions and app backends.
 

stripe/api_resources/balance.py

@@ -5,7 +5,7 @@
 from stripe.api_resources.abstract import SingletonAPIResource
 
 
-class Balance(SingletonAPIResource):
+class Balance(SingletonAPIResource["Balance"]):
     """
     This is an object representing your Stripe balance. You can retrieve it to see
     the balance currently on your Stripe account.

stripe/api_resources/balance_transaction.py

@@ -5,7 +5,7 @@
 from stripe.api_resources.abstract import ListableAPIResource
 
 
-class BalanceTransaction(ListableAPIResource):
+class BalanceTransaction(ListableAPIResource["BalanceTransaction"]):
     """
     Balance transactions represent funds moving through your Stripe account.
     They're created for every type of transaction that comes into or flows out of your Stripe account balance.

stripe/api_resources/bank_account.py

@@ -11,7 +11,11 @@
 from urllib.parse import quote_plus
 
 
-class BankAccount(DeletableAPIResource, UpdateableAPIResource, VerifyMixin):
+class BankAccount(
+    DeletableAPIResource["BankAccount"],
+    UpdateableAPIResource["BankAccount"],
+    VerifyMixin,
+):
     """
     These bank accounts are payment methods on `Customer` objects.
 

stripe/api_resources/billing_portal/configuration.py

@@ -8,9 +8,9 @@
 
 
 class Configuration(
-    CreateableAPIResource,
-    ListableAPIResource,
-    UpdateableAPIResource,
+    CreateableAPIResource["Configuration"],
+    ListableAPIResource["Configuration"],
+    UpdateableAPIResource["Configuration"],
 ):
     """
     A portal configuration describes the functionality and behavior of a portal session.

stripe/api_resources/billing_portal/session.py

@@ -5,7 +5,7 @@
 from stripe.api_resources.abstract import CreateableAPIResource
 
 
-class Session(CreateableAPIResource):
+class Session(CreateableAPIResource["Session"]):
     """
     The Billing customer portal is a Stripe-hosted UI for subscription and
     billing management.

stripe/api_resources/capability.py

@@ -7,7 +7,7 @@
 from urllib.parse import quote_plus
 
 
-class Capability(UpdateableAPIResource):
+class Capability(UpdateableAPIResource["Capability"]):
     """
     This is an object representing a capability for a Stripe account.
 

stripe/api_resources/card.py

@@ -10,7 +10,7 @@
 from urllib.parse import quote_plus
 
 
-class Card(DeletableAPIResource, UpdateableAPIResource):
+class Card(DeletableAPIResource["Card"], UpdateableAPIResource["Card"]):
     """
     You can store multiple cards on a customer in order to charge the customer
     later. You can also store multiple debit cards on a recipient in order to

stripe/api_resources/cash_balance.py

@@ -2,12 +2,12 @@
 # File generated from our OpenAPI spec
 from __future__ import absolute_import, division, print_function
 
-from stripe.api_resources.abstract import APIResource
 from stripe.api_resources.customer import Customer
+from stripe.stripe_object import StripeObject
 from urllib.parse import quote_plus
 
 
-class CashBalance(APIResource):
+class CashBalance(StripeObject):
     """
     A customer's `Cash balance` represents real funds. Customers can add funds to their cash balance by sending a bank transfer. These funds can be used for payment and can eventually be paid out to your bank account.
     """

stripe/api_resources/charge.py

@@ -10,10 +10,10 @@
 
 
 class Charge(
-    CreateableAPIResource,
-    ListableAPIResource,
-    SearchableAPIResource,
-    UpdateableAPIResource,
+    CreateableAPIResource["Charge"],
+    ListableAPIResource["Charge"],
+    SearchableAPIResource["Charge"],
+    UpdateableAPIResource["Charge"],
 ):
     """
     The `Charge` object represents a single attempt to move money into your Stripe account.

stripe/api_resources/checkout/session.py

@@ -7,7 +7,9 @@
 from stripe.api_resources.abstract import ListableAPIResource
 
 
-class Session(CreateableAPIResource, ListableAPIResource):
+class Session(
+    CreateableAPIResource["Session"], ListableAPIResource["Session"]
+):
     """
     A Checkout Session represents your customer's session as they pay for
     one-time purchases or subscriptions through [Checkout](https://stripe.com/docs/payments/checkout)

stripe/api_resources/country_spec.py

@@ -5,7 +5,7 @@
 from stripe.api_resources.abstract import ListableAPIResource
 
 
-class CountrySpec(ListableAPIResource):
+class CountrySpec(ListableAPIResource["CountrySpec"]):
     """
     Stripe needs to collect certain pieces of information about each account
     created. These requirements can differ depending on the account's country. The

stripe/api_resources/coupon.py

@@ -9,10 +9,10 @@
 
 
 class Coupon(
-    CreateableAPIResource,
-    DeletableAPIResource,
-    ListableAPIResource,
-    UpdateableAPIResource,
+    CreateableAPIResource["Coupon"],
+    DeletableAPIResource["Coupon"],
+    ListableAPIResource["Coupon"],
+    UpdateableAPIResource["Coupon"],
 ):
     """
     A coupon contains information about a percent-off or amount-off discount you