Add all_children and get_next_page_of_children functions (#315)

CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+## Next release
+
+- Adds `all_children` function to the User service for retrieving paginated lists of children
+- Adds `get_next_page_of_children` function to User service to get next paginated list of children
+
 ## v9.0.1 (2023-12-20)
 
 - Corrects the return type of `regenerate_rates`

Makefile

@@ -27,7 +27,7 @@ clean:
 
 ## coverage - Test the project and generate an HTML coverage report
 coverage:
-	$(VIRTUAL_BIN)/pytest --cov=$(PROJECT_NAME) --cov-branch --cov-report=html --cov-report=lcov --cov-report=term-missing --cov-fail-under=88
+	$(VIRTUAL_BIN)/pytest --cov=$(PROJECT_NAME) --cov-branch --cov-report=html --cov-report=lcov --cov-report=term-missing --cov-fail-under=87
 
 ## docs - Generates docs for the library
 docs:

easypost/services/user_service.py

@@ -117,3 +117,33 @@ def update_brand(self, id: str, **params) -> User:
         )
 
         return convert_to_easypost_object(response=response)
+
+    def all_children(self, **params) -> Dict[str, Any]:
+        """Retrieve a paginated list of children from the API."""
+        url = "/users/children"
+        response = Requestor(self._client).request(
+            method=RequestMethod.GET,
+            url=url,
+            params=params,
+        )
+
+        return convert_to_easypost_object(response=response)
+
+    def get_next_page_of_children(
+        self,
+        children: Dict[str, Any],
+        page_size: int,
+        optional_params: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Retrieve the next page of the list Children response."""
+        self._check_has_next_page(collection=children)
+
+        params = {
+            "before_id": children["children"][-1].id,
+            "page_size": page_size,
+        }
+
+        if optional_params:
+            params.update(optional_params)
+
+        return self.all_children(**params)

tests/test_user.py

@@ -1,4 +1,9 @@
 import pytest
+from easypost.constant import (
+    _FILTERS_KEY,
+    _TEST_FAILED_INTENTIONALLY_ERROR,
+    NO_MORE_PAGES_ERROR,
+)
 from easypost.models import (
     Brand,
     User,
@@ -76,3 +81,33 @@ def test_user_update_brand(prod_client):
     assert isinstance(brand, Brand)
     assert str.startswith(brand.id, "brd_")
     assert brand.color == color
+
+
+@pytest.mark.vcr()
+def test_user_all_children(prod_client, page_size):
+    children_data = prod_client.user.all_children(page_size=page_size)
+
+    children_array = children_data["children"]
+    assert len(children_array) <= page_size
+    assert all(isinstance(child, User) for child in children_array)
+
+    has_more = children_data["has_more"]
+    assert isinstance(has_more, bool)
+
+
+@pytest.mark.vcr()
+def test_user_children_get_next_page(prod_client, page_size):
+    try:
+        first_page = prod_client.user.all_children(page_size=page_size)
+        next_page = prod_client.user.get_next_page_of_children(children=first_page, page_size=page_size)
+
+        first_id_of_first_page = first_page["children"][0].id
+        first_id_of_second_page = next_page["children"][0].id
+
+        assert first_id_of_first_page != first_id_of_second_page
+
+        # Verify that the filters are being passed along for behind-the-scenes reference
+        assert first_page[_FILTERS_KEY] == next_page[_FILTERS_KEY]
+    except Exception as e:
+        if e.message != NO_MORE_PAGES_ERROR:
+            raise Exception(_TEST_FAILED_INTENTIONALLY_ERROR)