[codex] add paginated controlplane list responses

README.md

@@ -31,6 +31,49 @@ When running Blaxel SDK from a remote server that is not Blaxel-hosted, we recom
 
 ## Usage
 
+### Paginated list responses
+
+Control plane list methods return one page at a time. The return value behaves like a list for the current page and also exposes pagination helpers:
+
+```python
+from blaxel.core import SandboxInstance
+
+page = await SandboxInstance.list(limit=50)
+
+for sandbox in page.data:
+    print(sandbox.metadata.name)
+
+if page.has_more:
+    next_page = await page.next_page()
+    print(next_page.next_cursor)
+```
+
+Use `auto_paging_iter()` only when you explicitly want the SDK to walk every page for you:
+
+```python
+page = await SandboxInstance.list(limit=50)
+
+async for sandbox in page.auto_paging_iter():
+    print(sandbox.metadata.name)
+```
+
+The same shape is used by `DriveInstance.list()`, `VolumeInstance.list()`, and job execution listing. Sync APIs expose the same fields, with a synchronous `next_page()`:
+
+```python
+from blaxel.core import SyncDriveInstance
+
+page = SyncDriveInstance.list(limit=50)
+
+while True:
+    for drive in page.data:
+        print(drive.name)
+
+    if not page.has_more:
+        break
+
+    page = page.next_page()
+```
+
 ### Sandboxes
 
 Sandboxes are secure, instant-launching compute environments that scale to zero after inactivity and resume in under 25ms.
@@ -250,8 +293,10 @@ async def main():
         ]
     })
 
-    # List volumes
-    volumes = await VolumeInstance.list()
+    # List the first page of volumes
+    volumes = await VolumeInstance.list(limit=50)
+    for listed_volume in volumes.data:
+        print(listed_volume.name)
 
     # Delete volume (using class)
     await VolumeInstance.delete("my-volume")
@@ -303,8 +348,10 @@ async def main():
     except Exception as error:
         print(f"Timeout: {error}")
 
-    # List all executions
-    executions = await job.alist_executions()
+    # List one page of executions
+    executions = await job.alist_executions(limit=20)
+    for execution in executions.data:
+        print(execution.metadata.id)
 
     # Delete an execution
     await job.acancel_execution(execution_id)

src/blaxel/core/client/models/agent_list.py

@@ -3,6 +3,7 @@
 from attrs import define as _attrs_define
 from attrs import field as _attrs_field
 
+from ..pagination import split_list_response
 from ..types import UNSET, Unset
 
 if TYPE_CHECKING:
@@ -57,13 +58,14 @@ def to_dict(self) -> dict[str, Any]:
         return field_dict
 
     @classmethod
-    def from_dict(cls: type[T], src_dict: dict[str, Any]) -> T | None:
+    def from_dict(cls: type[T], src_dict: dict[str, Any] | list[Any]) -> T | None:
         from ..models.agent import Agent
         from ..models.pagination_meta import PaginationMeta
 
-        if not src_dict:
+        _data, _meta, additional_properties = split_list_response(src_dict)
+        if not _data and not additional_properties and isinstance(_meta, Unset):
             return None
-        d = src_dict.copy()
+        d = {"data": _data, "meta": _meta}
         data = []
         _data = d.pop("data", UNSET)
         for data_item_data in _data or []:
@@ -83,7 +85,7 @@ def from_dict(cls: type[T], src_dict: dict[str, Any]) -> T | None:
             meta=meta,
         )
 
-        agent_list.additional_properties = d
+        agent_list.additional_properties = additional_properties
         return agent_list
 
     @property

src/blaxel/core/client/models/drive_list.py

@@ -3,6 +3,7 @@
 from attrs import define as _attrs_define
 from attrs import field as _attrs_field
 
+from ..pagination import split_list_response
 from ..types import UNSET, Unset
 
 if TYPE_CHECKING:
@@ -57,13 +58,14 @@ def to_dict(self) -> dict[str, Any]:
         return field_dict
 
     @classmethod
-    def from_dict(cls: type[T], src_dict: dict[str, Any]) -> T | None:
+    def from_dict(cls: type[T], src_dict: dict[str, Any] | list[Any]) -> T | None:
         from ..models.drive import Drive
         from ..models.pagination_meta import PaginationMeta
 
-        if not src_dict:
+        _data, _meta, additional_properties = split_list_response(src_dict)
+        if not _data and not additional_properties and isinstance(_meta, Unset):
             return None
-        d = src_dict.copy()
+        d = {"data": _data, "meta": _meta}
         data = []
         _data = d.pop("data", UNSET)
         for data_item_data in _data or []:
@@ -83,7 +85,7 @@ def from_dict(cls: type[T], src_dict: dict[str, Any]) -> T | None:
             meta=meta,
         )
 
-        drive_list.additional_properties = d
+        drive_list.additional_properties = additional_properties
         return drive_list
 
     @property

src/blaxel/core/client/models/function_list.py

@@ -3,6 +3,7 @@
 from attrs import define as _attrs_define
 from attrs import field as _attrs_field
 
+from ..pagination import split_list_response
 from ..types import UNSET, Unset
 
 if TYPE_CHECKING:
@@ -57,13 +58,14 @@ def to_dict(self) -> dict[str, Any]:
         return field_dict
 
     @classmethod
-    def from_dict(cls: type[T], src_dict: dict[str, Any]) -> T | None:
+    def from_dict(cls: type[T], src_dict: dict[str, Any] | list[Any]) -> T | None:
         from ..models.function import Function
         from ..models.pagination_meta import PaginationMeta
 
-        if not src_dict:
+        _data, _meta, additional_properties = split_list_response(src_dict)
+        if not _data and not additional_properties and isinstance(_meta, Unset):
             return None
-        d = src_dict.copy()
+        d = {"data": _data, "meta": _meta}
         data = []
         _data = d.pop("data", UNSET)
         for data_item_data in _data or []:
@@ -83,7 +85,7 @@ def from_dict(cls: type[T], src_dict: dict[str, Any]) -> T | None:
             meta=meta,
         )
 
-        function_list.additional_properties = d
+        function_list.additional_properties = additional_properties
         return function_list
 
     @property

src/blaxel/core/client/models/job_execution_list.py

@@ -3,6 +3,7 @@
 from attrs import define as _attrs_define
 from attrs import field as _attrs_field
 
+from ..pagination import split_list_response
 from ..types import UNSET, Unset
 
 if TYPE_CHECKING:
@@ -57,13 +58,14 @@ def to_dict(self) -> dict[str, Any]:
         return field_dict
 
     @classmethod
-    def from_dict(cls: type[T], src_dict: dict[str, Any]) -> T | None:
+    def from_dict(cls: type[T], src_dict: dict[str, Any] | list[Any]) -> T | None:
         from ..models.job_execution import JobExecution
         from ..models.pagination_meta import PaginationMeta
 
-        if not src_dict:
+        _data, _meta, additional_properties = split_list_response(src_dict)
+        if not _data and not additional_properties and isinstance(_meta, Unset):
             return None
-        d = src_dict.copy()
+        d = {"data": _data, "meta": _meta}
         data = []
         _data = d.pop("data", UNSET)
         for data_item_data in _data or []:
@@ -83,7 +85,7 @@ def from_dict(cls: type[T], src_dict: dict[str, Any]) -> T | None:
             meta=meta,
         )
 
-        job_execution_list.additional_properties = d
+        job_execution_list.additional_properties = additional_properties
         return job_execution_list
 
     @property

src/blaxel/core/client/models/job_execution_task_list.py

@@ -3,6 +3,7 @@
 from attrs import define as _attrs_define
 from attrs import field as _attrs_field
 
+from ..pagination import split_list_response
 from ..types import UNSET, Unset
 
 if TYPE_CHECKING:
@@ -57,13 +58,14 @@ def to_dict(self) -> dict[str, Any]:
         return field_dict
 
     @classmethod
-    def from_dict(cls: type[T], src_dict: dict[str, Any]) -> T | None:
+    def from_dict(cls: type[T], src_dict: dict[str, Any] | list[Any]) -> T | None:
         from ..models.job_execution_task import JobExecutionTask
         from ..models.pagination_meta import PaginationMeta
 
-        if not src_dict:
+        _data, _meta, additional_properties = split_list_response(src_dict)
+        if not _data and not additional_properties and isinstance(_meta, Unset):
             return None
-        d = src_dict.copy()
+        d = {"data": _data, "meta": _meta}
         data = []
         _data = d.pop("data", UNSET)
         for data_item_data in _data or []:
@@ -83,7 +85,7 @@ def from_dict(cls: type[T], src_dict: dict[str, Any]) -> T | None:
             meta=meta,
         )
 
-        job_execution_task_list.additional_properties = d
+        job_execution_task_list.additional_properties = additional_properties
         return job_execution_task_list
 
     @property

src/blaxel/core/client/models/job_list.py

@@ -3,6 +3,7 @@
 from attrs import define as _attrs_define
 from attrs import field as _attrs_field
 
+from ..pagination import split_list_response
 from ..types import UNSET, Unset
 
 if TYPE_CHECKING:
@@ -57,13 +58,14 @@ def to_dict(self) -> dict[str, Any]:
         return field_dict
 
     @classmethod
-    def from_dict(cls: type[T], src_dict: dict[str, Any]) -> T | None:
+    def from_dict(cls: type[T], src_dict: dict[str, Any] | list[Any]) -> T | None:
         from ..models.job import Job
         from ..models.pagination_meta import PaginationMeta
 
-        if not src_dict:
+        _data, _meta, additional_properties = split_list_response(src_dict)
+        if not _data and not additional_properties and isinstance(_meta, Unset):
             return None
-        d = src_dict.copy()
+        d = {"data": _data, "meta": _meta}
         data = []
         _data = d.pop("data", UNSET)
         for data_item_data in _data or []:
@@ -83,7 +85,7 @@ def from_dict(cls: type[T], src_dict: dict[str, Any]) -> T | None:
             meta=meta,
         )
 
-        job_list.additional_properties = d
+        job_list.additional_properties = additional_properties
         return job_list
 
     @property

src/blaxel/core/client/models/model_list.py

@@ -3,6 +3,7 @@
 from attrs import define as _attrs_define
 from attrs import field as _attrs_field
 
+from ..pagination import split_list_response
 from ..types import UNSET, Unset
 
 if TYPE_CHECKING:
@@ -57,13 +58,14 @@ def to_dict(self) -> dict[str, Any]:
         return field_dict
 
     @classmethod
-    def from_dict(cls: type[T], src_dict: dict[str, Any]) -> T | None:
+    def from_dict(cls: type[T], src_dict: dict[str, Any] | list[Any]) -> T | None:
         from ..models.model import Model
         from ..models.pagination_meta import PaginationMeta
 
-        if not src_dict:
+        _data, _meta, additional_properties = split_list_response(src_dict)
+        if not _data and not additional_properties and isinstance(_meta, Unset):
             return None
-        d = src_dict.copy()
+        d = {"data": _data, "meta": _meta}
         data = []
         _data = d.pop("data", UNSET)
         for data_item_data in _data or []:
@@ -83,7 +85,7 @@ def from_dict(cls: type[T], src_dict: dict[str, Any]) -> T | None:
             meta=meta,
         )
 
-        model_list.additional_properties = d
+        model_list.additional_properties = additional_properties
         return model_list
 
     @property

src/blaxel/core/client/models/policy_list.py

@@ -3,6 +3,7 @@
 from attrs import define as _attrs_define
 from attrs import field as _attrs_field
 
+from ..pagination import split_list_response
 from ..types import UNSET, Unset
 
 if TYPE_CHECKING:
@@ -57,13 +58,14 @@ def to_dict(self) -> dict[str, Any]:
         return field_dict
 
     @classmethod
-    def from_dict(cls: type[T], src_dict: dict[str, Any]) -> T | None:
+    def from_dict(cls: type[T], src_dict: dict[str, Any] | list[Any]) -> T | None:
         from ..models.pagination_meta import PaginationMeta
         from ..models.policy import Policy
 
-        if not src_dict:
+        _data, _meta, additional_properties = split_list_response(src_dict)
+        if not _data and not additional_properties and isinstance(_meta, Unset):
             return None
-        d = src_dict.copy()
+        d = {"data": _data, "meta": _meta}
         data = []
         _data = d.pop("data", UNSET)
         for data_item_data in _data or []:
@@ -83,7 +85,7 @@ def from_dict(cls: type[T], src_dict: dict[str, Any]) -> T | None:
             meta=meta,
         )
 
-        policy_list.additional_properties = d
+        policy_list.additional_properties = additional_properties
         return policy_list
 
     @property

src/blaxel/core/client/models/sandbox_list.py

@@ -3,6 +3,7 @@
 from attrs import define as _attrs_define
 from attrs import field as _attrs_field
 
+from ..pagination import split_list_response
 from ..types import UNSET, Unset
 
 if TYPE_CHECKING:
@@ -58,13 +59,14 @@ def to_dict(self) -> dict[str, Any]:
         return field_dict
 
     @classmethod
-    def from_dict(cls: type[T], src_dict: dict[str, Any]) -> T | None:
+    def from_dict(cls: type[T], src_dict: dict[str, Any] | list[Any]) -> T | None:
         from ..models.pagination_meta import PaginationMeta
         from ..models.sandbox import Sandbox
 
-        if not src_dict:
+        _data, _meta, additional_properties = split_list_response(src_dict)
+        if not _data and not additional_properties and isinstance(_meta, Unset):
             return None
-        d = src_dict.copy()
+        d = {"data": _data, "meta": _meta}
         data = []
         _data = d.pop("data", UNSET)
         for data_item_data in _data or []:
@@ -84,7 +86,7 @@ def from_dict(cls: type[T], src_dict: dict[str, Any]) -> T | None:
             meta=meta,
         )
 
-        sandbox_list.additional_properties = d
+        sandbox_list.additional_properties = additional_properties
         return sandbox_list
 
     @property