Deprecations

stripe/api_requestor.py

@@ -19,7 +19,9 @@
 
 import stripe
 from stripe import error, oauth_error, http_client, version, util
-from stripe.multipart_data_generator import MultipartDataGenerator
+from stripe.multipart_data_generator import (
+    _MultipartDataGenerator as MultipartDataGenerator,
+)
 from urllib.parse import urlencode, urlsplit, urlunsplit
 from stripe.stripe_response import StripeResponse, StripeStreamResponse
 
@@ -45,7 +47,9 @@ def _api_encode(data):
         if value is None:
             continue
         elif hasattr(value, "stripe_id"):
-            yield (key, value.stripe_id)
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore", DeprecationWarning)
+                yield (key, value.stripe_id)
         elif isinstance(value, list) or isinstance(value, tuple):
             for i, sv in enumerate(value):
                 if isinstance(sv, dict):
@@ -119,7 +123,14 @@ def __init__(
             self._default_proxy = proxy
 
     @classmethod
+    @util._deprecated(
+        "This method is internal to stripe-python and the public interface will be removed in a future stripe-python version"
+    )
     def format_app_info(cls, info):
+        return cls._format_app_info(info)
+
+    @classmethod
+    def _format_app_info(cls, info):
         str = info["name"]
         if info["version"]:
             str += "/%s" % (info["version"],)
@@ -189,7 +200,7 @@ def handle_error_response(self, rbody, rcode, resp, rheaders) -> NoReturn:
         raise err
 
     def specific_api_error(self, rbody, rcode, resp, rheaders, error_data):
-        util.log_info(
+        util._log_info(
             "Stripe API error received",
             error_code=error_data.get("code"),
             error_type=error_data.get("type"),
@@ -245,7 +256,7 @@ def specific_api_error(self, rbody, rcode, resp, rheaders, error_data):
     def specific_oauth_error(self, rbody, rcode, resp, rheaders, error_code):
         description = resp.get("error_description", error_code)
 
-        util.log_info(
+        util._log_info(
             "Stripe OAuth error received",
             error_code=error_code,
             error_description=description,
@@ -271,7 +282,7 @@ def specific_oauth_error(self, rbody, rcode, resp, rheaders, error_code):
     def request_headers(self, api_key, method):
         user_agent = "Stripe/v1 PythonBindings/%s" % (version.VERSION,)
         if stripe.app_info:
-            user_agent += " " + self.format_app_info(stripe.app_info)
+            user_agent += " " + self._format_app_info(stripe.app_info)
 
         ua = {
             "bindings_version": version.VERSION,
@@ -380,8 +391,8 @@ def request_raw(
             for key, value in supplied_headers_dict.items():
                 headers[key] = value
 
-        util.log_info("Request to Stripe api", method=method, path=abs_url)
-        util.log_debug(
+        util._log_info("Request to Stripe api", method=method, path=abs_url)
+        util._log_debug(
             "Post details",
             post_data=encoded_params,
             api_version=self.api_version,
@@ -400,14 +411,16 @@ def request_raw(
                 method, abs_url, headers, post_data
             )
 
-        util.log_info("Stripe API response", path=abs_url, response_code=rcode)
-        util.log_debug("API response body", body=rcontent)
+        util._log_info(
+            "Stripe API response", path=abs_url, response_code=rcode
+        )
+        util._log_debug("API response body", body=rcontent)
 
         if "Request-Id" in rheaders:
             request_id = rheaders["Request-Id"]
-            util.log_debug(
+            util._log_debug(
                 "Dashboard link for request",
-                link=util.dashboard_link(request_id),
+                link=util._dashboard_link(request_id),
             )
 
         return rcontent, rcode, rheaders, my_api_key

stripe/api_resources/abstract/api_resource.py

@@ -21,6 +21,9 @@ class APIResource(StripeObject, Generic[T]):
     OBJECT_NAME: ClassVar[str]
 
     @classmethod
+    @util._deprecated(
+        "This method is deprecated and will be removed in a future version of stripe-python. Child classes of APIResource should define their own `retrieve` and use APIResource._request directly."
+    )
     def retrieve(cls, id, api_key=None, **params) -> T:
         instance = cls(id, api_key, **params)
         instance.refresh()

stripe/api_resources/abstract/custom_method.py

@@ -3,6 +3,9 @@
 from urllib.parse import quote_plus
 
 
+@util._deprecated(
+    "the custom_method class decorator will be removed in a future version of stripe-python. Define custom methods directly and use StripeObject._static_request within."
+)
 def custom_method(
     name: str,
     http_verb: str,

stripe/api_resources/abstract/listable_api_resource.py

@@ -8,6 +8,7 @@
 
 class ListableAPIResource(APIResource[T]):
     @classmethod
+    # TODO: inline this onto resources
     def auto_paging_iter(cls, *args, **params):
         return cls.list(*args, **params).auto_paging_iter()
 

stripe/api_resources/abstract/nested_resource_class_methods.py

@@ -4,8 +4,6 @@
 from stripe.api_resources.abstract import APIResource
 
 
-# TODO(major): Remove this. It is no longer used except for "nested_resource_url" and "nested_resource_request",
-# which are unnecessary ande deprecated.
 def nested_resource_class_methods(
     resource: str,
     path: Optional[str] = None,

stripe/api_resources/abstract/singleton_api_resource.py

@@ -11,6 +11,7 @@ class SingletonAPIResource(APIResource[T]):
     def retrieve(cls, **params) -> T:
         return super(SingletonAPIResource, cls).retrieve(None, **params)
 
+    # TODO (before removal): inline onto Tax.Settings and Balance
     @classmethod
     def class_url(cls):
         if cls == SingletonAPIResource:
@@ -23,5 +24,6 @@ def class_url(cls):
         base = cls.OBJECT_NAME.replace(".", "/")
         return "/v1/%s" % (base,)
 
+    # TODO (before removal): inline onto Tax.Settings and Balance
     def instance_url(self):
         return self.class_url()

stripe/api_resources/abstract/updateable_api_resource.py

@@ -13,7 +13,7 @@ def modify(cls, sid, **params) -> T:
         url = "%s/%s" % (cls.class_url(), quote_plus(sid))
         return cast(T, cls._static_request("post", url, params=params))
 
-    @util.deprecated(
+    @util._deprecated(
         "The `save` method is deprecated and will be removed in a future major version of the library. Use the class method `modify` on the resource instead."
     )
     def save(self, idempotency_key=None):

stripe/api_resources/list_object.py

@@ -13,9 +13,11 @@
     cast,
     Mapping,
 )
+from stripe import util
 from stripe.stripe_object import StripeObject
 
 from urllib.parse import quote_plus
+import warnings
 
 T = TypeVar("T", bound=StripeObject)
 
@@ -26,6 +28,9 @@ class ListObject(StripeObject, Generic[T]):
     has_more: bool
     url: str
 
+    @util._deprecated(  # pyright: ignore[reportPrivateUsage]
+        "This will be removed in a future version of stripe-python. Please call the `list` method on the corresponding resource directly, instead of using `list` from the list object."
+    )
     def list(
         self,
         api_key: Optional[str] = None,
@@ -50,6 +55,9 @@ def list(
             ),
         )
 
+    @util._deprecated(  # pyright: ignore[reportPrivateUsage]
+        "This will be removed in a future version of stripe-python. Please call the `create` method on the corresponding resource directly, instead of using `create` from the list object."
+    )
     def create(
         self,
         api_key: Optional[str] = None,
@@ -76,6 +84,9 @@ def create(
             ),
         )
 
+    @util._deprecated(  # pyright: ignore[reportPrivateUsage]
+        "This will be removed in a future version of stripe-python. Please call the `retrieve` method on the corresponding resource directly, instead of using `create` from the list object."
+    )
     def retrieve(
         self,
         id: str,
@@ -148,11 +159,27 @@ def auto_paging_iter(self) -> Iterator[T]:
                 break
 
     @classmethod
+    @util._deprecated(  # pyright: ignore[reportPrivateUsage]
+        "This method is for internal stripe-python use only. The public interface will be removed in a future version."
+    )
     def empty_list(
         cls,
         api_key: Optional[str] = None,
         stripe_version: Optional[str] = None,
         stripe_account: Optional[str] = None,
+    ) -> Self:
+        return cls._empty_list(
+            api_key=api_key,
+            stripe_version=stripe_version,
+            stripe_account=stripe_account,
+        )
+
+    @classmethod
+    def _empty_list(
+        cls,
+        api_key: Optional[str] = None,
+        stripe_version: Optional[str] = None,
+        stripe_account: Optional[str] = None,
     ) -> Self:
         return cls.construct_from(
             {"data": []},
@@ -174,7 +201,7 @@ def next_page(
         **params: Mapping[str, Any]
     ) -> Self:
         if not self.has_more:
-            return self.empty_list(
+            return self._empty_list(
                 api_key=api_key,
                 stripe_version=stripe_version,
                 stripe_account=stripe_account,
@@ -190,13 +217,15 @@ def next_page(
         params_with_filters.update({"starting_after": last_id})
         params_with_filters.update(params)
 
-        result = self.list(
-            api_key=api_key,
-            stripe_version=stripe_version,
-            stripe_account=stripe_account,
-            **params_with_filters,
-        )
-        return result
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", category=DeprecationWarning)
+            result = self.list(  # pyright: ignore[reportDeprecated]
+                api_key=api_key,
+                stripe_version=stripe_version,
+                stripe_account=stripe_account,
+                **params_with_filters,
+            )
+            return result
 
     def previous_page(
         self,
@@ -206,7 +235,7 @@ def previous_page(
         **params: Mapping[str, Any]
     ) -> Self:
         if not self.has_more:
-            return self.empty_list(
+            return self._empty_list(
                 api_key=api_key,
                 stripe_version=stripe_version,
                 stripe_account=stripe_account,
@@ -222,10 +251,12 @@ def previous_page(
         params_with_filters.update({"ending_before": first_id})
         params_with_filters.update(params)
 
-        result = self.list(
-            api_key=api_key,
-            stripe_version=stripe_version,
-            stripe_account=stripe_account,
-            **params_with_filters,
-        )
-        return result
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", category=DeprecationWarning)
+            result = self.list(  # pyright: ignore[reportDeprecated]
+                api_key=api_key,
+                stripe_version=stripe_version,
+                stripe_account=stripe_account,
+                **params_with_filters,
+            )
+            return result

stripe/api_resources/search_result_object.py

@@ -12,6 +12,8 @@
 )
 
 from stripe.stripe_object import StripeObject
+from stripe import util
+import warnings
 
 T = TypeVar("T", bound=StripeObject)
 
@@ -22,6 +24,9 @@ class SearchResultObject(StripeObject, Generic[T]):
     has_more: bool
     next_page: str
 
+    @util._deprecated(  # pyright: ignore[reportPrivateUsage]
+        "This will be removed in a future version of stripe-python. Please call the `search` method on the corresponding resource directly, instead of the generic search on SearchResultObject."
+    )
     def search(
         self,
         api_key: Optional[str] = None,
@@ -78,7 +83,7 @@ def auto_paging_iter(self) -> Iterator[T]:
                 break
 
     @classmethod
-    def empty_search_result(
+    def _empty_search_result(
         cls,
         api_key: Optional[str] = None,
         stripe_version: Optional[str] = None,
@@ -92,6 +97,20 @@ def empty_search_result(
             last_response=None,
         )
 
+    @classmethod
+    @util._deprecated(  # pyright: ignore[reportPrivateUsage]
+        "For internal stripe-python use only. This will be removed in a future version."
+    )
+    def empty_search_result(
+        cls,
+        api_key: Optional[str] = None,
+        stripe_version: Optional[str] = None,
+        stripe_account: Optional[str] = None,
+    ) -> Self:
+        return cls._empty_search_result(
+            api_key, stripe_version, stripe_account
+        )
+
     @property
     def is_empty(self) -> bool:
         return not self.data
@@ -104,7 +123,7 @@ def next_search_result_page(
         **params: Mapping[str, Any]
     ) -> Self:
         if not self.has_more:
-            return self.empty_search_result(
+            return self._empty_search_result(
                 api_key=api_key,
                 stripe_version=stripe_version,
                 stripe_account=stripe_account,
@@ -114,10 +133,12 @@ def next_search_result_page(
         params_with_filters.update({"page": self.next_page})
         params_with_filters.update(params)
 
-        result = self.search(
-            api_key=api_key,
-            stripe_version=stripe_version,
-            stripe_account=stripe_account,
-            **params_with_filters,
-        )
-        return result
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            result = self.search(  # pyright: ignore[reportDeprecated]
+                api_key=api_key,
+                stripe_version=stripe_version,
+                stripe_account=stripe_account,
+                **params_with_filters,
+            )
+            return result

stripe/error.py

@@ -1,6 +1,8 @@
 from typing import Dict, Optional, Union, cast
 import stripe
 from stripe.api_resources.error_object import ErrorObject
+from stripe import util
+import warnings
 
 
 class StripeError(Exception):
@@ -41,7 +43,9 @@ def __init__(
         self.headers = headers or {}
         self.code = code
         self.request_id = self.headers.get("request-id", None)
-        self.error = self.construct_error_object()
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            self.error = self.construct_error_object()
 
     def __str__(self):
         msg = self._message or "<empty message>"
@@ -66,6 +70,9 @@ def __repr__(self):
             self.request_id,
         )
 
+    @util._deprecated(
+        "For internal stripe-python use only. The public interface will be removed in a future version."
+    )
     def construct_error_object(self) -> Optional[ErrorObject]:
         if (
             self.json_body is None