fix(python-sdk): correct Sandbox.list() docstring (also lists paused) (#1511)

Integration branch PR for #1500. Merges the docstring fix into `main`.

Once #1500 is merged into `python-sdk-list-docstring-base`, this PR will
carry those changes into `main`.

---------

Co-authored-by: Leinux <tristone13th@outlook.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

.changeset/sandbox-list-docstring.md

@@ -0,0 +1,6 @@
+---
+"@e2b/python-sdk": patch
+"e2b": patch
+---
+
+Correct `Sandbox.list()` documentation across both SDKs: it returns a paginator (`SandboxPaginator` / `AsyncSandboxPaginator`), not a list, and by default the server returns sandboxes in both `running` and `paused` states. The docstrings now describe the return type accurately and show how to iterate pages via `paginator.next_items()` / `await paginator.nextItems()` while `paginator.has_next` / `paginator.hasNext` is true. No behavior change.

packages/js-sdk/src/sandbox/index.ts

@@ -227,11 +227,18 @@ export class Sandbox extends SandboxApi {
   }
 
   /**
-   * List all sandboxes.
+   * List sandboxes.
    *
-   * @param opts connection options.
+   * By default (no `query.state` set in `opts`), returns sandboxes in both
+   * `running` and `paused` states. To filter by state, pass
+   * `opts.query.state = [...]`.
+   *
+   * @param opts connection options, plus optional `query` to filter by
+   *   metadata / state and `limit` / `nextToken` for pagination.
    *
-   * @returns paginator for listing sandboxes.
+   * @returns a {@link SandboxPaginator} that yields pages of sandboxes
+   *   (running and paused by default). Iterate pages via
+   *   `await paginator.nextItems()` while `paginator.hasNext` is `true`.
    */
   static list(opts?: SandboxListOpts): SandboxPaginator {
     return new SandboxPaginator(opts)

packages/python-sdk/e2b/sandbox_async/sandbox_api.py

@@ -63,13 +63,16 @@ def list(
         **opts: Unpack[ApiParams],
     ) -> AsyncSandboxPaginator:
         """
-        List all running sandboxes.
+        List sandboxes.
 
-        :param query: Filter the list of sandboxes by metadata or state, e.g. `SandboxListQuery(metadata={"key": "value"})` or `SandboxListQuery(state=[SandboxState.RUNNING])`
+        By default (no `query.state` set), returns sandboxes in both `running`
+        and `paused` states. To filter by state, pass `query=SandboxQuery(state=[...])`.
+
+        :param query: Filter the list of sandboxes by metadata or state, e.g. `SandboxQuery(metadata={"key": "value"})` or `SandboxQuery(state=[SandboxState.RUNNING])`
         :param limit: Maximum number of sandboxes to return per page
         :param next_token: Token for pagination
 
-        :return: List of running sandboxes
+        :return: An `AsyncSandboxPaginator` that yields pages of sandboxes (running and paused by default). Iterate pages via `await paginator.next_items()` while `paginator.has_next` is True.
         """
         return AsyncSandboxPaginator(
             query=query,

packages/python-sdk/e2b/sandbox_sync/sandbox_api.py

@@ -62,13 +62,16 @@ def list(
         **opts: Unpack[ApiParams],
     ) -> SandboxPaginator:
         """
-        List all running sandboxes.
+        List sandboxes.
 
-        :param query: Filter the list of sandboxes by metadata or state, e.g. `SandboxListQuery(metadata={"key": "value"})` or `SandboxListQuery(state=[SandboxState.RUNNING])`
+        By default (no `query.state` set), returns sandboxes in both `running`
+        and `paused` states. To filter by state, pass `query=SandboxQuery(state=[...])`.
+
+        :param query: Filter the list of sandboxes by metadata or state, e.g. `SandboxQuery(metadata={"key": "value"})` or `SandboxQuery(state=[SandboxState.RUNNING])`
         :param limit: Maximum number of sandboxes to return per page
         :param next_token: Token for pagination
 
-        :return: List of running sandboxes
+        :return: A `SandboxPaginator` that yields pages of sandboxes (running and paused by default). Iterate pages via `paginator.next_items()` while `paginator.has_next` is True.
         """
         return SandboxPaginator(
             query=query,