zipbox 0.1.7__tar.gz → 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (29) hide show
  1. {zipbox-0.1.7 → zipbox-0.2.0}/PKG-INFO +33 -18
  2. {zipbox-0.1.7 → zipbox-0.2.0}/README.md +32 -17
  3. {zipbox-0.1.7 → zipbox-0.2.0}/pyproject.toml +1 -1
  4. {zipbox-0.1.7 → zipbox-0.2.0}/src/zipbox/_async_client.py +44 -14
  5. {zipbox-0.1.7 → zipbox-0.2.0}/src/zipbox/_client.py +44 -14
  6. {zipbox-0.1.7 → zipbox-0.2.0}/src/zipbox/_core.py +313 -60
  7. {zipbox-0.1.7 → zipbox-0.2.0}/src/zipbox/_effects.py +31 -1
  8. {zipbox-0.1.7 → zipbox-0.2.0}/src/zipbox/_models.py +5 -5
  9. {zipbox-0.1.7 → zipbox-0.2.0}/src/zipbox/_transport.py +38 -0
  10. zipbox-0.2.0/tests/test_claim_stream.py +161 -0
  11. zipbox-0.2.0/tests/test_closed_connection.py +150 -0
  12. {zipbox-0.1.7 → zipbox-0.2.0}/tests/test_conformance.py +9 -1
  13. {zipbox-0.1.7 → zipbox-0.2.0}/tests/test_fork.py +7 -2
  14. zipbox-0.2.0/tests/test_preconnect.py +150 -0
  15. {zipbox-0.1.7 → zipbox-0.2.0}/tests/test_pty.py +3 -2
  16. {zipbox-0.1.7 → zipbox-0.2.0}/tests/test_streams.py +6 -0
  17. {zipbox-0.1.7 → zipbox-0.2.0}/tests/test_tailscale.py +1 -1
  18. {zipbox-0.1.7 → zipbox-0.2.0}/tests/test_units.py +105 -8
  19. {zipbox-0.1.7 → zipbox-0.2.0}/uv.lock +1 -1
  20. {zipbox-0.1.7 → zipbox-0.2.0}/.gitignore +0 -0
  21. {zipbox-0.1.7 → zipbox-0.2.0}/src/zipbox/__init__.py +0 -0
  22. {zipbox-0.1.7 → zipbox-0.2.0}/src/zipbox/_backoff.py +0 -0
  23. {zipbox-0.1.7 → zipbox-0.2.0}/src/zipbox/_envelope.py +0 -0
  24. {zipbox-0.1.7 → zipbox-0.2.0}/src/zipbox/_errors.py +0 -0
  25. {zipbox-0.1.7 → zipbox-0.2.0}/src/zipbox/_pty.py +0 -0
  26. {zipbox-0.1.7 → zipbox-0.2.0}/src/zipbox/_sse.py +0 -0
  27. {zipbox-0.1.7 → zipbox-0.2.0}/src/zipbox/py.typed +0 -0
  28. {zipbox-0.1.7 → zipbox-0.2.0}/tests/conftest.py +0 -0
  29. {zipbox-0.1.7 → zipbox-0.2.0}/tests/mock_server.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: zipbox
3
- Version: 0.1.7
3
+ Version: 0.2.0
4
4
  Summary: Drive Zipbox boxes from Python: create, exec, files, PTY, previews.
5
5
  Project-URL: Homepage, https://zipbox.ai
6
6
  Project-URL: Documentation, https://zipbox.ai/docs/sdk-python
@@ -56,17 +56,17 @@ async with AsyncZipbox() as zb:
56
56
 
57
57
  ## What is in it
58
58
 
59
- | Area | Calls |
60
- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
61
- | Lifecycle | `zb.sandboxes.create(name=, tier=, ssh_public_key=, mailbox=, private=)`, `get_or_create(name, tier=, …)`, `list`, `get`, `wait_ready`, `start`, `stop`, `restart`, `cancel_transition`, `delete(id, archive=)`, `set_tier`; `zb.sandbox(id)` |
62
- | Fork | `zb.sandboxes.fork(source_id, name=, source_policy=, private=, tailscale_auth_key=, wait=True)` → the new box; `get_fork(child_id)` → `SandboxFork`; `box.fork(name=, source_policy=, …)`, `box.fork_status()` |
63
- | Exec | `box.exec(cmd)` → `ExecResult(id, exit_code, stdout, stderr)`; `exec_stream(cmd)`; `exec_background(cmd)` → `Command`; `run_code("python", code, cwd=)` |
64
- | Commands | `Command.get()`, `events(since=)`, `wait()`, `stdin(data)`, `close_stdin()`, `signal("TERM")`; `box.commands.list/get/handle/events/stdin/close_stdin/signal` |
65
- | Files | `box.files.read`, `read_text`, `write`, `list`, `stat`, `mkdir`, `move`, `copy`, `delete`, `upload`, `download` |
66
- | PTY | `box.pty.create(cols=, rows=, client_label=)` / `attach(session_id, …)` → `write`, `resize`, `takeover`, `on_data`, iterate, `detach`, `close`, `wait` |
67
- | Previews | `box.preview.create(port, label=)` → `Preview(url, label)`; `remove(label)` |
68
- | Other | `box.logs(since=, lines=, unit=)`, `box.ssh_info()`, `box.screenshot()`, `zb.account.balance()`, `usage()`, `whoami()` |
69
- | Tailscale | `box.tailscale.status()` → `TailscaleStatus` or `None`; `connect(auth_key)`; `disconnect()`; `box.set_private(enabled)`; `create(private=True)` |
59
+ | Area | Calls |
60
+ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
61
+ | Lifecycle | `zb.sandboxes.create(name=, tier=, ssh_public_key=, mailbox=, private=)`, `get_or_create(name, tier=, …)`, `list`, `get`, `wait_ready`, `pause`, `resume` (`stop`, `start` are aliases), `restart`, `cancel_transition`, `delete(id, archive=)`, `set_tier`; `zb.sandbox(id)` |
62
+ | Fork | `zb.sandboxes.fork(source_id, name=, source_policy=, private=, tailscale_auth_key=, wait=True)` → the new box; `get_fork(child_id)` → `SandboxFork`; `box.fork(name=, source_policy=, …)`, `box.fork_status()` |
63
+ | Exec | `box.exec(cmd)` → `ExecResult(id, exit_code, stdout, stderr)`; `exec_stream(cmd)`; `exec_background(cmd)` → `Command`; `run_code("python", code, cwd=)` |
64
+ | Commands | `Command.get()`, `events(since=)`, `wait()`, `stdin(data)`, `close_stdin()`, `signal("TERM")`; `box.commands.list/get/handle/events/stdin/close_stdin/signal` |
65
+ | Files | `box.files.read`, `read_text`, `write`, `list`, `stat`, `mkdir`, `move`, `copy`, `delete`, `upload`, `download` |
66
+ | PTY | `box.pty.create(cols=, rows=, client_label=)` / `attach(session_id, …)` → `write`, `resize`, `takeover`, `on_data`, iterate, `detach`, `close`, `wait` |
67
+ | Previews | `box.preview.create(port, label=)` → `Preview(url, label)`; `remove(label)` |
68
+ | Other | `box.logs(since=, lines=, unit=)`, `box.ssh_info()`, `box.screenshot()`, `zb.account.balance()`, `usage()`, `whoami()` |
69
+ | Tailscale | `box.tailscale.status()` → `TailscaleStatus` or `None`; `connect(auth_key)`; `disconnect()`; `box.set_private(enabled)`; `create(private=True)` |
70
70
 
71
71
  A string command runs under `bash -lc` (your PATH, nvm, pyenv); a list is spawned as argv.
72
72
  A command that exits non-zero is a result: check `exit_code`. Relative paths resolve
@@ -77,6 +77,19 @@ merely drops after the command started re-attaches from its last cursor by itsel
77
77
  started with `exec_background` keeps running with nobody attached — re-attach any time
78
78
  with `box.commands.handle(id).events(since=cursor)`.
79
79
 
80
+ ## Pause and resume
81
+
82
+ ```python
83
+ box = zb.sandboxes.pause(box.id) # returns the box paused; nothing is billed while paused
84
+ box = zb.sandboxes.resume(box.id) # returns the box ready, files and software as they were
85
+ ```
86
+
87
+ `pause` and `resume` return once the box is there: at once when the server answers with the
88
+ final state, else after waiting for it on `GET /sandbox/:id/wait`, with no deadline. A box
89
+ whose Pause was cancelled raises `conflict`. `resume` on a box still `stopping` (a Pause still
90
+ landing) waits that out, then resumes it. `stop` and `start` are aliases that send the same
91
+ requests. On a box object, `box.pause()` / `box.resume()` return the updated detail.
92
+
80
93
  ## Tailscale and private boxes
81
94
 
82
95
  ```python
@@ -117,11 +130,13 @@ A fork is a new box with the source's files, packages and settings, and a new id
117
130
  `private=True`, whatever the source's privacy. A running
118
131
  source needs `source_policy="pause_and_resume"`: it pauses for the capture (its sessions
119
132
  disconnect) and resumes right after; `"require_paused"` raises `pause_required` instead.
120
- Every wait (`create`, `get_or_create`, `wait_ready`, `fork`) reads the box's `readiness`: it keeps reading
121
- while the box is `settling`, with backoff and no deadline (a retryable failed read stays on
122
- the same ladder), returns on `ready` or, for a private box, `awaits_tailnet`, and raises on
133
+ Every wait (`create`, `get_or_create`, `wait_ready`, `resume`, `fork`) asks
134
+ `GET /sandbox/:id/wait?until=ready`, which the server answers when the box gets there; it
135
+ asks again while the box is `settling`, with no deadline (a retryable failed read waits on a
136
+ backoff ladder), returns on `ready` or, for a private box, `awaits_tailnet`, and raises on
123
137
  the rest, never retryable: paused `box_not_running`, a failed start `start_failed`, deleting
124
- or gone `conflict`. Rows carry `phase` and `allowed_actions`; a detail also carries `readiness`.
138
+ or gone `conflict`. An API older than `/wait` is polled with `GET /sandbox/:id` instead. A
139
+ `create` the server answers with the box already bound returns at once, with no wait. Rows carry `phase` and `allowed_actions`; a detail also carries `readiness`.
125
140
  One retry rule: an error is retried when its `retryable` is true.
126
141
 
127
142
  A created box's `base_url` changes once, a few minutes after create: from its boot address
@@ -159,8 +174,8 @@ machine names, and a deleted box keeps its name: reuse a fixed pool of names wit
159
174
  retry_base_delay_s=0.5, retry_max_delay_s=30.0, poll_interval_s=1.0,
160
175
  poll_max_interval_s=10.0, pty_base_delay_s=0.5, pty_max_delay_s=30.0)`. The key and URL
161
176
  default to `ZIPBOX_API_KEY` and `ZIPBOX_API_URL` (else `https://api.tribes.xyz`). A wait's
162
- readiness checks start at `poll_interval_s` and grow 1.25× per check to
163
- `poll_max_interval_s`, with jitter.
177
+ retries after a failed read, and its checks against an API older than `/wait`, start at
178
+ `poll_interval_s` and grow 1.25× per check to `poll_max_interval_s`, with jitter.
164
179
 
165
180
  Docs: [zipbox.ai/docs/sdk-python](https://zipbox.ai/docs/sdk-python) · Agent index:
166
181
  [zipbox.ai/llms.txt](https://zipbox.ai/llms.txt) · Apache-2.0.
@@ -35,17 +35,17 @@ async with AsyncZipbox() as zb:
35
35
 
36
36
  ## What is in it
37
37
 
38
- | Area | Calls |
39
- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
40
- | Lifecycle | `zb.sandboxes.create(name=, tier=, ssh_public_key=, mailbox=, private=)`, `get_or_create(name, tier=, …)`, `list`, `get`, `wait_ready`, `start`, `stop`, `restart`, `cancel_transition`, `delete(id, archive=)`, `set_tier`; `zb.sandbox(id)` |
41
- | Fork | `zb.sandboxes.fork(source_id, name=, source_policy=, private=, tailscale_auth_key=, wait=True)` → the new box; `get_fork(child_id)` → `SandboxFork`; `box.fork(name=, source_policy=, …)`, `box.fork_status()` |
42
- | Exec | `box.exec(cmd)` → `ExecResult(id, exit_code, stdout, stderr)`; `exec_stream(cmd)`; `exec_background(cmd)` → `Command`; `run_code("python", code, cwd=)` |
43
- | Commands | `Command.get()`, `events(since=)`, `wait()`, `stdin(data)`, `close_stdin()`, `signal("TERM")`; `box.commands.list/get/handle/events/stdin/close_stdin/signal` |
44
- | Files | `box.files.read`, `read_text`, `write`, `list`, `stat`, `mkdir`, `move`, `copy`, `delete`, `upload`, `download` |
45
- | PTY | `box.pty.create(cols=, rows=, client_label=)` / `attach(session_id, …)` → `write`, `resize`, `takeover`, `on_data`, iterate, `detach`, `close`, `wait` |
46
- | Previews | `box.preview.create(port, label=)` → `Preview(url, label)`; `remove(label)` |
47
- | Other | `box.logs(since=, lines=, unit=)`, `box.ssh_info()`, `box.screenshot()`, `zb.account.balance()`, `usage()`, `whoami()` |
48
- | Tailscale | `box.tailscale.status()` → `TailscaleStatus` or `None`; `connect(auth_key)`; `disconnect()`; `box.set_private(enabled)`; `create(private=True)` |
38
+ | Area | Calls |
39
+ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
40
+ | Lifecycle | `zb.sandboxes.create(name=, tier=, ssh_public_key=, mailbox=, private=)`, `get_or_create(name, tier=, …)`, `list`, `get`, `wait_ready`, `pause`, `resume` (`stop`, `start` are aliases), `restart`, `cancel_transition`, `delete(id, archive=)`, `set_tier`; `zb.sandbox(id)` |
41
+ | Fork | `zb.sandboxes.fork(source_id, name=, source_policy=, private=, tailscale_auth_key=, wait=True)` → the new box; `get_fork(child_id)` → `SandboxFork`; `box.fork(name=, source_policy=, …)`, `box.fork_status()` |
42
+ | Exec | `box.exec(cmd)` → `ExecResult(id, exit_code, stdout, stderr)`; `exec_stream(cmd)`; `exec_background(cmd)` → `Command`; `run_code("python", code, cwd=)` |
43
+ | Commands | `Command.get()`, `events(since=)`, `wait()`, `stdin(data)`, `close_stdin()`, `signal("TERM")`; `box.commands.list/get/handle/events/stdin/close_stdin/signal` |
44
+ | Files | `box.files.read`, `read_text`, `write`, `list`, `stat`, `mkdir`, `move`, `copy`, `delete`, `upload`, `download` |
45
+ | PTY | `box.pty.create(cols=, rows=, client_label=)` / `attach(session_id, …)` → `write`, `resize`, `takeover`, `on_data`, iterate, `detach`, `close`, `wait` |
46
+ | Previews | `box.preview.create(port, label=)` → `Preview(url, label)`; `remove(label)` |
47
+ | Other | `box.logs(since=, lines=, unit=)`, `box.ssh_info()`, `box.screenshot()`, `zb.account.balance()`, `usage()`, `whoami()` |
48
+ | Tailscale | `box.tailscale.status()` → `TailscaleStatus` or `None`; `connect(auth_key)`; `disconnect()`; `box.set_private(enabled)`; `create(private=True)` |
49
49
 
50
50
  A string command runs under `bash -lc` (your PATH, nvm, pyenv); a list is spawned as argv.
51
51
  A command that exits non-zero is a result: check `exit_code`. Relative paths resolve
@@ -56,6 +56,19 @@ merely drops after the command started re-attaches from its last cursor by itsel
56
56
  started with `exec_background` keeps running with nobody attached — re-attach any time
57
57
  with `box.commands.handle(id).events(since=cursor)`.
58
58
 
59
+ ## Pause and resume
60
+
61
+ ```python
62
+ box = zb.sandboxes.pause(box.id) # returns the box paused; nothing is billed while paused
63
+ box = zb.sandboxes.resume(box.id) # returns the box ready, files and software as they were
64
+ ```
65
+
66
+ `pause` and `resume` return once the box is there: at once when the server answers with the
67
+ final state, else after waiting for it on `GET /sandbox/:id/wait`, with no deadline. A box
68
+ whose Pause was cancelled raises `conflict`. `resume` on a box still `stopping` (a Pause still
69
+ landing) waits that out, then resumes it. `stop` and `start` are aliases that send the same
70
+ requests. On a box object, `box.pause()` / `box.resume()` return the updated detail.
71
+
59
72
  ## Tailscale and private boxes
60
73
 
61
74
  ```python
@@ -96,11 +109,13 @@ A fork is a new box with the source's files, packages and settings, and a new id
96
109
  `private=True`, whatever the source's privacy. A running
97
110
  source needs `source_policy="pause_and_resume"`: it pauses for the capture (its sessions
98
111
  disconnect) and resumes right after; `"require_paused"` raises `pause_required` instead.
99
- Every wait (`create`, `get_or_create`, `wait_ready`, `fork`) reads the box's `readiness`: it keeps reading
100
- while the box is `settling`, with backoff and no deadline (a retryable failed read stays on
101
- the same ladder), returns on `ready` or, for a private box, `awaits_tailnet`, and raises on
112
+ Every wait (`create`, `get_or_create`, `wait_ready`, `resume`, `fork`) asks
113
+ `GET /sandbox/:id/wait?until=ready`, which the server answers when the box gets there; it
114
+ asks again while the box is `settling`, with no deadline (a retryable failed read waits on a
115
+ backoff ladder), returns on `ready` or, for a private box, `awaits_tailnet`, and raises on
102
116
  the rest, never retryable: paused `box_not_running`, a failed start `start_failed`, deleting
103
- or gone `conflict`. Rows carry `phase` and `allowed_actions`; a detail also carries `readiness`.
117
+ or gone `conflict`. An API older than `/wait` is polled with `GET /sandbox/:id` instead. A
118
+ `create` the server answers with the box already bound returns at once, with no wait. Rows carry `phase` and `allowed_actions`; a detail also carries `readiness`.
104
119
  One retry rule: an error is retried when its `retryable` is true.
105
120
 
106
121
  A created box's `base_url` changes once, a few minutes after create: from its boot address
@@ -138,8 +153,8 @@ machine names, and a deleted box keeps its name: reuse a fixed pool of names wit
138
153
  retry_base_delay_s=0.5, retry_max_delay_s=30.0, poll_interval_s=1.0,
139
154
  poll_max_interval_s=10.0, pty_base_delay_s=0.5, pty_max_delay_s=30.0)`. The key and URL
140
155
  default to `ZIPBOX_API_KEY` and `ZIPBOX_API_URL` (else `https://api.tribes.xyz`). A wait's
141
- readiness checks start at `poll_interval_s` and grow 1.25× per check to
142
- `poll_max_interval_s`, with jitter.
156
+ retries after a failed read, and its checks against an API older than `/wait`, start at
157
+ `poll_interval_s` and grow 1.25× per check to `poll_max_interval_s`, with jitter.
143
158
 
144
159
  Docs: [zipbox.ai/docs/sdk-python](https://zipbox.ai/docs/sdk-python) · Agent index:
145
160
  [zipbox.ai/llms.txt](https://zipbox.ai/llms.txt) · Apache-2.0.
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "zipbox"
7
- version = "0.1.7"
7
+ version = "0.2.0"
8
8
  description = "Drive Zipbox boxes from Python: create, exec, files, PTY, previews."
9
9
  readme = "README.md"
10
10
  license = "Apache-2.0"
@@ -118,7 +118,8 @@ class AsyncSandboxes:
118
118
  mailbox: bool | None = None,
119
119
  private: bool | None = None,
120
120
  ) -> AsyncSandbox:
121
- """Create a box and wait until it is ready (no deadline).
121
+ """Create a box and return it once it is ready (no deadline): at once when the
122
+ server bound a booted machine inside the request.
122
123
 
123
124
  ``mailbox=True`` creates the box's mailbox now; by default it is created
124
125
  the first time the box uses mail. ``private=True`` creates it private
@@ -146,7 +147,7 @@ class AsyncSandboxes:
146
147
  mailbox: bool | None = None,
147
148
  private: bool | None = None,
148
149
  ) -> AsyncSandbox:
149
- """Return the live box named ``name`` (starting it if stopped), or create it with
150
+ """Return the live box named ``name`` (resuming it if paused), or create it with
150
151
  these options.
151
152
 
152
153
  The options apply only when a box is created. A box that already has this name
@@ -174,13 +175,31 @@ class AsyncSandboxes:
174
175
  detail = await self._client._run(self._client._core.get(sandbox_id))
175
176
  return AsyncSandbox(self._client, sandbox_id, detail)
176
177
 
177
- async def start(self, sandbox_id: str) -> None:
178
- """Start a stopped box, or a ``stopping`` one once its stop lands (402 when dry)."""
179
- await self._client._run(self._client._core.start(sandbox_id))
178
+ async def pause(self, sandbox_id: str) -> AsyncSandbox:
179
+ """Pause a box and return it paused: nothing is billed while it is paused, and
180
+ ``resume`` brings it back with its files and installed software.
180
181
 
181
- async def stop(self, sandbox_id: str) -> None:
182
- """Stop a box: disk archived, nothing billed while stopped."""
183
- await self._client._run(self._client._core.lifecycle(sandbox_id, "pause"))
182
+ Returns at once when the server answers with the paused box, else waits for the
183
+ Pause to take effect (no deadline). A box that reads running again (the Pause
184
+ was cancelled) raises ``conflict``.
185
+ """
186
+ detail = await self._client._run(self._client._core.pause(sandbox_id))
187
+ return AsyncSandbox(self._client, sandbox_id, detail)
188
+
189
+ async def resume(self, sandbox_id: str) -> AsyncSandbox:
190
+ """Resume a paused box and return it ready; a ``stopping`` one is resumed once
191
+ its Pause lands. Returns at once when the server answers with the ready box,
192
+ else waits as ``wait_ready`` does (402 ``insufficient_credits`` when dry)."""
193
+ detail = await self._client._run(self._client._core.resume(sandbox_id))
194
+ return AsyncSandbox(self._client, sandbox_id, detail)
195
+
196
+ async def stop(self, sandbox_id: str) -> AsyncSandbox:
197
+ """Alias of ``pause``: the same request and the same result."""
198
+ return await self.pause(sandbox_id)
199
+
200
+ async def start(self, sandbox_id: str) -> AsyncSandbox:
201
+ """Alias of ``resume``: the same request and the same result."""
202
+ return await self.resume(sandbox_id)
184
203
 
185
204
  async def restart(self, sandbox_id: str) -> None:
186
205
  """Hard-restart a running box; files survive."""
@@ -354,13 +373,24 @@ class AsyncSandbox:
354
373
  """A PNG of the box's desktop."""
355
374
  return await self._client._run(self._client._core.screenshot(self.id))
356
375
 
357
- async def start(self) -> None:
358
- """Start this box."""
359
- await self._client.sandboxes.start(self.id)
376
+ async def pause(self) -> SandboxDetail:
377
+ """Pause this box (nothing billed while paused) and return its detail, paused."""
378
+ self.info = await self._client._run(self._client._core.pause(self.id))
379
+ return self.info
380
+
381
+ async def resume(self) -> SandboxDetail:
382
+ """Resume this box and return its detail, ready; a ``stopping`` box is resumed
383
+ once its Pause lands."""
384
+ self.info = await self._client._run(self._client._core.resume(self.id))
385
+ return self.info
386
+
387
+ async def stop(self) -> SandboxDetail:
388
+ """Alias of ``pause``: the same request and the same result."""
389
+ return await self.pause()
360
390
 
361
- async def stop(self) -> None:
362
- """Stop this box."""
363
- await self._client.sandboxes.stop(self.id)
391
+ async def start(self) -> SandboxDetail:
392
+ """Alias of ``resume``: the same request and the same result."""
393
+ return await self.resume()
364
394
 
365
395
  async def restart(self) -> None:
366
396
  """Hard-restart this box."""
@@ -116,7 +116,8 @@ class Sandboxes:
116
116
  mailbox: bool | None = None,
117
117
  private: bool | None = None,
118
118
  ) -> Sandbox:
119
- """Create a box and wait until it is ready (no deadline).
119
+ """Create a box and return it once it is ready (no deadline): at once when the
120
+ server bound a booted machine inside the request.
120
121
 
121
122
  ``mailbox=True`` creates the box's mailbox now; by default it is created
122
123
  the first time the box uses mail. ``private=True`` creates it private
@@ -144,7 +145,7 @@ class Sandboxes:
144
145
  mailbox: bool | None = None,
145
146
  private: bool | None = None,
146
147
  ) -> Sandbox:
147
- """Return the live box named ``name`` (starting it if stopped), or create it with
148
+ """Return the live box named ``name`` (resuming it if paused), or create it with
148
149
  these options.
149
150
 
150
151
  The options apply only when a box is created. A box that already has this name
@@ -172,13 +173,31 @@ class Sandboxes:
172
173
  detail = self._client._run(self._client._core.get(sandbox_id))
173
174
  return Sandbox(self._client, sandbox_id, detail)
174
175
 
175
- def start(self, sandbox_id: str) -> None:
176
- """Start a stopped box, or a ``stopping`` one once its stop lands (402 when dry)."""
177
- self._client._run(self._client._core.start(sandbox_id))
176
+ def pause(self, sandbox_id: str) -> Sandbox:
177
+ """Pause a box and return it paused: nothing is billed while it is paused, and
178
+ ``resume`` brings it back with its files and installed software.
178
179
 
179
- def stop(self, sandbox_id: str) -> None:
180
- """Stop a box: disk archived, nothing billed while stopped."""
181
- self._client._run(self._client._core.lifecycle(sandbox_id, "pause"))
180
+ Returns at once when the server answers with the paused box, else waits for the
181
+ Pause to take effect (no deadline). A box that reads running again (the Pause
182
+ was cancelled) raises ``conflict``.
183
+ """
184
+ detail = self._client._run(self._client._core.pause(sandbox_id))
185
+ return Sandbox(self._client, sandbox_id, detail)
186
+
187
+ def resume(self, sandbox_id: str) -> Sandbox:
188
+ """Resume a paused box and return it ready; a ``stopping`` one is resumed once
189
+ its Pause lands. Returns at once when the server answers with the ready box,
190
+ else waits as ``wait_ready`` does (402 ``insufficient_credits`` when dry)."""
191
+ detail = self._client._run(self._client._core.resume(sandbox_id))
192
+ return Sandbox(self._client, sandbox_id, detail)
193
+
194
+ def stop(self, sandbox_id: str) -> Sandbox:
195
+ """Alias of ``pause``: the same request and the same result."""
196
+ return self.pause(sandbox_id)
197
+
198
+ def start(self, sandbox_id: str) -> Sandbox:
199
+ """Alias of ``resume``: the same request and the same result."""
200
+ return self.resume(sandbox_id)
182
201
 
183
202
  def restart(self, sandbox_id: str) -> None:
184
203
  """Hard-restart a running box; files survive."""
@@ -350,13 +369,24 @@ class Sandbox:
350
369
  """A PNG of the box's desktop."""
351
370
  return self._client._run(self._client._core.screenshot(self.id))
352
371
 
353
- def start(self) -> None:
354
- """Start this box."""
355
- self._client.sandboxes.start(self.id)
372
+ def pause(self) -> SandboxDetail:
373
+ """Pause this box (nothing billed while paused) and return its detail, paused."""
374
+ self.info = self._client._run(self._client._core.pause(self.id))
375
+ return self.info
376
+
377
+ def resume(self) -> SandboxDetail:
378
+ """Resume this box and return its detail, ready; a ``stopping`` box is resumed
379
+ once its Pause lands."""
380
+ self.info = self._client._run(self._client._core.resume(self.id))
381
+ return self.info
382
+
383
+ def stop(self) -> SandboxDetail:
384
+ """Alias of ``pause``: the same request and the same result."""
385
+ return self.pause()
356
386
 
357
- def stop(self) -> None:
358
- """Stop this box."""
359
- self._client.sandboxes.stop(self.id)
387
+ def start(self) -> SandboxDetail:
388
+ """Alias of ``resume``: the same request and the same result."""
389
+ return self.resume()
360
390
 
361
391
  def restart(self) -> None:
362
392
  """Hard-restart this box."""