Fix pagination schema to match nested response structure

stainless-app[bot] · stainless-app[bot] · commit 4fc3af695ffd · 2026-02-12T07:12:53.000Z
diff --git a/.stats.yml b/.stats.yml
@@ -1,4 +1,4 @@
 configured_endpoints: 9
 openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/nanonets%2Fdocstrange-a418fe45369669cc2d14b549ee010f3a7ee52f6e47fea3489e560d33064be099.yml
 openapi_spec_hash: 02f7f52faae1eb42188c290c32c25f10
-config_hash: 618498b0a12e1535b716981b83e1f760
+config_hash: de4c18021060af5ebd13aa207675d379
diff --git a/README.md b/README.md
@@ -112,6 +112,67 @@ Nested request parameters are [TypedDicts](https://docs.python.org/3/library/typ
 
 Typed requests and responses provide autocomplete and documentation within your editor. If you would like to see type errors in VS Code to help catch bugs earlier, set `python.analysis.typeCheckingMode` to `basic`.
 
+## Pagination
+
+List methods in the Docstrange API are paginated.
+
+This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:
+
+```python
+from docstrange import Docstrange
+
+client = Docstrange()
+
+all_results = []
+# Automatically fetches more pages as needed.
+for result in client.extract.results.list():
+    # Do something with result here
+    all_results.append(result)
+print(all_results)
+```
+
+Or, asynchronously:
+
+```python
+import asyncio
+from docstrange import AsyncDocstrange
+
+client = AsyncDocstrange()
+
+
+async def main() -> None:
+    all_results = []
+    # Iterate through items across all pages, issuing requests as needed.
+    async for result in client.extract.results.list():
+        all_results.append(result)
+    print(all_results)
+
+
+asyncio.run(main())
+```
+
+Alternatively, you can use the `.has_next_page()`, `.next_page_info()`, or `.get_next_page()` methods for more granular control working with pages:
+
+```python
+first_page = await client.extract.results.list()
+if first_page.has_next_page():
+    print(f"will fetch next page using these details: {first_page.next_page_info()}")
+    next_page = await first_page.get_next_page()
+    print(f"number of items we just fetched: {len(next_page.results)}")
+
+# Remove `await` for non-async usage.
+```
+
+Or just work directly with the returned data:
+
+```python
+first_page = await client.extract.results.list()
+for result in first_page.results:
+    print(result.record_id)
+
+# Remove `await` for non-async usage.
+```
+
 ## File uploads
 
 Request parameters that correspond to file uploads can be passed as `bytes`, or a [`PathLike`](https://docs.python.org/3/library/os.html#os.PathLike) instance or a tuple of `(filename, contents, media type)`.
diff --git a/api.md b/api.md
@@ -34,7 +34,7 @@ from docstrange.types.extract import ExtractionListResponse, PaginationInfo
 Methods:
 
 - <code title="get /api/v1/extract/results/{record_id}">client.extract.results.<a href="./src/docstrange/resources/extract/results.py">retrieve</a>(record_id, \*\*<a href="src/docstrange/types/extract/result_retrieve_params.py">params</a>) -> <a href="./src/docstrange/types/extract_response.py">ExtractResponse</a></code>
-- <code title="get /api/v1/extract/results">client.extract.results.<a href="./src/docstrange/resources/extract/results.py">list</a>(\*\*<a href="src/docstrange/types/extract/result_list_params.py">params</a>) -> <a href="./src/docstrange/types/extract/extraction_list_response.py">ExtractionListResponse</a></code>
+- <code title="get /api/v1/extract/results">client.extract.results.<a href="./src/docstrange/resources/extract/results.py">list</a>(\*\*<a href="src/docstrange/types/extract/result_list_params.py">params</a>) -> <a href="./src/docstrange/types/extract_response.py">SyncPageNumberPagination[ExtractResponse]</a></code>
 
 # Classify
 
diff --git a/src/docstrange/pagination.py b/src/docstrange/pagination.py
@@ -3,46 +3,65 @@
 from typing import List, Generic, TypeVar, Optional, cast
 from typing_extensions import override
 
+from ._models import BaseModel
 from ._base_client import BasePage, PageInfo, BaseSyncPage, BaseAsyncPage
 
-__all__ = ["SyncPageNumberPagination", "AsyncPageNumberPagination"]
+__all__ = ["PageNumberPaginationPagination", "SyncPageNumberPagination", "AsyncPageNumberPagination"]
 
 _T = TypeVar("_T")
 
 
-class SyncPageNumberPagination(BaseSyncPage[_T], BasePage[_T], Generic[_T]):
-    items: List[_T]
-    total_count: Optional[int] = None
+class PageNumberPaginationPagination(BaseModel):
     has_next: Optional[bool] = None
 
+    total_count: Optional[int] = None
+
+
+class SyncPageNumberPagination(BaseSyncPage[_T], BasePage[_T], Generic[_T]):
+    results: List[_T]
+    pagination: Optional[PageNumberPaginationPagination] = None
+
     @override
     def _get_page_items(self) -> List[_T]:
-        items = self.items
-        if not items:
+        results = self.results
+        if not results:
             return []
-        return items
+        return results
 
     @override
     def next_page_info(self) -> Optional[PageInfo]:
         last_page = cast("int | None", self._options.params.get("page")) or 1
 
+        total_pages = None
+        if self.pagination is not None:
+            if self.pagination.total_count is not None:
+                total_pages = self.pagination.total_count
+        if total_pages is not None and last_page >= total_pages:
+            return None
+
         return PageInfo(params={"page": last_page + 1})
 
 
 class AsyncPageNumberPagination(BaseAsyncPage[_T], BasePage[_T], Generic[_T]):
-    items: List[_T]
-    total_count: Optional[int] = None
-    has_next: Optional[bool] = None
+    results: List[_T]
+    pagination: Optional[PageNumberPaginationPagination] = None
 
     @override
     def _get_page_items(self) -> List[_T]:
-        items = self.items
-        if not items:
+        results = self.results
+        if not results:
             return []
-        return items
+        return results
 
     @override
     def next_page_info(self) -> Optional[PageInfo]:
         last_page = cast("int | None", self._options.params.get("page")) or 1
 
+        total_pages = None
+        if self.pagination is not None:
+            if self.pagination.total_count is not None:
+                total_pages = self.pagination.total_count
+        if total_pages is not None and last_page >= total_pages:
+            return None
+
         return PageInfo(params={"page": last_page + 1})
diff --git a/src/docstrange/resources/extract/results.py b/src/docstrange/resources/extract/results.py
@@ -16,10 +16,10 @@
     async_to_raw_response_wrapper,
     async_to_streamed_response_wrapper,
 )
-from ..._base_client import make_request_options
+from ...pagination import SyncPageNumberPagination, AsyncPageNumberPagination
+from ..._base_client import AsyncPaginator, make_request_options
 from ...types.extract import result_list_params, result_retrieve_params
 from ...types.extract_response import ExtractResponse
-from ...types.extract.extraction_list_response import ExtractionListResponse
 
 __all__ = ["ResultsResource", "AsyncResultsResource"]
 
@@ -100,7 +100,7 @@ def list(
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
-    ) -> ExtractionListResponse:
+    ) -> SyncPageNumberPagination[ExtractResponse]:
         """
         List all extraction jobs for the authenticated user (paginated).
 
@@ -113,8 +113,9 @@ def list(
 
           timeout: Override the client-level default timeout for this request, in seconds
         """
-        return self._get(
+        return self._get_api_list(
             "/api/v1/extract/results",
+            page=SyncPageNumberPagination[ExtractResponse],
             options=make_request_options(
                 extra_headers=extra_headers,
                 extra_query=extra_query,
@@ -130,7 +131,7 @@ def list(
                     result_list_params.ResultListParams,
                 ),
             ),
-            cast_to=ExtractionListResponse,
+            model=ExtractResponse,
         )
 
 
@@ -196,7 +197,7 @@ async def retrieve(
             cast_to=ExtractResponse,
         )
 
-    async def list(
+    def list(
         self,
         *,
         page: int | Omit = omit,
@@ -210,7 +211,7 @@ async def list(
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
-    ) -> ExtractionListResponse:
+    ) -> AsyncPaginator[ExtractResponse, AsyncPageNumberPagination[ExtractResponse]]:
         """
         List all extraction jobs for the authenticated user (paginated).
 
@@ -223,14 +224,15 @@ async def list(
 
           timeout: Override the client-level default timeout for this request, in seconds
         """
-        return await self._get(
+        return self._get_api_list(
             "/api/v1/extract/results",
+            page=AsyncPageNumberPagination[ExtractResponse],
             options=make_request_options(
                 extra_headers=extra_headers,
                 extra_query=extra_query,
                 extra_body=extra_body,
                 timeout=timeout,
-                query=await async_maybe_transform(
+                query=maybe_transform(
                     {
                         "page": page,
                         "page_size": page_size,
@@ -240,7 +242,7 @@ async def list(
                     result_list_params.ResultListParams,
                 ),
             ),
-            cast_to=ExtractionListResponse,
+            model=ExtractResponse,
         )
 
 
diff --git a/tests/api_resources/extract/test_results.py b/tests/api_resources/extract/test_results.py
@@ -10,7 +10,7 @@
 from docstrange import Docstrange, AsyncDocstrange
 from tests.utils import assert_matches_type
 from docstrange.types import ExtractResponse
-from docstrange.types.extract import ExtractionListResponse
+from docstrange.pagination import SyncPageNumberPagination, AsyncPageNumberPagination
 
 base_url = os.environ.get("TEST_API_BASE_URL", "http://127.0.0.1:4010")
 
@@ -73,7 +73,7 @@ def test_path_params_retrieve(self, client: Docstrange) -> None:
     @parametrize
     def test_method_list(self, client: Docstrange) -> None:
         result = client.extract.results.list()
-        assert_matches_type(ExtractionListResponse, result, path=["response"])
+        assert_matches_type(SyncPageNumberPagination[ExtractResponse], result, path=["response"])
 
     @pytest.mark.skip(reason="Prism tests are disabled")
     @parametrize
@@ -84,7 +84,7 @@ def test_method_list_with_all_params(self, client: Docstrange) -> None:
             sort_by="created_at",
             sort_order="asc",
         )
-        assert_matches_type(ExtractionListResponse, result, path=["response"])
+        assert_matches_type(SyncPageNumberPagination[ExtractResponse], result, path=["response"])
 
     @pytest.mark.skip(reason="Prism tests are disabled")
     @parametrize
@@ -94,7 +94,7 @@ def test_raw_response_list(self, client: Docstrange) -> None:
         assert response.is_closed is True
         assert response.http_request.headers.get("X-Stainless-Lang") == "python"
         result = response.parse()
-        assert_matches_type(ExtractionListResponse, result, path=["response"])
+        assert_matches_type(SyncPageNumberPagination[ExtractResponse], result, path=["response"])
 
     @pytest.mark.skip(reason="Prism tests are disabled")
     @parametrize
@@ -104,7 +104,7 @@ def test_streaming_response_list(self, client: Docstrange) -> None:
             assert response.http_request.headers.get("X-Stainless-Lang") == "python"
 
             result = response.parse()
-            assert_matches_type(ExtractionListResponse, result, path=["response"])
+            assert_matches_type(SyncPageNumberPagination[ExtractResponse], result, path=["response"])
 
         assert cast(Any, response.is_closed) is True
 
@@ -169,7 +169,7 @@ async def test_path_params_retrieve(self, async_client: AsyncDocstrange) -> None
     @parametrize
     async def test_method_list(self, async_client: AsyncDocstrange) -> None:
         result = await async_client.extract.results.list()
-        assert_matches_type(ExtractionListResponse, result, path=["response"])
+        assert_matches_type(AsyncPageNumberPagination[ExtractResponse], result, path=["response"])
 
     @pytest.mark.skip(reason="Prism tests are disabled")
     @parametrize
@@ -180,7 +180,7 @@ async def test_method_list_with_all_params(self, async_client: AsyncDocstrange)
             sort_by="created_at",
             sort_order="asc",
         )
-        assert_matches_type(ExtractionListResponse, result, path=["response"])
+        assert_matches_type(AsyncPageNumberPagination[ExtractResponse], result, path=["response"])
 
     @pytest.mark.skip(reason="Prism tests are disabled")
     @parametrize
@@ -190,7 +190,7 @@ async def test_raw_response_list(self, async_client: AsyncDocstrange) -> None:
         assert response.is_closed is True
         assert response.http_request.headers.get("X-Stainless-Lang") == "python"
         result = await response.parse()
-        assert_matches_type(ExtractionListResponse, result, path=["response"])
+        assert_matches_type(AsyncPageNumberPagination[ExtractResponse], result, path=["response"])
 
     @pytest.mark.skip(reason="Prism tests are disabled")
     @parametrize
@@ -200,6 +200,6 @@ async def test_streaming_response_list(self, async_client: AsyncDocstrange) -> N
             assert response.http_request.headers.get("X-Stainless-Lang") == "python"
 
             result = await response.parse()
-            assert_matches_type(ExtractionListResponse, result, path=["response"])
+            assert_matches_type(AsyncPageNumberPagination[ExtractResponse], result, path=["response"])
 
         assert cast(Any, response.is_closed) is True
