[feat] Add beta feature to retrieve paginated child user list (#300)

Author: nwithan8

easypost/beta/__init__.py

@@ -2,3 +2,4 @@
 from easypost.beta.carrier_metadata import CarrierMetadata
 from easypost.beta.rate import Rate
 from easypost.beta.referral import Referral
+from easypost.beta.user import User

easypost/beta/user.py

@@ -0,0 +1,51 @@
+from typing import (
+    Any,
+    Dict,
+    List,
+    Optional,
+)
+
+from easypost.easypost_object import convert_to_easypost_object
+from easypost.error import Error
+from easypost.requestor import (
+    RequestMethod,
+    Requestor,
+)
+from easypost.resource import Resource
+
+
+class User(Resource):
+    @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, beta=True)
+        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, beta=True)
+        next_children_array: List[Any] = data.get("children", [])
+        if len(next_children_array) == 0 or not data.get("has_more", False):
+            raise Error(message="There are no more pages to retrieve.")
+
+        return convert_to_easypost_object(response=data, api_key=api_key)

tests/cassettes/test_beta_user_all_children.yaml

@@ -0,0 +1,30 @@
+import pytest
+
+import easypost
+
+
+@pytest.mark.vcr()
+def test_beta_user_all_children(prod_api_key, page_size):
+    children_data = easypost.beta.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_beta_user_get_next_page(prod_api_key, page_size):
+    try:
+        children = easypost.beta.User.all_children(page_size=page_size)
+        next_page = easypost.beta.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.")