Mark defunct and internal methods as deprecated (#1101)

stripe/_api_requestor.py

@@ -78,7 +78,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"],)
@@ -230,7 +237,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,

stripe/_api_resource.py

@@ -8,6 +8,7 @@
 )
 from stripe._api_requestor import APIRequestor
 from stripe._stripe_object import StripeObject
+from stripe import _util
 from urllib.parse import quote_plus
 from typing import (
     Any,
@@ -28,6 +29,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/_custom_method.py

@@ -3,6 +3,10 @@
 from urllib.parse import quote_plus
 
 
+# TODO(major): 1704.
+@_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/_error.py

@@ -4,6 +4,9 @@
 import stripe  # noqa: IMP101
 from stripe._error_object import ErrorObject
 
+from stripe import _util
+import warnings
+
 
 class StripeError(Exception):
     _message: Optional[str]
@@ -43,7 +46,7 @@ def __init__(
         self.headers = headers or {}
         self.code = code
         self.request_id = self.headers.get("request-id", None)
-        self.error = self.construct_error_object()
+        self.error = self._construct_error_object()
 
     def __str__(self):
         msg = self._message or "<empty message>"
@@ -68,6 +71,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
@@ -81,6 +87,11 @@ def construct_error_object(self) -> Optional[ErrorObject]:
             self.json_body["error"], stripe.api_key
         )
 
+    def _construct_error_object(self):
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            return self.construct_error_object()
+
 
 class APIError(StripeError):
     pass

stripe/_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,25 @@ class ListObject(StripeObject, Generic[T]):
     has_more: bool
     url: str
 
+    def _list(
+        self,
+        api_key: Optional[str] = None,
+        stripe_version: Optional[str] = None,
+        stripe_account: Optional[str] = None,
+        **params: Mapping[str, Any]
+    ) -> Self:
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", category=DeprecationWarning)
+            return self.list(  # pyright: ignore[reportDeprecated]
+                api_key=api_key,
+                stripe_version=stripe_version,
+                stripe_account=stripe_account,
+                **params,
+            )
+
+    @_util.deprecated(
+        "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 +71,9 @@ def list(
             ),
         )
 
+    @_util.deprecated(
+        "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 +100,9 @@ def create(
             ),
         )
 
+    @_util.deprecated(
+        "This will be removed in a future version of stripe-python. Please call the `retrieve` method on the corresponding resource directly, instead of using `retrieve` from the list object."
+    )
     def retrieve(
         self,
         id: str,
@@ -148,11 +175,27 @@ def auto_paging_iter(self) -> Iterator[T]:
                 break
 
     @classmethod
+    @_util.deprecated(
+        "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 +217,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 +233,12 @@ def next_page(
         params_with_filters.update({"starting_after": last_id})
         params_with_filters.update(params)
 
-        result = self.list(
+        return self._list(
             api_key=api_key,
             stripe_version=stripe_version,
             stripe_account=stripe_account,
             **params_with_filters,
         )
-        return result
 
     def previous_page(
         self,
@@ -206,7 +248,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,7 +264,7 @@ def previous_page(
         params_with_filters.update({"ending_before": first_id})
         params_with_filters.update(params)
 
-        result = self.list(
+        result = self._list(
             api_key=api_key,
             stripe_version=stripe_version,
             stripe_account=stripe_account,

stripe/_listable_api_resource.py

@@ -5,6 +5,9 @@
 
 T = TypeVar("T", bound=StripeObject)
 
+# TODO(major): 1704 - remove this class and all internal usages. `.list` is already inlined into the resource classes.
+# Although we should inline .auto_paging_iter into the resource classes as well.
+
 
 class ListableAPIResource(APIResource[T]):
     @classmethod

stripe/_nested_resource_class_methods.py

@@ -4,8 +4,8 @@
 from stripe._api_resource 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.
+# TODO(major): 1704. Remove this. It is no longer used except for "nested_resource_url" and "nested_resource_request",
+# which are unnecessary and deprecated and should also be removed.
 def nested_resource_class_methods(
     resource: str,
     path: Optional[str] = None,

stripe/_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,25 @@ class SearchResultObject(StripeObject, Generic[T]):
     has_more: bool
     next_page: str
 
+    def _search(
+        self,
+        api_key: Optional[str] = None,
+        stripe_version: Optional[str] = None,
+        stripe_account: Optional[str] = None,
+        **params: Mapping[str, Any]
+    ) -> Self:
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            return self.search(  # pyright: ignore[reportDeprecated]
+                api_key=api_key,
+                stripe_version=stripe_version,
+                stripe_account=stripe_account,
+                **params,
+            )
+
+    @_util.deprecated(
+        "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 +99,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 +113,22 @@ def empty_search_result(
             last_response=None,
         )
 
+    @classmethod
+    @_util.deprecated(
+        "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=api_key,
+            stripe_version=stripe_version,
+            stripe_account=stripe_account,
+        )
+
     @property
     def is_empty(self) -> bool:
         return not self.data
@@ -104,7 +141,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 +151,9 @@ def next_search_result_page(
         params_with_filters.update({"page": self.next_page})
         params_with_filters.update(params)
 
-        result = self.search(
+        return self._search(
             api_key=api_key,
             stripe_version=stripe_version,
             stripe_account=stripe_account,
             **params_with_filters,
         )
-        return result

stripe/_singleton_api_resource.py

@@ -5,6 +5,8 @@
 
 T = TypeVar("T", bound=StripeObject)
 
+# TODO(major): 1704 - Inline into Tax.Settings and Balance, and remove this class.
+
 
 class SingletonAPIResource(APIResource[T]):
     @classmethod