feat(api): add pagination to the deployments endpoint

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 46
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-e98d46c55826cdf541a9ee0df04ce92806ac6d4d92957ae79f897270b7d85b23.yml
-openapi_spec_hash: 8a1af54fc0a4417165b8a52e6354b685
-config_hash: 043ddc54629c6d8b889123770cb4769f
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-33f1feaba7bde46bfa36d2fefb5c3bc9512967945bccf78045ad3f64aafc4eb0.yml
+openapi_spec_hash: 52a448889d41216d1ca30e8a57115b14
+config_hash: 1f28d5c3c063f418ebd2799df1e4e781

README.md

@@ -115,6 +115,79 @@ 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 Kernel 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 kernel import Kernel
+
+client = Kernel()
+
+all_deployments = []
+# Automatically fetches more pages as needed.
+for deployment in client.deployments.list(
+    app_name="YOUR_APP",
+    limit=2,
+):
+    # Do something with deployment here
+    all_deployments.append(deployment)
+print(all_deployments)
+```
+
+Or, asynchronously:
+
+```python
+import asyncio
+from kernel import AsyncKernel
+
+client = AsyncKernel()
+
+
+async def main() -> None:
+    all_deployments = []
+    # Iterate through items across all pages, issuing requests as needed.
+    async for deployment in client.deployments.list(
+        app_name="YOUR_APP",
+        limit=2,
+    ):
+        all_deployments.append(deployment)
+    print(all_deployments)
+
+
+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.deployments.list(
+    app_name="YOUR_APP",
+    limit=2,
+)
+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.items)}")
+
+# Remove `await` for non-async usage.
+```
+
+Or just work directly with the returned data:
+
+```python
+first_page = await client.deployments.list(
+    app_name="YOUR_APP",
+    limit=2,
+)
+for deployment in first_page.items:
+    print(deployment.id)
+
+# Remove `await` for non-async usage.
+```
+
 ## Nested params
 
 Nested parameters are dictionaries, typed using `TypedDict`, for example:

api.md

@@ -22,7 +22,7 @@ Methods:
 
 - <code title="post /deployments">client.deployments.<a href="./src/kernel/resources/deployments.py">create</a>(\*\*<a href="src/kernel/types/deployment_create_params.py">params</a>) -> <a href="./src/kernel/types/deployment_create_response.py">DeploymentCreateResponse</a></code>
 - <code title="get /deployments/{id}">client.deployments.<a href="./src/kernel/resources/deployments.py">retrieve</a>(id) -> <a href="./src/kernel/types/deployment_retrieve_response.py">DeploymentRetrieveResponse</a></code>
-- <code title="get /deployments">client.deployments.<a href="./src/kernel/resources/deployments.py">list</a>(\*\*<a href="src/kernel/types/deployment_list_params.py">params</a>) -> <a href="./src/kernel/types/deployment_list_response.py">DeploymentListResponse</a></code>
+- <code title="get /deployments">client.deployments.<a href="./src/kernel/resources/deployments.py">list</a>(\*\*<a href="src/kernel/types/deployment_list_params.py">params</a>) -> <a href="./src/kernel/types/deployment_list_response.py">SyncOffsetPagination[DeploymentListResponse]</a></code>
 - <code title="get /deployments/{id}/events">client.deployments.<a href="./src/kernel/resources/deployments.py">follow</a>(id, \*\*<a href="src/kernel/types/deployment_follow_params.py">params</a>) -> <a href="./src/kernel/types/deployment_follow_response.py">DeploymentFollowResponse</a></code>
 
 # Apps

src/kernel/pagination.py

@@ -0,0 +1,78 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import Any, List, Type, Generic, Mapping, TypeVar, Optional, cast
+from typing_extensions import override
+
+from httpx import Response
+
+from ._utils import is_mapping
+from ._models import BaseModel
+from ._base_client import BasePage, PageInfo, BaseSyncPage, BaseAsyncPage
+
+__all__ = ["SyncOffsetPagination", "AsyncOffsetPagination"]
+
+_BaseModelT = TypeVar("_BaseModelT", bound=BaseModel)
+
+_T = TypeVar("_T")
+
+
+class SyncOffsetPagination(BaseSyncPage[_T], BasePage[_T], Generic[_T]):
+    items: List[_T]
+
+    @override
+    def _get_page_items(self) -> List[_T]:
+        items = self.items
+        if not items:
+            return []
+        return items
+
+    @override
+    def next_page_info(self) -> Optional[PageInfo]:
+        offset = self._options.params.get("offset") or 0
+        if not isinstance(offset, int):
+            raise ValueError(f'Expected "offset" param to be an integer but got {offset}')
+
+        length = len(self._get_page_items())
+        current_count = offset + length
+
+        return PageInfo(params={"offset": current_count})
+
+    @classmethod
+    def build(cls: Type[_BaseModelT], *, response: Response, data: object) -> _BaseModelT:  # noqa: ARG003
+        return cls.construct(
+            None,
+            **{
+                **(cast(Mapping[str, Any], data) if is_mapping(data) else {"items": data}),
+            },
+        )
+
+
+class AsyncOffsetPagination(BaseAsyncPage[_T], BasePage[_T], Generic[_T]):
+    items: List[_T]
+
+    @override
+    def _get_page_items(self) -> List[_T]:
+        items = self.items
+        if not items:
+            return []
+        return items
+
+    @override
+    def next_page_info(self) -> Optional[PageInfo]:
+        offset = self._options.params.get("offset") or 0
+        if not isinstance(offset, int):
+            raise ValueError(f'Expected "offset" param to be an integer but got {offset}')
+
+        length = len(self._get_page_items())
+        current_count = offset + length
+
+        return PageInfo(params={"offset": current_count})
+
+    @classmethod
+    def build(cls: Type[_BaseModelT], *, response: Response, data: object) -> _BaseModelT:  # noqa: ARG003
+        return cls.construct(
+            None,
+            **{
+                **(cast(Mapping[str, Any], data) if is_mapping(data) else {"items": data}),
+            },
+        )

src/kernel/resources/deployments.py

@@ -19,7 +19,8 @@
     async_to_streamed_response_wrapper,
 )
 from .._streaming import Stream, AsyncStream
-from .._base_client import make_request_options
+from ..pagination import SyncOffsetPagination, AsyncOffsetPagination
+from .._base_client import AsyncPaginator, make_request_options
 from ..types.deployment_list_response import DeploymentListResponse
 from ..types.deployment_create_response import DeploymentCreateResponse
 from ..types.deployment_follow_response import DeploymentFollowResponse
@@ -150,21 +151,27 @@ def retrieve(
     def list(
         self,
         *,
-        app_name: str | NotGiven = NOT_GIVEN,
+        app_name: str,
+        limit: int | NotGiven = NOT_GIVEN,
+        offset: int | NotGiven = NOT_GIVEN,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
-    ) -> DeploymentListResponse:
+    ) -> SyncOffsetPagination[DeploymentListResponse]:
         """List deployments.
 
         Optionally filter by application name.
 
         Args:
           app_name: Filter results by application name.
 
+          limit: Limit the number of deployments to return.
+
+          offset: Offset the number of deployments to return.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -173,16 +180,24 @@ def list(
 
           timeout: Override the client-level default timeout for this request, in seconds
         """
-        return self._get(
+        return self._get_api_list(
             "/deployments",
+            page=SyncOffsetPagination[DeploymentListResponse],
             options=make_request_options(
                 extra_headers=extra_headers,
                 extra_query=extra_query,
                 extra_body=extra_body,
                 timeout=timeout,
-                query=maybe_transform({"app_name": app_name}, deployment_list_params.DeploymentListParams),
+                query=maybe_transform(
+                    {
+                        "app_name": app_name,
+                        "limit": limit,
+                        "offset": offset,
+                    },
+                    deployment_list_params.DeploymentListParams,
+                ),
             ),
-            cast_to=DeploymentListResponse,
+            model=DeploymentListResponse,
         )
 
     def follow(
@@ -352,24 +367,30 @@ async def retrieve(
             cast_to=DeploymentRetrieveResponse,
         )
 
-    async def list(
+    def list(
         self,
         *,
-        app_name: str | NotGiven = NOT_GIVEN,
+        app_name: str,
+        limit: int | NotGiven = NOT_GIVEN,
+        offset: int | NotGiven = NOT_GIVEN,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
-    ) -> DeploymentListResponse:
+    ) -> AsyncPaginator[DeploymentListResponse, AsyncOffsetPagination[DeploymentListResponse]]:
         """List deployments.
 
         Optionally filter by application name.
 
         Args:
           app_name: Filter results by application name.
 
+          limit: Limit the number of deployments to return.
+
+          offset: Offset the number of deployments to return.
+
           extra_headers: Send extra headers
 
           extra_query: Add additional query parameters to the request
@@ -378,16 +399,24 @@ async def list(
 
           timeout: Override the client-level default timeout for this request, in seconds
         """
-        return await self._get(
+        return self._get_api_list(
             "/deployments",
+            page=AsyncOffsetPagination[DeploymentListResponse],
             options=make_request_options(
                 extra_headers=extra_headers,
                 extra_query=extra_query,
                 extra_body=extra_body,
                 timeout=timeout,
-                query=await async_maybe_transform({"app_name": app_name}, deployment_list_params.DeploymentListParams),
+                query=maybe_transform(
+                    {
+                        "app_name": app_name,
+                        "limit": limit,
+                        "offset": offset,
+                    },
+                    deployment_list_params.DeploymentListParams,
+                ),
             ),
-            cast_to=DeploymentListResponse,
+            model=DeploymentListResponse,
         )
 
     async def follow(

src/kernel/types/deployment_list_params.py

@@ -2,11 +2,17 @@
 
 from __future__ import annotations
 
-from typing_extensions import TypedDict
+from typing_extensions import Required, TypedDict
 
 __all__ = ["DeploymentListParams"]
 
 
 class DeploymentListParams(TypedDict, total=False):
-    app_name: str
+    app_name: Required[str]
     """Filter results by application name."""
+
+    limit: int
+    """Limit the number of deployments to return."""
+
+    offset: int
+    """Offset the number of deployments to return."""

src/kernel/types/deployment_list_response.py

@@ -1,15 +1,15 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-from typing import Dict, List, Optional
+from typing import Dict, Optional
 from datetime import datetime
-from typing_extensions import Literal, TypeAlias
+from typing_extensions import Literal
 
 from .._models import BaseModel
 
-__all__ = ["DeploymentListResponse", "DeploymentListResponseItem"]
+__all__ = ["DeploymentListResponse"]
 
 
-class DeploymentListResponseItem(BaseModel):
+class DeploymentListResponse(BaseModel):
     id: str
     """Unique identifier for the deployment"""
 
@@ -33,6 +33,3 @@ class DeploymentListResponseItem(BaseModel):
 
     updated_at: Optional[datetime] = None
     """Timestamp when the deployment was last updated"""
-
-
-DeploymentListResponse: TypeAlias = List[DeploymentListResponseItem]