Move all_children functions to GA (#320)

Author: jchen293

CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+## v7.15.0 Next release
+
+- Adds `all_children` function to the User class for retrieving paginated lists of children users, and deprecate the beta function
+- Adds `get_next_page_of_children` function to the User class for retrieving next paginated lists of children users, and deprecate the beta function
+
 ## v7.14.1 (2023-10-30)
 
 - Fixes a bug where `get_next_page` functions threw an error, preventing users from retrieving the final page of results

easypost/beta/user.py

@@ -4,6 +4,7 @@
     List,
     Optional,
 )
+from warnings import warn
 
 from easypost.easypost_object import convert_to_easypost_object
 from easypost.error import Error
@@ -17,6 +18,11 @@
 class User(Resource):
     @classmethod
     def all_children(cls, api_key: Optional[str] = None, **params) -> Dict[str, Any]:
+        warn(
+            "This function is deprecated, please use `all_children` function in `user` class for GA accessibility",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         """Retrieve a paginated list of children from the API."""
         requestor = Requestor(local_api_key=api_key)
         url = "/users/children"
@@ -30,6 +36,12 @@ def get_next_page_of_children(
         page_size: int,
         api_key: Optional[str] = None,
     ) -> List["User"]:
+        warn(
+            "This function is deprecated, please use `get_next_page_of_children` function in"
+            "`user` class for GA accessibility",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         """Get next page of children."""
         requestor = Requestor(local_api_key=api_key)
         url = "/users/children"

easypost/requestor.py

@@ -42,7 +42,7 @@ def _objects_to_ids(cls, param: Dict[str, Any]) -> Dict[str, Any]:
             return {"id": param.id}
         elif isinstance(param, dict):
             data = {}
-            for (k, v) in param.items():
+            for k, v in param.items():
                 if isinstance(v, list):
                     data[k] = [cls._objects_to_ids(item) for item in v]  # type: ignore
                 else:

easypost/user.py

@@ -7,6 +7,7 @@
 
 from easypost.api_key import ApiKey
 from easypost.easypost_object import convert_to_easypost_object
+from easypost.error import Error
 from easypost.requestor import (
     RequestMethod,
     Requestor,
@@ -83,3 +84,38 @@ def update_brand(self, api_key: Optional[str] = None, **params) -> "User":
             method=RequestMethod.PATCH, url=self.instance_url() + "/brand", params=params
         )
         return convert_to_easypost_object(response=response, api_key=api_key)
+
+    @classmethod
+    def all_children(cls, api_key: Optional[str] = None, **params) -> Dict[str, Any]:
+        """Retrieve a paginated list of children from the API."""
+        requestor = Requestor(local_api_key=api_key)
+        url = "/users/children"
+        response, api_key = requestor.request(method=RequestMethod.GET, url=url, params=params)
+        return convert_to_easypost_object(response=response, api_key=api_key)
+
+    @classmethod
+    def get_next_page_of_children(
+        cls,
+        children: Dict[str, Any],
+        page_size: int,
+        api_key: Optional[str] = None,
+    ) -> List["User"]:
+        """Get next page of children."""
+        requestor = Requestor(local_api_key=api_key)
+        url = "/users/children"
+        children_array = children.get("children", [])
+
+        if len(children_array) == 0 or not children.get("has_more", False):
+            raise Error(message="There are no more pages to retrieve.")
+
+        params = {
+            "after_id": children_array[-1].id,
+            "page_size": page_size,
+        }
+
+        data, api_key = requestor.request(method=RequestMethod.GET, url=url, params=params)
+        next_children_array: List[Any] = data.get("children", [])
+        if len(next_children_array) == 0:
+            raise Error(message="There are no more pages to retrieve.")
+
+        return convert_to_easypost_object(response=data, api_key=api_key)

tests/cassettes/test_user_all_children.yaml

@@ -109,3 +109,30 @@ def test_user_update_brand(prod_api_key):
     assert isinstance(brand, easypost.Brand)
     assert str.startswith(brand.id, "brd_")
     assert brand.color == color
+
+
+@pytest.mark.vcr()
+def test_user_all_children(prod_api_key, page_size):
+    children_data = easypost.User.all_children(page_size=page_size)
+
+    children_array = children_data["children"]
+    assert len(children_array) <= page_size
+    assert all(isinstance(child, easypost.User) for child in children_array)
+
+    has_more = children_data["has_more"]
+    assert isinstance(has_more, bool)
+
+
+@pytest.mark.vcr()
+def test_user_get_next_page(prod_api_key, page_size):
+    try:
+        children = easypost.User.all_children(page_size=page_size)
+        next_page = easypost.User.get_next_page_of_children(children=children, page_size=page_size)
+
+        first_id_of_first_page = children["children"][0].id
+        first_id_of_second_page = next_page["children"][0].id
+
+        assert first_id_of_first_page != first_id_of_second_page
+    except easypost.Error as e:
+        if e.message != "There are no more pages to retrieve.":
+            raise easypost.Error(message="Test failed intentionally.")