Open-source, secure environment with real-world tools for enterprise-grade agents.
Python agentaiai-agentai-agentscode-interpretercopilotdevelopmentdevtoolsgptgpt-4javascriptllmnextjsopenaipythonreactsoftwaretypescript
Introduce generic paginator base class for JS and Python SDKs (#1491)
Lukáš Huvarbb45f185f113
diff --git a/.changeset/generic-paginator.md b/.changeset/generic-paginator.mdnew file mode 100644index 000000000..d84e3ddd2--- /dev/null+++ b/.changeset/generic-paginator.md@@ -0,0 +1,6 @@+---+"@e2b/python-sdk": patch+"e2b": patch+---++Introduce a generic, reusable paginator base class and migrate the sandbox and snapshot list paginators onto it. The base owns the shared cursor-based pagination state (`hasNext`/`has_next`, `nextToken`/`next_token`, and reading the `x-next-token` header) while each concrete paginator implements `nextItems`/`next_items` to fetch its own page, so future list endpoints can add pagination by subclassing it without reimplementing the bookkeeping. No public API changes.diff --git a/packages/js-sdk/src/paginator.ts b/packages/js-sdk/src/paginator.tsnew file mode 100644index 000000000..051655a76--- /dev/null+++ b/packages/js-sdk/src/paginator.ts@@ -0,0 +1,77 @@+import type { ConnectionOpts } from './connectionConfig'++/**+ * Generic, reusable paginator for cursor-based list endpoints.+ *+ * The base owns the shared pagination state — `hasNext`, `nextToken`, and the+ * reading of the `x-next-token` response header (via {@link Paginator.updatePagination}).+ * Each concrete paginator implements {@link Paginator.nextItems} to do the+ * actual fetching for its endpoint, so any model can expose pagination by+ * subclassing this without reimplementing the bookkeeping.+ *+ * The optional `O` type parameter is the per-call options type accepted by+ * `nextItems` (e.g. connection options for a given API).+ *+ * @example+ * ```ts+ * const paginator = Sandbox.list()+ * while (paginator.hasNext) {+ * const items = await paginator.nextItems()+ * console.log(items)+ * }+ * ```+ */+export abstract class Paginator<T, O extends ConnectionOpts = ConnectionOpts> {+ protected readonly opts?: O+ protected readonly limit?: number++ private _hasNext: boolean+ private _nextToken?: string++ constructor(opts?: O, limit?: number, nextToken?: string) {+ this.opts = opts+ this.limit = limit++ this._hasNext = true+ this._nextToken = nextToken+ }++ /**+ * Returns true if there are more items to fetch.+ */+ get hasNext(): boolean {+ return this._hasNext+ }++ /**+ * Returns the next token to use for pagination.+ */+ get nextToken(): string | undefined {+ return this._nextToken+ }++ /**+ * Update the pagination state from a response, reading the `x-next-token`+ * header. Concrete paginators call this from {@link Paginator.nextItems}+ * after fetching a page.+ */+ protected updatePagination(response: Response) {+ this._nextToken = response.headers.get('x-next-token') || undefined+ this._hasNext = !!this._nextToken+ }++ /**+ * Get the next page of items.+ *+ * @param opts per-call connection options. When provided, this call uses+ * these options (e.g. `apiKey`, `domain`, `headers`, `requestTimeoutMs`,+ * `signal`) instead of the ones the paginator was constructed with.+ * Aborting a page via `signal` does not affect subsequent {@link Paginator.nextItems}+ * calls — pass a fresh signal each call you want to be cancellable.+ *+ * @throws Error if there are no more items to fetch. Call this method only if `hasNext` is `true`.+ *+ * @returns List of items+ */+ abstract nextItems(opts?: O): Promise<T[]>+}diff --git a/packages/js-sdk/src/sandbox/sandboxApi.ts b/packages/js-sdk/src/sandbox/sandboxApi.tsindex 6211e10ea..4cedebcfa 100644--- a/packages/js-sdk/src/sandbox/sandboxApi.ts+++ b/packages/js-sdk/src/sandbox/sandboxApi.ts@@ -11,6 +11,7 @@ import {SandboxNotFoundError,TemplateError,} from '../errors'+import { Paginator } from '../paginator'import { timeoutToSeconds } from '../utils'import type { Volume } from '../volume'import type { McpServer as BaseMcpServer } from './mcp'@@ -1242,56 +1243,6 @@ export class SandboxApi {}}-abstract class BasePaginator<T> {- protected readonly opts?: SandboxApiOpts- protected readonly limit?: number-- private _hasNext: boolean- private _nextToken?: string-- constructor(opts?: SandboxApiOpts, limit?: number, nextToken?: string) {- this.opts = opts- this.limit = limit-- this._hasNext = true- this._nextToken = nextToken- }-- /**- * Returns true if there are more items to fetch.- */- get hasNext(): boolean {- return this._hasNext- }-- /**- * Returns the next token to use for pagination.- */- get nextToken(): string | undefined {- return this._nextToken- }-- protected updatePagination(response: Response) {- this._nextToken = response.headers.get('x-next-token') || undefined- this._hasNext = !!this._nextToken- }-- /**- * Get the next page of items.- *- * @param opts per-call connection options. When provided, this call uses- * these options (e.g. `apiKey`, `domain`, `headers`, `requestTimeoutMs`,- * `signal`) instead of the ones the paginator was constructed with.- * Aborting a page via `signal` does not affect subsequent {@link BasePaginator.nextItems}- * calls — pass a fresh signal each call you want to be cancellable.- *- * @throws Error if there are no more items to fetch. Call this method only if `hasNext` is `true`.- *- * @returns List of items- */- abstract nextItems(opts?: SandboxApiOpts): Promise<T[]>-}-/*** Paginator for listing sandboxes.*@@ -1304,7 +1255,7 @@ abstract class BasePaginator<T> {* }* ```*/-export class SandboxPaginator extends BasePaginator<SandboxInfo> {+export class SandboxPaginator extends Paginator<SandboxInfo, SandboxApiOpts> {private query: SandboxListOpts['query']constructor(opts?: SandboxListOpts) {@@ -1382,7 +1333,7 @@ export class SandboxPaginator extends BasePaginator<SandboxInfo> {* }* ```*/-export class SnapshotPaginator extends BasePaginator<SnapshotInfo> {+export class SnapshotPaginator extends Paginator<SnapshotInfo, SandboxApiOpts> {private readonly sandboxId?: stringconstructor(opts?: SnapshotListOpts) {diff --git a/packages/js-sdk/tests/paginator.test.ts b/packages/js-sdk/tests/paginator.test.tsnew file mode 100644index 000000000..67169b6ab--- /dev/null+++ b/packages/js-sdk/tests/paginator.test.ts@@ -0,0 +1,62 @@+import { assert, expect, test } from 'vitest'++import { Paginator } from '../src/paginator'++// Build a fake HTTP Response carrying only the `x-next-token` header.+function fakeResponse(nextToken?: string): Response {+ const headers = new Headers()+ if (nextToken !== undefined) {+ headers.set('x-next-token', nextToken)+ }+ return new Response(null, { headers })+}++// Minimal concrete paginator that returns canned pages and drives the shared+// base state machine via `updatePagination`.+class FakePaginator extends Paginator<string> {+ private call = 0++ constructor(+ private readonly pages: Array<{ items: string[]; nextToken?: string }>+ ) {+ super()+ }++ async nextItems(): Promise<string[]> {+ if (!this.hasNext) {+ throw new Error('No more items to fetch')+ }++ const page = this.pages[this.call++]+ this.updatePagination(fakeResponse(page.nextToken))+ return page.items+ }+}++test('paginator exposes pagination state and advances across pages', async () => {+ const paginator = new FakePaginator([+ { items: ['a', 'b'], nextToken: 'tok-2' },+ { items: ['c'], nextToken: undefined },+ ])++ assert.isTrue(paginator.hasNext)+ assert.isUndefined(paginator.nextToken)++ const first = await paginator.nextItems()+ assert.deepEqual(first, ['a', 'b'])+ assert.isTrue(paginator.hasNext)+ assert.equal(paginator.nextToken, 'tok-2')++ const second = await paginator.nextItems()+ assert.deepEqual(second, ['c'])+ assert.isFalse(paginator.hasNext)+ assert.isUndefined(paginator.nextToken)+})++test('paginator throws once exhausted', async () => {+ const paginator = new FakePaginator([{ items: [], nextToken: undefined }])+ await paginator.nextItems()++ assert.isFalse(paginator.hasNext)+ await expect(paginator.nextItems()).rejects.toThrow('No more items to fetch')+})diff --git a/packages/python-sdk/e2b/paginator.py b/packages/python-sdk/e2b/paginator.pynew file mode 100644index 000000000..a1a2e1130--- /dev/null+++ b/packages/python-sdk/e2b/paginator.py@@ -0,0 +1,52 @@+from typing import Generic, Mapping, Optional, TypeVar++from typing_extensions import Unpack++from e2b.connection_config import ApiParams++T = TypeVar("T")+OptsT = TypeVar("OptsT", bound=ApiParams)+++class PaginatorBase(Generic[T, OptsT]):+ """+ Shared pagination state for cursor-based list endpoints.++ Owns the `has_next` / `next_token` state and the reading of the+ `x-next-token` response header (via `_update_pagination`). Each concrete+ paginator implements `next_items` to do the actual fetching for its+ endpoint, so any model can expose pagination by subclassing this without+ reimplementing the bookkeeping.++ `T` is the item type returned by `next_items`; `OptsT` is the connection+ options type accepted by the paginator (an `ApiParams`-compatible TypedDict).+ """++ def __init__(+ self,+ limit: Optional[int] = None,+ next_token: Optional[str] = None,+ **opts: Unpack[OptsT],+ ):+ self._opts: OptsT = opts+ self.limit = limit+ self._has_next = True+ self._next_token = next_token++ @property+ def has_next(self) -> bool:+ """+ Returns True if there are more items to fetch.+ """+ return self._has_next++ @property+ def next_token(self) -> Optional[str]:+ """+ Returns the next token to use for pagination.+ """+ return self._next_token++ def _update_pagination(self, headers: Mapping[str, str]) -> None:+ self._next_token = headers.get("x-next-token")+ self._has_next = bool(self._next_token)diff --git a/packages/python-sdk/e2b/sandbox/sandbox_api.py b/packages/python-sdk/e2b/sandbox/sandbox_api.pyindex 4799e0df1..d0982864f 100644--- a/packages/python-sdk/e2b/sandbox/sandbox_api.py+++ b/packages/python-sdk/e2b/sandbox/sandbox_api.py@@ -48,6 +48,7 @@ from e2b.api.client.types import Unsetfrom e2b.connection_config import ApiParamsfrom e2b.sandbox.mcp import McpServer as BaseMcpServerfrom e2b.sandbox.network import ALL_TRAFFIC+from e2b.paginator import PaginatorBaseclass GitHubMcpServerConfig(TypedDict):@@ -599,34 +600,7 @@ class SnapshotInfo:"""Full names of the snapshot template including team namespace and tag (e.g. team-slug/my-snapshot:v2)."""-class PaginatorBase:- def __init__(- self,- limit: Optional[int] = None,- next_token: Optional[str] = None,- **opts: Unpack[ApiParams],- ):- self._opts: ApiParams = opts- self.limit = limit- self._has_next = True- self._next_token = next_token-- @property- def has_next(self) -> bool:- """- Returns True if there are more items to fetch.- """- return self._has_next-- @property- def next_token(self) -> Optional[str]:- """- Returns the next token to use for pagination.- """- return self._next_token---class SnapshotPaginatorBase(PaginatorBase):+class SnapshotPaginatorBase(PaginatorBase[SnapshotInfo, ApiParams]):def __init__(self,sandbox_id: Optional[str] = None,@@ -638,7 +612,7 @@ class SnapshotPaginatorBase(PaginatorBase):self.sandbox_id = sandbox_id-class SandboxPaginatorBase(PaginatorBase):+class SandboxPaginatorBase(PaginatorBase[SandboxInfo, ApiParams]):def __init__(self,query: Optional[SandboxQuery] = None,diff --git a/packages/python-sdk/e2b/sandbox_async/paginator.py b/packages/python-sdk/e2b/sandbox_async/paginator.pyindex 451ff7e55..269248c5e 100644--- a/packages/python-sdk/e2b/sandbox_async/paginator.py+++ b/packages/python-sdk/e2b/sandbox_async/paginator.py@@ -70,8 +70,7 @@ class AsyncSandboxPaginator(SandboxPaginatorBase):if res.status_code >= 300:raise handle_api_exception(res)- self._next_token = res.headers.get("x-next-token")- self._has_next = bool(self._next_token)+ self._update_pagination(res.headers)if res.parsed is None:return []@@ -124,8 +123,7 @@ class AsyncSnapshotPaginator(SnapshotPaginatorBase):if res.status_code >= 300:raise handle_api_exception(res)- self._next_token = res.headers.get("x-next-token")- self._has_next = bool(self._next_token)+ self._update_pagination(res.headers)if res.parsed is None:return []diff --git a/packages/python-sdk/e2b/sandbox_sync/paginator.py b/packages/python-sdk/e2b/sandbox_sync/paginator.pyindex 464de6644..9f0d4bf22 100644--- a/packages/python-sdk/e2b/sandbox_sync/paginator.py+++ b/packages/python-sdk/e2b/sandbox_sync/paginator.py@@ -70,8 +70,7 @@ class SandboxPaginator(SandboxPaginatorBase):if res.status_code >= 300:raise handle_api_exception(res)- self._next_token = res.headers.get("x-next-token")- self._has_next = bool(self._next_token)+ self._update_pagination(res.headers)if res.parsed is None:return []@@ -124,8 +123,7 @@ class SnapshotPaginator(SnapshotPaginatorBase):if res.status_code >= 300:raise handle_api_exception(res)- self._next_token = res.headers.get("x-next-token")- self._has_next = bool(self._next_token)+ self._update_pagination(res.headers)if res.parsed is None:return []diff --git a/packages/python-sdk/tests/test_paginator.py b/packages/python-sdk/tests/test_paginator.pynew file mode 100644index 000000000..e667f8eb0--- /dev/null+++ b/packages/python-sdk/tests/test_paginator.py@@ -0,0 +1,53 @@+import pytest++from e2b.connection_config import ApiParams+from e2b.paginator import PaginatorBase+++class FakePaginator(PaginatorBase[str, ApiParams]):+ """Minimal paginator that returns canned pages and drives the shared state."""++ def __init__(self, pages):+ super().__init__()+ self._pages = pages+ self._call = 0++ def next_items(self):+ if not self.has_next:+ raise Exception("No more items to fetch")++ items, headers = self._pages[self._call]+ self._call += 1+ self._update_pagination(headers)+ return items+++def test_paginator_exposes_state_and_advances():+ paginator = FakePaginator(+ [+ (["a", "b"], {"x-next-token": "tok-2"}),+ (["c"], {}),+ ]+ )++ assert paginator.has_next is True+ assert paginator.next_token is None++ first = paginator.next_items()+ assert first == ["a", "b"]+ assert paginator.has_next is True+ assert paginator.next_token == "tok-2"++ second = paginator.next_items()+ assert second == ["c"]+ assert paginator.has_next is False+ assert paginator.next_token is None+++def test_paginator_raises_once_exhausted():+ paginator = FakePaginator([([], {})])+ paginator.next_items()++ assert paginator.has_next is False+ with pytest.raises(Exception, match="No more items to fetch"):+ paginator.next_items()