diff --git a/.hark/changes/2026-09-17_zacchua_rename-reversal-transferreversal.change.md b/.hark/changes/2026-09-17_zacchua_rename-reversal-transferreversal.change.md new file mode 100644 index 000000000..b18ec5eb2 --- /dev/null +++ b/.hark/changes/2026-09-17_zacchua_rename-reversal-transferreversal.change.md @@ -0,0 +1,7 @@ +--- +title: Rename `stripe.Reversal` to `stripe.TransferReversal` +pr_url: https://github.com/stripe/stripe-python/pull/1915 +semver_level: major +--- + +- ⚠️ Rename the `stripe.Reversal` resource class to `stripe.TransferReversal`. Update references and type annotations to use `stripe.TransferReversal`. diff --git a/.hark/migration-guides/v16.md b/.hark/migration-guides/v16.md index a505f380b..6a29d3a23 100644 --- a/.hark/migration-guides/v16.md +++ b/.hark/migration-guides/v16.md @@ -8,6 +8,24 @@ You will almost certainly need before/after code examples and information about See: https://github.com/stripe/hark#writing-a-great-migration-guide --> +## Rename `stripe.Reversal` to `stripe.TransferReversal` + +The class representing a transfer reversal has been renamed from `stripe.Reversal` to `stripe.TransferReversal`. + +This change affects integrations that reference `stripe.Reversal` directly, including imports, class comparisons, `isinstance` checks, and type annotations. Replace those references with `stripe.TransferReversal`: + +```python +# Before +reversal = stripe.Transfer.retrieve_reversal("tr_123", "trr_123") +isinstance(reversal, stripe.Reversal) + +# After +reversal = stripe.Transfer.retrieve_reversal("tr_123", "trr_123") +isinstance(reversal, stripe.TransferReversal) +``` + +The methods for creating, retrieving, modifying, and listing transfer reversals have not changed. Code that only calls those methods and reads attributes from the returned object does not require an update. + ## `StripeObject.request()` has been removed The deprecated `StripeObject.request()` method has been removed. If you used it to make custom API requests, create a `StripeClient` and use `raw_request()` instead: diff --git a/stripe/__init__.py b/stripe/__init__.py index b1e4ffa26..3221f5871 100644 --- a/stripe/__init__.py +++ b/stripe/__init__.py @@ -447,7 +447,7 @@ def set_app_info( from stripe._reserve_transaction import ( ReserveTransaction as ReserveTransaction, ) - from stripe._reversal import Reversal as Reversal + from stripe._transfer_reversal import TransferReversal as TransferReversal from stripe._review import Review as Review from stripe._review_service import ReviewService as ReviewService from stripe._search_result_object import ( @@ -835,7 +835,7 @@ def set_app_info( "RequestOptions": ("stripe._request_options", False), "RequestorOptions": ("stripe._requestor_options", False), "ReserveTransaction": ("stripe._reserve_transaction", False), - "Reversal": ("stripe._reversal", False), + "TransferReversal": ("stripe._transfer_reversal", False), "Review": ("stripe._review", False), "ReviewService": ("stripe._review_service", False), "SearchResultObject": ("stripe._search_result_object", False), diff --git a/stripe/_balance_transaction.py b/stripe/_balance_transaction.py index a5ee4eb36..22d0ab50d 100644 --- a/stripe/_balance_transaction.py +++ b/stripe/_balance_transaction.py @@ -19,7 +19,7 @@ from stripe._payout import Payout from stripe._refund import Refund from stripe._reserve_transaction import ReserveTransaction - from stripe._reversal import Reversal + from stripe._transfer_reversal import TransferReversal from stripe._tax_deducted_at_source import TaxDeductedAtSource from stripe._topup import Topup from stripe._transfer import Transfer @@ -146,7 +146,7 @@ class FeeDetail(StripeObject): "TaxDeductedAtSource", "Topup", "Transfer", - "Reversal", + "TransferReversal", ] ] ] diff --git a/stripe/_object_classes.py b/stripe/_object_classes.py index d93383f5f..3b7720ff8 100644 --- a/stripe/_object_classes.py +++ b/stripe/_object_classes.py @@ -226,7 +226,7 @@ "stripe._reserve_transaction", "ReserveTransaction", ), - "transfer_reversal": ("stripe._reversal", "Reversal"), + "transfer_reversal": ("stripe._transfer_reversal", "TransferReversal"), "review": ("stripe._review", "Review"), "setup_attempt": ("stripe._setup_attempt", "SetupAttempt"), "setup_intent": ("stripe._setup_intent", "SetupIntent"), diff --git a/stripe/_refund.py b/stripe/_refund.py index 608e4a08b..b6ea2d371 100644 --- a/stripe/_refund.py +++ b/stripe/_refund.py @@ -17,7 +17,7 @@ from stripe._customer import Customer from stripe._payment_intent import PaymentIntent from stripe._payment_method import PaymentMethod - from stripe._reversal import Reversal + from stripe._transfer_reversal import TransferReversal from stripe.params._refund_cancel_params import RefundCancelParams from stripe.params._refund_create_params import RefundCreateParams from stripe.params._refund_expire_params import RefundExpireParams @@ -473,7 +473,7 @@ class PresentmentDetails(StripeObject): """ This is the transaction number that appears on email receipts sent for this refund. """ - source_transfer_reversal: Optional[ExpandableField["Reversal"]] + source_transfer_reversal: Optional[ExpandableField["TransferReversal"]] """ The transfer reversal that's associated with the refund. Only present if the charge came from another Stripe account. """ @@ -481,7 +481,7 @@ class PresentmentDetails(StripeObject): """ Status of the refund. This can be `pending`, `requires_action`, `succeeded`, `failed`, or `canceled`. Learn more about [failed refunds](https://docs.stripe.com/refunds#failed-refunds). """ - transfer_reversal: Optional[ExpandableField["Reversal"]] + transfer_reversal: Optional[ExpandableField["TransferReversal"]] """ This refers to the transfer reversal object if the accompanying transfer reverses. This is only applicable if the charge was created using the destination parameter. """ diff --git a/stripe/_transfer.py b/stripe/_transfer.py index c746222ba..f9d16d60b 100644 --- a/stripe/_transfer.py +++ b/stripe/_transfer.py @@ -15,7 +15,7 @@ from stripe._account import Account from stripe._balance_transaction import BalanceTransaction from stripe._charge import Charge - from stripe._reversal import Reversal + from stripe._transfer_reversal import TransferReversal from stripe.params._transfer_create_params import TransferCreateParams from stripe.params._transfer_create_reversal_params import ( TransferCreateReversalParams, @@ -102,7 +102,7 @@ class Transfer( """ String representing the object's type. Objects of the same type share the same value. """ - reversals: ListObject["Reversal"] + reversals: ListObject["TransferReversal"] """ A list of reversals that have been applied to the transfer. """ @@ -256,12 +256,12 @@ async def retrieve_async( @classmethod def list_reversals( cls, id: str, /, **params: Unpack["TransferListReversalsParams"] - ) -> ListObject["Reversal"]: + ) -> ListObject["TransferReversal"]: """ You can see a list of the reversals belonging to a specific transfer. Note that the 10 most recent reversals are always available by default on the transfer object. If you need more than those 10, you can use this API method and the limit and starting_after parameters to page through additional reversals. """ return cast( - ListObject["Reversal"], + ListObject["TransferReversal"], cls._static_request( "get", "/v1/transfers/{id}/reversals".format(id=sanitize_id(id)), @@ -272,12 +272,12 @@ def list_reversals( @classmethod async def list_reversals_async( cls, id: str, /, **params: Unpack["TransferListReversalsParams"] - ) -> ListObject["Reversal"]: + ) -> ListObject["TransferReversal"]: """ You can see a list of the reversals belonging to a specific transfer. Note that the 10 most recent reversals are always available by default on the transfer object. If you need more than those 10, you can use this API method and the limit and starting_after parameters to page through additional reversals. """ return cast( - ListObject["Reversal"], + ListObject["TransferReversal"], await cls._static_request_async( "get", "/v1/transfers/{id}/reversals".format(id=sanitize_id(id)), @@ -288,7 +288,7 @@ async def list_reversals_async( @classmethod def create_reversal( cls, id: str, /, **params: Unpack["TransferCreateReversalParams"] - ) -> "Reversal": + ) -> "TransferReversal": """ When you create a new reversal, you must specify a transfer to create it on. @@ -297,7 +297,7 @@ def create_reversal( Once entirely reversed, a transfer can't be reversed again. This method will return an error when called on an already-reversed transfer, or when trying to reverse more money than is left on a transfer. """ return cast( - "Reversal", + "TransferReversal", cls._static_request( "post", "/v1/transfers/{id}/reversals".format(id=sanitize_id(id)), @@ -308,7 +308,7 @@ def create_reversal( @classmethod async def create_reversal_async( cls, id: str, /, **params: Unpack["TransferCreateReversalParams"] - ) -> "Reversal": + ) -> "TransferReversal": """ When you create a new reversal, you must specify a transfer to create it on. @@ -317,7 +317,7 @@ async def create_reversal_async( Once entirely reversed, a transfer can't be reversed again. This method will return an error when called on an already-reversed transfer, or when trying to reverse more money than is left on a transfer. """ return cast( - "Reversal", + "TransferReversal", await cls._static_request_async( "post", "/v1/transfers/{id}/reversals".format(id=sanitize_id(id)), @@ -332,12 +332,12 @@ def retrieve_reversal( id: str, /, **params: Unpack["TransferRetrieveReversalParams"], - ) -> "Reversal": + ) -> "TransferReversal": """ By default, you can see the 10 most recent reversals stored directly on the transfer object, but you can also retrieve details about a specific reversal stored on the transfer. """ return cast( - "Reversal", + "TransferReversal", cls._static_request( "get", "/v1/transfers/{transfer}/reversals/{id}".format( @@ -354,12 +354,12 @@ async def retrieve_reversal_async( id: str, /, **params: Unpack["TransferRetrieveReversalParams"], - ) -> "Reversal": + ) -> "TransferReversal": """ By default, you can see the 10 most recent reversals stored directly on the transfer object, but you can also retrieve details about a specific reversal stored on the transfer. """ return cast( - "Reversal", + "TransferReversal", await cls._static_request_async( "get", "/v1/transfers/{transfer}/reversals/{id}".format( @@ -376,14 +376,14 @@ def modify_reversal( id: str, /, **params: Unpack["TransferModifyReversalParams"], - ) -> "Reversal": + ) -> "TransferReversal": """ Updates the specified reversal by setting the values of the parameters passed. Any parameters not provided will be left unchanged. This request only accepts metadata and description as arguments. """ return cast( - "Reversal", + "TransferReversal", cls._static_request( "post", "/v1/transfers/{transfer}/reversals/{id}".format( @@ -400,14 +400,14 @@ async def modify_reversal_async( id: str, /, **params: Unpack["TransferModifyReversalParams"], - ) -> "Reversal": + ) -> "TransferReversal": """ Updates the specified reversal by setting the values of the parameters passed. Any parameters not provided will be left unchanged. This request only accepts metadata and description as arguments. """ return cast( - "Reversal", + "TransferReversal", await cls._static_request_async( "post", "/v1/transfers/{transfer}/reversals/{id}".format( diff --git a/stripe/_reversal.py b/stripe/_transfer_reversal.py similarity index 98% rename from stripe/_reversal.py rename to stripe/_transfer_reversal.py index f6a6e5109..2a9dc2566 100644 --- a/stripe/_reversal.py +++ b/stripe/_transfer_reversal.py @@ -13,7 +13,7 @@ from stripe._refund import Refund -class Reversal(UpdateableAPIResource["Reversal"]): +class TransferReversal(UpdateableAPIResource["TransferReversal"]): """ [Stripe Connect](https://docs.stripe.com/connect) platforms can reverse transfers made to a connected account, either entirely or partially, and can also specify whether diff --git a/stripe/_transfer_reversal_service.py b/stripe/_transfer_reversal_service.py index e25f76cf0..c418478f2 100644 --- a/stripe/_transfer_reversal_service.py +++ b/stripe/_transfer_reversal_service.py @@ -8,7 +8,7 @@ if TYPE_CHECKING: from stripe._list_object import ListObject from stripe._request_options import RequestOptions - from stripe._reversal import Reversal + from stripe._transfer_reversal import TransferReversal from stripe.params._transfer_reversal_create_params import ( TransferReversalCreateParams, ) @@ -30,12 +30,12 @@ def list( /, params: Optional["TransferReversalListParams"] = None, options: Optional["RequestOptions"] = None, - ) -> "ListObject[Reversal]": + ) -> "ListObject[TransferReversal]": """ You can see a list of the reversals belonging to a specific transfer. Note that the 10 most recent reversals are always available by default on the transfer object. If you need more than those 10, you can use this API method and the limit and starting_after parameters to page through additional reversals. """ return cast( - "ListObject[Reversal]", + "ListObject[TransferReversal]", self._request( "get", "/v1/transfers/{id}/reversals".format(id=sanitize_id(id)), @@ -51,12 +51,12 @@ async def list_async( /, params: Optional["TransferReversalListParams"] = None, options: Optional["RequestOptions"] = None, - ) -> "ListObject[Reversal]": + ) -> "ListObject[TransferReversal]": """ You can see a list of the reversals belonging to a specific transfer. Note that the 10 most recent reversals are always available by default on the transfer object. If you need more than those 10, you can use this API method and the limit and starting_after parameters to page through additional reversals. """ return cast( - "ListObject[Reversal]", + "ListObject[TransferReversal]", await self._request_async( "get", "/v1/transfers/{id}/reversals".format(id=sanitize_id(id)), @@ -72,7 +72,7 @@ def create( /, params: Optional["TransferReversalCreateParams"] = None, options: Optional["RequestOptions"] = None, - ) -> "Reversal": + ) -> "TransferReversal": """ When you create a new reversal, you must specify a transfer to create it on. @@ -81,7 +81,7 @@ def create( Once entirely reversed, a transfer can't be reversed again. This method will return an error when called on an already-reversed transfer, or when trying to reverse more money than is left on a transfer. """ return cast( - "Reversal", + "TransferReversal", self._request( "post", "/v1/transfers/{id}/reversals".format(id=sanitize_id(id)), @@ -97,7 +97,7 @@ async def create_async( /, params: Optional["TransferReversalCreateParams"] = None, options: Optional["RequestOptions"] = None, - ) -> "Reversal": + ) -> "TransferReversal": """ When you create a new reversal, you must specify a transfer to create it on. @@ -106,7 +106,7 @@ async def create_async( Once entirely reversed, a transfer can't be reversed again. This method will return an error when called on an already-reversed transfer, or when trying to reverse more money than is left on a transfer. """ return cast( - "Reversal", + "TransferReversal", await self._request_async( "post", "/v1/transfers/{id}/reversals".format(id=sanitize_id(id)), @@ -123,12 +123,12 @@ def retrieve( /, params: Optional["TransferReversalRetrieveParams"] = None, options: Optional["RequestOptions"] = None, - ) -> "Reversal": + ) -> "TransferReversal": """ By default, you can see the 10 most recent reversals stored directly on the transfer object, but you can also retrieve details about a specific reversal stored on the transfer. """ return cast( - "Reversal", + "TransferReversal", self._request( "get", "/v1/transfers/{transfer}/reversals/{id}".format( @@ -148,12 +148,12 @@ async def retrieve_async( /, params: Optional["TransferReversalRetrieveParams"] = None, options: Optional["RequestOptions"] = None, - ) -> "Reversal": + ) -> "TransferReversal": """ By default, you can see the 10 most recent reversals stored directly on the transfer object, but you can also retrieve details about a specific reversal stored on the transfer. """ return cast( - "Reversal", + "TransferReversal", await self._request_async( "get", "/v1/transfers/{transfer}/reversals/{id}".format( @@ -173,14 +173,14 @@ def update( /, params: Optional["TransferReversalUpdateParams"] = None, options: Optional["RequestOptions"] = None, - ) -> "Reversal": + ) -> "TransferReversal": """ Updates the specified reversal by setting the values of the parameters passed. Any parameters not provided will be left unchanged. This request only accepts metadata and description as arguments. """ return cast( - "Reversal", + "TransferReversal", self._request( "post", "/v1/transfers/{transfer}/reversals/{id}".format( @@ -200,14 +200,14 @@ async def update_async( /, params: Optional["TransferReversalUpdateParams"] = None, options: Optional["RequestOptions"] = None, - ) -> "Reversal": + ) -> "TransferReversal": """ Updates the specified reversal by setting the values of the parameters passed. Any parameters not provided will be left unchanged. This request only accepts metadata and description as arguments. """ return cast( - "Reversal", + "TransferReversal", await self._request_async( "post", "/v1/transfers/{transfer}/reversals/{id}".format( diff --git a/tests/api_resources/test_reversal.py b/tests/api_resources/test_transfer_reversal.py similarity index 72% rename from tests/api_resources/test_reversal.py rename to tests/api_resources/test_transfer_reversal.py index 0d96dc187..f4ebf110a 100644 --- a/tests/api_resources/test_reversal.py +++ b/tests/api_resources/test_transfer_reversal.py @@ -6,15 +6,17 @@ TEST_RESOURCE_ID = "trr_123" -class TestReversal(object): +class TestTransferReversal(object): def construct_resource(self): reversal_dict = { "id": TEST_RESOURCE_ID, - "object": "reversal", + "object": "transfer_reversal", "metadata": {}, "transfer": "tr_123", } - return stripe.Reversal.construct_from(reversal_dict, stripe.api_key) + return stripe.TransferReversal.construct_from( + reversal_dict, stripe.api_key + ) def test_has_instance_url(self): resource = self.construct_resource() @@ -25,11 +27,13 @@ def test_has_instance_url(self): def test_is_not_modifiable(self): with pytest.raises(NotImplementedError): - stripe.Reversal.modify(TEST_RESOURCE_ID, metadata={"key": "value"}) + stripe.TransferReversal.modify( + TEST_RESOURCE_ID, metadata={"key": "value"} + ) def test_is_not_retrievable(self): with pytest.raises(NotImplementedError): - stripe.Reversal.retrieve(TEST_RESOURCE_ID) + stripe.TransferReversal.retrieve(TEST_RESOURCE_ID) def test_is_saveable(self, http_client_mock): resource = self.construct_resource()