testflows.machine 0.1.0__py3-none-any.whl

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.

Potentially problematic release.


This version of testflows.machine might be problematic. Click here for more details.

@@ -0,0 +1,1924 @@
1
+ # Copyright 2026 Katteli Inc.
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+ """The client: where the SDK starts, and the one object a program holds.
15
+
16
+ The SDK mirrors the CLI. A top-level command is a method of `Client`, a
17
+ command group is an attribute, and a command that takes a run is a method of
18
+ `Run`: `machine create` is `client.create()`, `machine sessions use` is
19
+ `client.sessions.use()`, and `machine start app` is `run.start()`.
20
+ """
21
+
22
+ from __future__ import annotations
23
+
24
+ import builtins
25
+ import contextlib
26
+ import dataclasses
27
+ import time
28
+ import os
29
+ from typing import Any, Generator, Literal, Optional, Sequence, overload
30
+
31
+ from testflows.machine._core import api
32
+ from testflows.machine._core import branches as _branches
33
+ from testflows.machine._core import cloud_run_source as _cloud_run_source
34
+ from testflows.machine._core import ipc as _ipc
35
+ from testflows.machine._core import lifecycle as _lifecycle
36
+ from testflows.machine._core import machines as _machines
37
+ from testflows.machine._core import parsers as _parsers
38
+ from testflows.machine._core import ping as _ping
39
+ from testflows.machine._core import storage_ops as _storage_ops
40
+ from testflows.machine._core import run_source as _run_source
41
+ from testflows.machine._core import sorting as _sorting
42
+ from testflows.machine._core import wait as _wait
43
+ from testflows.machine._core import wire as _wire
44
+
45
+ from . import _args
46
+ from . import _service
47
+ from . import _when
48
+ from . import results
49
+ from .errors import ApiError, InvalidArgument, ServiceUnavailable, _translated
50
+ from .disks import Disk, Disks
51
+ from .ping import Ping, _public
52
+ from .runs import Run
53
+ from .sessions import Session, Sessions
54
+
55
+ #: Set to 1, a client given no session works with the service on this
56
+ #: machine.
57
+ _LOCAL_ENV = "TESTFLOWS_MACHINE_LOCAL"
58
+
59
+ #: The values `create` accepts for its enumerated options.
60
+ _MEM_TYPES = ("auto", "hugepages")
61
+ _MEM_MODES = ("auto", "map", "lazy")
62
+ _CONSOLES = ("serial", "virtio")
63
+ _FRAMEBUFFERS = ("vnc", "gtk", "sdl", "none")
64
+
65
+ #: `runs --parents`: where a run reads its data parents from.
66
+ _PARENTS = ("local", "remote")
67
+
68
+ #: What `create` accepts, the bounds the CLI holds the same flags to. A vCPU
69
+ #: count and a memory size the machine cannot serve are refused here rather
70
+ #: than at the spawn.
71
+ _MAX_CPUS = _wire.MAX_VCPUS
72
+ _MAX_MEM_MB = 1048576
73
+
74
+
75
+ class Client:
76
+ """The one object a program holds, as the `machine` command is.
77
+
78
+ A top-level CLI command is a method here, and a command group is an
79
+ attribute: `machine create` is `create`, `machine runs` is `runs`,
80
+ `machine sessions use` is `sessions.use`. A command that takes a run is
81
+ a method of the `Run` these return.
82
+
83
+ A run lives in a session: a machine the account rents, with its own
84
+ CPUs, memory and storage. The client has a current session, as the CLI
85
+ does: `session=` sets it, as `-s` does, and `sessions.use` or
86
+ `sessions.connect` change it for this client only, never for the CLI.
87
+ Commands that need a machine go to the current session at the time of
88
+ the call. With no session, reading the account's runs still works:
89
+ `runs`, `branches`, `marks`, and a run's `describe`, `lineage` and
90
+ `checkpoints` read the account's catalog.
91
+
92
+ Nothing is contacted until a call needs it. Every call signs in with
93
+ TESTFLOWS_MACHINE_API_KEY when it is set, otherwise the login stored by
94
+ `machine login` or `login.verify`.
95
+
96
+ Example:
97
+ >>> import testflows.machine.v1 as machine
98
+ >>> client = machine.Client()
99
+ >>> with client.sessions.create("ci-1", cpus=4) as session:
100
+ ... client.sessions.use(session)
101
+ ... run = client.create("app", disk="app")
102
+ ... run.run(until="tasks")
103
+ ... run.focus.add("/app")
104
+ ... run.run(until="/app:exit")
105
+ ... run.checkpoint("done")
106
+
107
+ Args:
108
+ session (str, optional): The current session, by name, id or unique
109
+ id prefix, as `-s` names it.
110
+ api_url (str, optional): The service's URL, as `--api-url` gives it;
111
+ defaults to TESTFLOWS_MACHINE_API_URL, else the public service.
112
+ """
113
+
114
+ def __init__(
115
+ self,
116
+ *,
117
+ session: Optional[str] = None,
118
+ api_url: Optional[str] = None,
119
+ ) -> None:
120
+ local = os.environ.get(_LOCAL_ENV) == "1"
121
+ if local and session is not None:
122
+ raise InvalidArgument(
123
+ f"{_LOCAL_ENV} is set, so a client cannot take a session."
124
+ f" Unset it to work with session {session!r}."
125
+ )
126
+ self._local = local
127
+ self._session_ref = session
128
+ self._session: Optional[Session] = None
129
+ self._api_url = api_url
130
+ self._api: Optional[tuple[api.client.Client, dict[str, Any]]] = None
131
+ self._services: dict[str, _service._Service] = {}
132
+
133
+ @classmethod
134
+ def _signed_in(
135
+ cls, client: api.client.Client, creds: dict[str, Any], api_url: Optional[str]
136
+ ) -> "Client":
137
+ """A client with no session, over a login already made."""
138
+ made = cls(api_url=api_url)
139
+ made._api = (client, creds)
140
+ return made
141
+
142
+ # -- the session -----------------------------------------------------------
143
+
144
+ @property
145
+ def session(self) -> Optional[Session]:
146
+ """Session: The current session, read on first use; None when the
147
+ client has none.
148
+
149
+ Raises:
150
+ NotFound: No session matches the name the client was given.
151
+ InvalidArgument: The name matches more than one session.
152
+ """
153
+ if self._session_ref is None:
154
+ return None
155
+ if self._session is None:
156
+ self._session = self.sessions.show(self._session_ref)
157
+ return self._session
158
+
159
+ @property
160
+ def sessions(self) -> Sessions:
161
+ """Sessions: The account's sessions, as `machine sessions`: create,
162
+ list, use and delete them.
163
+
164
+ Raises:
165
+ NotSignedIn: There are no credentials.
166
+ """
167
+ return Sessions(self)
168
+
169
+ @property
170
+ def disks(self) -> Disks:
171
+ """Disks: The account's disks, as `machine disks`: push, list and
172
+ delete them.
173
+
174
+ Raises:
175
+ NotSignedIn: There are no credentials.
176
+ """
177
+ return Disks(*self._account())
178
+
179
+ @property
180
+ def storage(self) -> "Storage":
181
+ """Storage: What the account stores, as `machine storage`."""
182
+ return Storage(self)
183
+
184
+ @property
185
+ def preload(self) -> "Preload":
186
+ """Preload: Copies onto the current session's disk, as `machine
187
+ preload`."""
188
+ return Preload(self)
189
+
190
+ @property
191
+ def offload(self) -> "Offload":
192
+ """Offload: Copies dropped from the current session's disk, as
193
+ `machine offload`."""
194
+ return Offload(self)
195
+
196
+ @property
197
+ def marks(self) -> "Marks":
198
+ """Marks: The marks of every tree, as `machine marks`."""
199
+ return Marks(self)
200
+
201
+ @property
202
+ def delete(self) -> "Delete":
203
+ """Delete: Deleting every run of the session, or those booting a
204
+ disk, as `machine delete -a`; `cleanup` resumes interrupted ones."""
205
+ return Delete(self)
206
+
207
+ @property
208
+ def runs(self) -> "Runs":
209
+ """Runs: The account's runs, as `machine runs`: call it to list them,
210
+ and index it to get one."""
211
+ return Runs(self)
212
+
213
+ # -- runs ------------------------------------------------------------------
214
+
215
+ def create(
216
+ self,
217
+ name: Optional[str] = None,
218
+ *,
219
+ disk: "Disk | str",
220
+ like: "Run | str | None" = None,
221
+ labels: Optional[dict[str, str]] = None,
222
+ keep_output: "Sequence[str] | str | None" = None,
223
+ drop_output: "Sequence[str] | str | None" = None,
224
+ cpus: Optional[int] = None,
225
+ mem: Optional[int] = None,
226
+ mem_type: Optional[str] = None,
227
+ console: Optional[str] = None,
228
+ mem_mode: Optional[str] = None,
229
+ fs_sync: Optional[bool] = None,
230
+ fs_dirsync: Optional[bool] = None,
231
+ fb: Optional[str] = None,
232
+ rng: Optional[bool] = None,
233
+ rng_seed: Optional[int] = None,
234
+ daemon: Optional[bool] = None,
235
+ single_step: Optional[bool] = None,
236
+ limit: Optional[int] = None,
237
+ backstop_limit: Optional[int] = None,
238
+ pin_cpu: Optional[int] = None,
239
+ vtime_base: Optional[int] = None,
240
+ vtime_rate: Optional[str] = None,
241
+ vtime_io_cost: Optional[int] = None,
242
+ vtime_rdtsc_cost: Optional[int] = None,
243
+ vtime_pause_cost: Optional[int] = None,
244
+ auto_checkpoints: Optional[int] = None,
245
+ side_dump: Optional[bool] = None,
246
+ side_trace: Optional[bool] = None,
247
+ mem_hash: Optional[bool] = None,
248
+ disk_hash: Optional[bool] = None,
249
+ repeatable: Optional[bool] = None,
250
+ limit_margin: Optional[int] = None,
251
+ timer_slack: Optional[str] = None,
252
+ instr_margin: Optional[int] = None,
253
+ dispatch_bound: Optional[str] = None,
254
+ fast_backstop: Optional[int] = None,
255
+ irq_wait: Optional[int] = None,
256
+ wait: bool = True,
257
+ timeout: Optional[float] = None,
258
+ ) -> Run:
259
+ """Create a run on a disk and bring its machine up, as
260
+ `machine create` does, in the current session.
261
+
262
+ The machine boots nothing on its own: it waits for commands, and
263
+ `Run.run` drives it. Every option left None takes its value from
264
+ `like`, a run whose options are copied, else the default: 1 vCPU,
265
+ 256 MB, an RNG device, fast execution with no limit. Used in a
266
+ `with` block, the run is deleted when the block exits, unless the
267
+ block calls `Run.keep`.
268
+
269
+ Example:
270
+ >>> run = client.create("app", disk="app", cpus=2,
271
+ ... rng_seed=7, labels={"suite": "nightly"})
272
+ >>> twin = client.create(disk="app", like=run, cpus=4)
273
+ >>> with client.create(disk="app") as scratch:
274
+ ... scratch.run(until="tasks")
275
+
276
+ Args:
277
+ name (str, optional): The run's name; one is generated when
278
+ omitted.
279
+ disk (str): The disk to boot, by name; `Client.disks` lists
280
+ them and `Disks.push` adds one.
281
+ like (Run or str, optional): A run whose options to copy.
282
+ labels (dict[str, str], optional): Labels to attach, for
283
+ `runs(labels=...)`; an empty value removes one `like`
284
+ carried.
285
+ keep_output (str or list[str], optional): Sources whose output
286
+ the run stores though it is dropped: an output file or a
287
+ directory of them by its path, such as
288
+ `/output/drop/app/debug.log`, or a pattern such as
289
+ `/output/drop/*/*.log`. The run keeps them for its whole
290
+ life, and a branch of it has them unless it names its own.
291
+ drop_output (str or list[str], optional): Sources whose output
292
+ the run does not store: a path, a device such as `ttyS1`,
293
+ or a pattern. `Run.fork` describes the patterns and which
294
+ of a kept and a dropped name decides.
295
+ cpus (int, optional): vCPUs.
296
+ mem (int, optional): Guest memory in MB.
297
+ mem_type (str, optional): Guest memory backing: `auto` or
298
+ `hugepages`.
299
+ mem_mode (str, optional): How a cold restore maps memory:
300
+ `auto`, `map` or `lazy`.
301
+ console (str, optional): The device the run's console is:
302
+ `serial` for the first serial port, `ttyS0`, or `virtio`
303
+ for the virtio console, `hvc0`. Defaults to `serial`.
304
+ fs_sync (bool, optional): Mount the root filesystem `sync`, so
305
+ writes reach the disk at once.
306
+ fs_dirsync (bool, optional): Mount it `dirsync`.
307
+ fb (str, optional): Open a framebuffer to watch the guest:
308
+ `vnc`, `gtk`, `sdl` or `none`.
309
+ rng (bool, optional): Give the guest an RNG device, whose seed
310
+ a branch can change; on by default, False leaves it out.
311
+ rng_seed (int, optional): The RNG's seed; the same seed gives
312
+ the same random bytes.
313
+ daemon (bool, optional): Wait for commands; False runs the
314
+ machine to completion. The run keeps it, and every later
315
+ start and fork repeats it. Defaults to True.
316
+ single_step (bool, optional): Run in step mode, for runs that
317
+ do not wait for commands. Kept the same way. Defaults to
318
+ False.
319
+ limit (int, optional): Conditional branches a fast dispatch may
320
+ run, steps in step mode; 0 for no limit.
321
+ backstop_limit (int, optional): Step modes only: instructions a
322
+ dispatch may run without stepping.
323
+ pin_cpu (int, optional): Pin this machine to a host CPU; the
324
+ default lets it pick the least-loaded. A CPU belongs to one
325
+ machine, so the run does not keep it.
326
+ vtime_base (int, optional): The guest's clock at boot, in Unix
327
+ seconds; defaults to 2026-03-01.
328
+ vtime_rate (str, optional): Virtual nanoseconds per instruction,
329
+ `n` or `n/d`.
330
+ vtime_io_cost (int, optional): Virtual nanoseconds each I/O exit
331
+ costs.
332
+ vtime_rdtsc_cost (int, optional): Virtual nanoseconds each RDTSC
333
+ exit costs.
334
+ vtime_pause_cost (int, optional): Virtual nanoseconds each PAUSE
335
+ costs.
336
+ auto_checkpoints (int, optional): Checkpoint every this many
337
+ entries; 0 for never.
338
+ side_dump (bool, optional): Record the machine's state with every
339
+ entry, which `Run.dump(entry=...)` reads back; costs disk.
340
+ side_trace (bool, optional): Record an execution trace with
341
+ every entry.
342
+ mem_hash (bool, optional): Hash the machine's memory at every
343
+ entry, so that a replay compares memory too. Off by default.
344
+ disk_hash (bool, optional): Hash the machine's disk at every
345
+ entry, so that a replay compares the disk too. Off by default.
346
+ repeatable (bool, optional): Record so that the same run,
347
+ recorded again from the same start with the same commands,
348
+ records the same entries. Fast execution stops exactly at
349
+ its limit and at timer deadlines, which records more
350
+ slowly. The run keeps it, and every start and fork of it
351
+ records the same way. None: the session's default. A
352
+ run's describe shows the value it was given.
353
+ limit_margin (int, optional): How many branches short of each
354
+ stop the branch counter interrupts. Fewer is faster, too
355
+ few misses stops. Defaults to the skid of the host's
356
+ branch counter.
357
+ timer_slack (str, optional): How late a timer may be in code
358
+ that takes no exit, a duration such as `20ms`, or `0` for
359
+ no later than its deadline. More is faster. Defaults to
360
+ `20ms`.
361
+ instr_margin (int, optional): How many instructions short of a
362
+ stop placed by an instruction count the instruction counter
363
+ interrupts. A replay that passes such a stop needs more.
364
+ Defaults to the host's: 50,000 on AMD, 3,630 on Intel.
365
+ dispatch_bound (str, optional): The host time a fast dispatch
366
+ may run before it stops, a duration such as `500ms`. A stop
367
+ it places does not repeat in another recording. Defaults to
368
+ `1s`.
369
+ fast_backstop (int, optional): How many instructions a fast
370
+ dispatch may run with no other stop, in code that retires no
371
+ branch. Defaults to 100,000,000.
372
+ irq_wait (int, optional): How many branches a dispatch runs
373
+ while an interrupt waits for the guest to take it. Defaults
374
+ to 200.
375
+ wait (bool, optional): Return once the machine accepts commands.
376
+ Defaults to True.
377
+ timeout (float, optional): Seconds to wait; None waits without a
378
+ limit.
379
+
380
+ Returns:
381
+ Run: The new run.
382
+
383
+ Raises:
384
+ InvalidArgument: An option or label is not valid, or the client
385
+ has no session.
386
+ AlreadyExists: A run has this name.
387
+ NotFound: The disk or the `like` run does not exist.
388
+ Timeout: The machine was not ready within `timeout`.
389
+ ApiError: The machine failed to start; the message says why.
390
+ """
391
+ # The same bounds the CLI holds these to, so a number the machine would
392
+ # refuse is refused here, with the range in the message.
393
+ _args.bounded("cpus", cpus, 1, _MAX_CPUS)
394
+ _args.bounded("mem", mem, 1, _MAX_MEM_MB)
395
+ _args.bounded("limit", limit, 0)
396
+ _args.bounded("backstop_limit", backstop_limit, 0)
397
+ _args.bounded("auto_checkpoints", auto_checkpoints, 0)
398
+ _args.bounded("pin_cpu", pin_cpu, _args.MIN_PIN_CPU, _args.MAX_PIN_CPU)
399
+ explicit: dict[str, Any] = {
400
+ key: value
401
+ for key, value in (
402
+ ("cpus", cpus),
403
+ ("memory", mem),
404
+ ("mem_type", mem_type),
405
+ ("mem_mode", mem_mode),
406
+ ("console", console),
407
+ ("fs_sync", fs_sync),
408
+ ("fs_dirsync", fs_dirsync),
409
+ ("fb", fb),
410
+ ("rng", rng),
411
+ ("rng_seed", rng_seed),
412
+ ("daemon", daemon),
413
+ ("single_step", single_step),
414
+ ("limit", limit),
415
+ ("backstop_limit", backstop_limit),
416
+ ("pin_cpu", pin_cpu),
417
+ ("vtime_base", vtime_base),
418
+ ("vtime_io_cost", vtime_io_cost),
419
+ ("vtime_rdtsc_cost", vtime_rdtsc_cost),
420
+ ("vtime_pause_cost", vtime_pause_cost),
421
+ ("auto_checkpoint_interval", auto_checkpoints),
422
+ ("side_dump", side_dump),
423
+ ("side_trace", side_trace),
424
+ ("mem_hash", mem_hash),
425
+ ("disk_hash", disk_hash),
426
+ ("repeatable", repeatable),
427
+ ("limit_margin", _args.limit_margin(limit_margin)),
428
+ ("timer_slack", _args.timer_slack(timer_slack)),
429
+ ("instr_margin", _args.stop_count("instr_margin", instr_margin)),
430
+ ("dispatch_bound", _args.dispatch_bound(dispatch_bound)),
431
+ ("fast_backstop", _args.stop_count("fast_backstop", fast_backstop)),
432
+ ("irq_wait", _args.irq_wait(irq_wait)),
433
+ )
434
+ if value is not None
435
+ }
436
+ _args.check_choice("mem_type", mem_type, _MEM_TYPES)
437
+ _args.check_choice("mem_mode", mem_mode, _MEM_MODES)
438
+ _args.check_choice("console", console, _CONSOLES)
439
+ _args.check_choice("fb", fb, _FRAMEBUFFERS)
440
+ with _translated():
441
+ for label in labels or {}:
442
+ _machines.validate_label_name(label)
443
+ if vtime_rate is not None:
444
+ num, den = _parsers.vtime_rate_type(vtime_rate)
445
+ explicit.update(vtime_rate_num=num, vtime_rate_den=den)
446
+ service = self._service()
447
+ resolved = service.disk(_args.disk_ref(disk))
448
+ with service.client() as client, _translated():
449
+ kwargs = dict(_machines.RUN_DEFAULTS)
450
+ if like is not None:
451
+ like_id = like.id if isinstance(like, Run) else like
452
+ kwargs.update(
453
+ _machines.describe_to_run_kwargs(client.describe(like_id))
454
+ )
455
+ kwargs.update(explicit)
456
+ # `like` first, then the disk's own labels, then this call's: a
457
+ # disk labelled `version=1.2` is not relabelled 1.0 by copying
458
+ # the options of a run that booted an older one.
459
+ merged = {
460
+ **(kwargs.pop("labels", None) or {}),
461
+ **resolved.labels,
462
+ **(labels or {}),
463
+ }
464
+ merged = {key: value for key, value in merged.items() if value}
465
+ if merged:
466
+ kwargs["labels"] = merged
467
+ # What `like` copied stands for each list this call does not
468
+ # give.
469
+ kwargs["output"] = _args.stored(keep_output, drop_output).over(
470
+ kwargs.get("output") or _ipc.STORED_BY_DIRECTORY
471
+ )
472
+ made = _machines.run_machine(
473
+ client, name=name or "", disk=resolved.id, **kwargs
474
+ )
475
+ if wait:
476
+ _lifecycle.wait_ready(client, made, timeout_s=timeout)
477
+ run_name = _machines.display_name(client, made.run_id)
478
+ return Run(self, made.run_id, run_name)
479
+
480
+ @overload
481
+ def ops(
482
+ self,
483
+ *,
484
+ op_id: Optional[int] = ...,
485
+ states: Optional[builtins.list[str]] = ...,
486
+ types: Optional[builtins.list[str]] = ...,
487
+ since: "_when.When | None" = ...,
488
+ until: "_when.When | None" = ...,
489
+ limit: Optional[int] = ...,
490
+ offset: int = ...,
491
+ watch: Literal[False] = ...,
492
+ timeout: Optional[float] = ...,
493
+ ) -> builtins.list[results.Op]: ...
494
+
495
+ @overload
496
+ def ops(
497
+ self,
498
+ *,
499
+ op_id: Optional[int] = ...,
500
+ states: Optional[builtins.list[str]] = ...,
501
+ types: Optional[builtins.list[str]] = ...,
502
+ since: "_when.When | None" = ...,
503
+ until: "_when.When | None" = ...,
504
+ limit: Optional[int] = ...,
505
+ offset: int = ...,
506
+ watch: Literal[True],
507
+ timeout: Optional[float] = ...,
508
+ ) -> Generator[builtins.list[results.Op], None, None]: ...
509
+
510
+ def ops(
511
+ self,
512
+ *,
513
+ op_id: Optional[int] = None,
514
+ states: Optional[builtins.list[str]] = None,
515
+ types: Optional[builtins.list[str]] = None,
516
+ since: "_when.When | None" = None,
517
+ until: "_when.When | None" = None,
518
+ limit: Optional[int] = None,
519
+ offset: int = 0,
520
+ watch: bool = False,
521
+ timeout: Optional[float] = None,
522
+ ) -> "builtins.list[results.Op] | Generator[builtins.list[results.Op], None, None]":
523
+ """List the current session's operations on runs, newest first, as
524
+ `machine ops` does.
525
+
526
+ An operation is a checkpoint, branch, switch or rewind the session
527
+ carried out. The list is every operation in every state, which is
528
+ where to look when one of those calls returned an error; `states`
529
+ keeps some. Every matching operation is returned unless `limit` is
530
+ given. `Run.ops` lists one run's.
531
+
532
+ With `watch`, it yields the list at once, then again each time it
533
+ changes, such as a checkpoint finishing. Leave the loop, or pass
534
+ `timeout`, to stop watching.
535
+
536
+ Example:
537
+ >>> client.ops(states=["failed"], since="1h")
538
+ [{'op_id': '17897...', 'op_type': 'checkpoint', 'state': 'failed', ...}]
539
+ >>> for running in client.ops(states=["running"], watch=True, timeout=300):
540
+ ... if not running:
541
+ ... break
542
+
543
+ Args:
544
+ op_id (int, optional): Return this operation alone, whatever its
545
+ state or type.
546
+ states (list[str], optional): Keep these states: `running`,
547
+ `unfinished`, `done`, `failed`; `^state` leaves one out.
548
+ Defaults to every state.
549
+ types (list[str], optional): Keep these types: `checkpoint`,
550
+ `branch`, `switch`, `rewind`, `start`, `delete`; `^type`
551
+ leaves one out. Defaults to every type.
552
+ since (datetime or int or str, optional): Keep those started at
553
+ or after this time: a datetime, Unix seconds, a date or an
554
+ age such as `1h`.
555
+ until (datetime or int or str, optional): Keep those started at
556
+ or before this time.
557
+ limit (int, optional): Return at most this many.
558
+ offset (int, optional): Skip this many first. Defaults to 0.
559
+ watch (bool, optional): Yield the list each time it changes.
560
+ Defaults to False.
561
+ timeout (float, optional): With `watch`, end the generator after
562
+ this many seconds, without raising; None watches until the
563
+ caller leaves the loop.
564
+
565
+ Returns:
566
+ list[Op]: One record per operation: its id,
567
+ type, state, run, entry, start time and error; with `watch`, an
568
+ iterator of such lists.
569
+
570
+ Raises:
571
+ InvalidArgument: A state, type or time is not valid, or the
572
+ client has no session.
573
+ """
574
+ return self._ops(
575
+ None,
576
+ op_id=op_id,
577
+ states=states,
578
+ types=types,
579
+ since=since,
580
+ until=until,
581
+ limit=limit,
582
+ offset=offset,
583
+ watch=watch,
584
+ timeout=timeout,
585
+ )
586
+
587
+ @overload
588
+ def branches(
589
+ self,
590
+ *,
591
+ running: bool = ...,
592
+ depth: Optional[int] = ...,
593
+ since: "_when.When | None" = ...,
594
+ until: "_when.When | None" = ...,
595
+ sort: str = ...,
596
+ reverse: bool = ...,
597
+ limit: Optional[int] = ...,
598
+ offset: int = ...,
599
+ watch: Literal[False] = ...,
600
+ timeout: Optional[float] = ...,
601
+ ) -> builtins.list[Run]: ...
602
+
603
+ @overload
604
+ def branches(
605
+ self,
606
+ *,
607
+ running: bool = ...,
608
+ depth: Optional[int] = ...,
609
+ since: "_when.When | None" = ...,
610
+ until: "_when.When | None" = ...,
611
+ sort: str = ...,
612
+ reverse: bool = ...,
613
+ limit: Optional[int] = ...,
614
+ offset: int = ...,
615
+ watch: Literal[True],
616
+ timeout: Optional[float] = ...,
617
+ ) -> Generator[builtins.list[Run], None, None]: ...
618
+
619
+ def branches(
620
+ self,
621
+ *,
622
+ running: bool = False,
623
+ depth: Optional[int] = None,
624
+ since: "_when.When | None" = None,
625
+ until: "_when.When | None" = None,
626
+ sort: str = "created",
627
+ reverse: bool = False,
628
+ limit: Optional[int] = None,
629
+ offset: int = 0,
630
+ watch: bool = False,
631
+ timeout: Optional[float] = None,
632
+ ) -> "builtins.list[Run] | Generator[builtins.list[Run], None, None]":
633
+ """List the runs of every tree, newest first, as `machine branches`
634
+ does.
635
+
636
+ Every matching run is returned unless `limit` is given. Answers with
637
+ no session, from the account's catalog. `Run.branches` lists one
638
+ run's tree.
639
+
640
+ With `watch`, it yields the list at once, then again each time it
641
+ changes: a branch forked or deleted, or one starting or stopping.
642
+ Leave the loop, or pass `timeout`, to stop watching.
643
+
644
+ Example:
645
+ >>> [b.name for b in client.branches(depth=0)]
646
+ ['app', 'db']
647
+ >>> for running in client.branches(running=True, watch=True, timeout=600):
648
+ ... if not running:
649
+ ... break
650
+
651
+ Args:
652
+ running (bool, optional): Keep those with a machine. Defaults to
653
+ False.
654
+ depth (int, optional): Keep those this many forks from their
655
+ root; 0 is the roots.
656
+ since (datetime or int or str, optional): Keep those created at
657
+ or after this time: a datetime, Unix seconds, a date or an
658
+ age such as `1h`.
659
+ until (datetime or int or str, optional): Keep those created at
660
+ or before this time.
661
+ sort (str, optional): `created`, newest first, or `name`, A to
662
+ Z. Defaults to `created`.
663
+ reverse (bool, optional): Turn the order round. Defaults to
664
+ False.
665
+ limit (int, optional): Return at most this many.
666
+ offset (int, optional): Skip this many first. Defaults to 0.
667
+ watch (bool, optional): Yield the list each time it changes.
668
+ Defaults to False.
669
+ timeout (float, optional): With `watch`, end the generator after
670
+ this many seconds, without raising; None watches until the
671
+ caller leaves the loop.
672
+
673
+ Returns:
674
+ list[Run]: The runs; with `watch`, an iterator of such lists.
675
+
676
+ Raises:
677
+ InvalidArgument: `sort` or a time is not valid.
678
+ """
679
+ return self._branches(
680
+ None,
681
+ running=running,
682
+ depth=depth,
683
+ since=since,
684
+ until=until,
685
+ sort=sort,
686
+ reverse=reverse,
687
+ limit=limit,
688
+ offset=offset,
689
+ watch=watch,
690
+ timeout=timeout,
691
+ )
692
+
693
+ def cleanup(self, *, force: bool = False) -> results.Cleanup:
694
+ """Remove what machines that ended uncleanly left behind in the
695
+ current session, as `machine cleanup` does.
696
+
697
+ A machine that crashed or was killed from outside leaves stale
698
+ entries the service clears here. Runs themselves are not deleted.
699
+ With `force`, machines that no longer answer are killed and their
700
+ entries removed too.
701
+
702
+ Args:
703
+ force (bool, optional): Also kill orphaned machines and remove
704
+ entries whose machine is already gone. Defaults to False.
705
+
706
+ Returns:
707
+ Cleanup: What was cleaned, and the runs it touched.
708
+
709
+ Raises:
710
+ InvalidArgument: The client has no session.
711
+ """
712
+ with self._connection() as client, _translated():
713
+ done = _machines.clean(client, force=force)
714
+ return results.cleanup(dataclasses.asdict(done))
715
+
716
+ def ping(self, *, count: int = 3) -> Ping:
717
+ """Measure whether the current session's service answers, and how
718
+ fast, as `machine ping` does.
719
+
720
+ For a client with no session it measures the account's service
721
+ instead. A service that cannot be reached is a result, not an
722
+ exception: `Ping.ok` is False and `Ping.error` says why.
723
+
724
+ Example:
725
+ >>> ping = client.ping()
726
+ >>> ping.ok, round(ping.rtt_ms, 1)
727
+ (True, 1.8)
728
+
729
+ Args:
730
+ count (int, optional): Round trips to time, at least 1.
731
+ Defaults to 3.
732
+
733
+ Returns:
734
+ Ping: Whether it answered, and its round trips.
735
+
736
+ Raises:
737
+ NotRunning: The current session is not running.
738
+ """
739
+ count = max(1, count)
740
+ if self._local:
741
+ return _public(_ping.probe_socket(None, count))
742
+ session = self.session
743
+ client, creds = self._account()
744
+ if session is None:
745
+ base_url = _ping.api_base_url(creds, self._api_url)
746
+ return _public(_ping.probe_api(creds, base_url, count))
747
+ try:
748
+ with _translated():
749
+ self._service()
750
+ except ServiceUnavailable as unreachable:
751
+ return _public(_ping.Probe(False, error=str(unreachable)))
752
+ return _public(
753
+ _ping.probe_session(client, creds, session.id, count, self._api_url)
754
+ )
755
+
756
+ def stop(
757
+ self,
758
+ *,
759
+ all: bool,
760
+ dry_run: bool = False,
761
+ wait: bool = True,
762
+ timeout: Optional[float] = None,
763
+ ) -> builtins.list[Run]:
764
+ """Stop every running machine in the current session, as `machine
765
+ stop -a` does.
766
+
767
+ Each machine checkpoints its tip first, so its run starts again
768
+ where it stopped. `Run.stop` stops one.
769
+
770
+ Example:
771
+ >>> [r.name for r in client.stop(all=True, dry_run=True)]
772
+ ['app', 'app/try-1']
773
+ >>> client.stop(all=True)
774
+
775
+ Args:
776
+ all (bool): Stop every running machine; required, as `-a` is.
777
+ dry_run (bool, optional): List what would be stopped, stopping
778
+ nothing. Defaults to False.
779
+ wait (bool, optional): Return once every machine is gone.
780
+ Defaults to True.
781
+ timeout (float, optional): Seconds to wait; None waits without a
782
+ limit.
783
+
784
+ Returns:
785
+ list[Run]: The runs stopped, or with `dry_run` those that would
786
+ be.
787
+
788
+ Raises:
789
+ InvalidArgument: `all` is False, or the client has no session.
790
+ ApiError: Some machines could not be stopped; the message names
791
+ the first.
792
+ """
793
+ _require_all(all, "Stop one run with run.stop().")
794
+ with self._connection() as client, _translated():
795
+ names = _names(client)
796
+ done, errors = _lifecycle.stop_all(
797
+ client, dry_run=dry_run, until_stopped=wait, timeout_s=timeout
798
+ )
799
+ if isinstance(done, _machines.StopDryRunResult):
800
+ return [Run(self, run_id, name) for name, run_id in done.would_stop]
801
+ _raise_first(errors, f"Stopped {done.stopped}")
802
+ return [Run(self, run_id, names.get(run_id, "")) for run_id in done.run_ids]
803
+
804
+ def wait(
805
+ self,
806
+ *runs: "Run | str",
807
+ for_: str,
808
+ all: bool = False,
809
+ interval: float = _wait.DEFAULT_INTERVAL_S,
810
+ timeout: Optional[float] = None,
811
+ ) -> None:
812
+ """Wait until runs satisfy a predicate, as `machine wait` does.
813
+
814
+ It watches without driving: other programs or threads run the
815
+ machines. With several runs, it returns once every one satisfies
816
+ it. `Run.wait` waits for one.
817
+
818
+ Example:
819
+ >>> client.wait(a, b, for_="/app:exit", timeout=600)
820
+ >>> client.wait(for_="stopped", all=True)
821
+
822
+ Args:
823
+ *runs (Run or str): The runs, as `Run` objects or names.
824
+ for_ (str): The predicate, as for `Run.wait`. The trailing
825
+ underscore avoids the Python keyword.
826
+ all (bool, optional): Wait for every running run in the session
827
+ instead of naming them. Defaults to False.
828
+ interval (float, optional): Seconds between checks. Defaults
829
+ to 1.
830
+ timeout (float, optional): Seconds to wait; None waits without a
831
+ limit, 0 checks once.
832
+
833
+ Raises:
834
+ InvalidArgument: `for_` is not a predicate, runs are named with
835
+ `all`, or none are named without it.
836
+ Timeout: It did not hold for every run within `timeout`.
837
+ NotRunning: A run stopped, so the predicate can no longer hold.
838
+ """
839
+ if all and runs:
840
+ raise InvalidArgument("Name runs or pass all=True, not both.")
841
+ if not all and not runs:
842
+ raise InvalidArgument("Run name required.")
843
+ _args.positive("interval", interval)
844
+ predicate = _args.predicate(for_)
845
+ with self._connection() as client, _translated():
846
+ if all:
847
+ live = _machines.list_machines(client, enrich=False)
848
+ ids = [m.run_id for m in live]
849
+ else:
850
+ ids = [
851
+ r.id if isinstance(r, Run) else client.resolve_run_ref(r)
852
+ for r in runs
853
+ ]
854
+ _wait.poll_all(
855
+ client, ids, predicate, timeout_s=timeout, interval_s=interval
856
+ )
857
+
858
+ def __repr__(self) -> str:
859
+ if self._session_ref is not None:
860
+ return f"Client(session={self._session_ref!r})"
861
+ return "Client()"
862
+
863
+ # -- internals -------------------------------------------------------------
864
+
865
+ def _use(self, session: Session) -> None:
866
+ """Make `session` current for this client."""
867
+ self._session_ref = session.id
868
+ self._session = session
869
+
870
+ def _forget(self, session_id: str) -> None:
871
+ """Drop `session_id` as current, when it is: it was deleted."""
872
+ self._services.pop(session_id, None)
873
+ if self._session is not None and self._session.id == session_id:
874
+ self._session_ref = None
875
+ self._session = None
876
+
877
+ def _account(self) -> tuple[api.client.Client, dict[str, Any]]:
878
+ """The account's service and the login to it, signed in once."""
879
+ if self._api is None:
880
+ with _translated():
881
+ self._api = api.auth.signed_in(self._api_url)
882
+ return self._api
883
+
884
+ def _service(self) -> _service._Service:
885
+ """The current session's service."""
886
+ if self._local:
887
+ return self._services.setdefault("", _service.local())
888
+ session = self.session
889
+ if session is None:
890
+ raise InvalidArgument(
891
+ "No session. Use one with client.sessions.use(name),"
892
+ " or create one with client.sessions.create()."
893
+ )
894
+ if session.id not in self._services:
895
+ client, creds = self._account()
896
+ self._services[session.id] = _service.of_session(
897
+ client, creds, session.id, session.name
898
+ )
899
+ return self._services[session.id]
900
+
901
+ @contextlib.contextmanager
902
+ def _connection(self) -> Generator[_ipc.Client, None, None]:
903
+ """A connection to the current session's service."""
904
+ with self._service().client() as client:
905
+ yield client
906
+
907
+ @contextlib.contextmanager
908
+ def _catalog(self) -> Generator[_run_source.RunSource, None, None]:
909
+ """Where runs are read from: the current session, else the account's
910
+ catalog."""
911
+ if self._local or self._session_ref is not None:
912
+ with self._connection() as client:
913
+ yield client
914
+ return
915
+ with self._account_catalog() as source:
916
+ yield source
917
+
918
+ @contextlib.contextmanager
919
+ def _account_catalog(
920
+ self,
921
+ ) -> Generator[_cloud_run_source.CloudRunSource, None, None]:
922
+ """The account's catalog of runs, whichever session is current."""
923
+ api_client, creds = self._account()
924
+ source = _cloud_run_source.CloudRunSource(api_client, creds)
925
+ try:
926
+ with _translated():
927
+ yield source
928
+ finally:
929
+ source.close()
930
+
931
+ @contextlib.contextmanager
932
+ def _copies(self) -> Generator[_ipc.Client, None, None]:
933
+ """A connection to the service of the session whose disk holds the
934
+ copies."""
935
+ if self._local:
936
+ raise InvalidArgument(
937
+ "The service on this machine keeps every run on its disk,"
938
+ " so it has no copies to preload or offload."
939
+ )
940
+ with self._connection() as client:
941
+ yield client
942
+
943
+ def _disk_id(self, name: str) -> str:
944
+ """The id of the account's disk `name`."""
945
+ client, creds = self._account()
946
+ with _translated():
947
+ row = api.auth.authed(creds, lambda t: client.disk_get(t, name))
948
+ return str(row["disk_id"])
949
+
950
+ def _name(self, source: _run_source.RunSource, run_id: str) -> str:
951
+ """What a run is called, read from where runs are read."""
952
+ if isinstance(source, _ipc.Client):
953
+ return _machines.display_name(source, run_id)
954
+ return _machines.catalog_name(source, run_id)
955
+
956
+ def _ops(
957
+ self,
958
+ run_id: Optional[str],
959
+ *,
960
+ op_id: Optional[int],
961
+ states: Optional[builtins.list[str]],
962
+ types: Optional[builtins.list[str]],
963
+ since: "_when.When | None",
964
+ until: "_when.When | None",
965
+ limit: Optional[int],
966
+ offset: int,
967
+ watch: bool,
968
+ timeout: Optional[float],
969
+ ) -> "builtins.list[results.Op] | Generator[builtins.list[results.Op], None, None]":
970
+ filters = _args.op_filters(op_id, states, types, _machines.OP_TYPE_CHOICES)
971
+
972
+ def read() -> builtins.list[results.Op]:
973
+ with self._connection() as client, _translated():
974
+ rows = _machines.list_ops(
975
+ client,
976
+ run_id=run_id,
977
+ op_id=op_id,
978
+ states=filters.states,
979
+ op_types=filters.types,
980
+ since=_when.unix_seconds(since),
981
+ until=_when.unix_seconds(until),
982
+ limit=limit,
983
+ offset=offset,
984
+ )
985
+ return [results.op(dataclasses.asdict(row)) for row in rows]
986
+
987
+ return _args.watched(read, _args.same, watch, timeout)
988
+
989
+ def _branches(
990
+ self,
991
+ run_id: Optional[str],
992
+ *,
993
+ running: bool,
994
+ depth: Optional[int],
995
+ since: "_when.When | None",
996
+ until: "_when.When | None",
997
+ sort: str,
998
+ reverse: bool,
999
+ limit: Optional[int],
1000
+ offset: int,
1001
+ watch: bool,
1002
+ timeout: Optional[float],
1003
+ ) -> "builtins.list[Run] | Generator[builtins.list[Run], None, None]":
1004
+ _args.check_choice("sort", sort, _sorting.BRANCH_SORT_COLS)
1005
+
1006
+ def read() -> builtins.list[tuple[str, str, str]]:
1007
+ """Each branch's id, name and execution: a branch starting or
1008
+ stopping is a change."""
1009
+ with self._catalog() as source, _translated():
1010
+ listed = source.branch_list(scope_run_id=run_id)
1011
+ liveness = _machines.catalog_liveness(source, run_id)
1012
+ page, _ = _branches.page_branches(
1013
+ listed,
1014
+ running=running,
1015
+ depth=depth,
1016
+ liveness=liveness,
1017
+ since=_when.unix_seconds(since),
1018
+ until=_when.unix_seconds(until),
1019
+ sort=sort,
1020
+ reverse=reverse,
1021
+ limit=limit,
1022
+ offset=offset,
1023
+ )
1024
+ return [
1025
+ (
1026
+ b.run_id,
1027
+ b.name,
1028
+ liveness[b.run_id].execution if b.run_id in liveness else "",
1029
+ )
1030
+ for b in page
1031
+ ]
1032
+
1033
+ def present(rows: builtins.list[tuple[str, str, str]]) -> builtins.list[Run]:
1034
+ return [Run(self, run_id, name) for run_id, name, _ in rows]
1035
+
1036
+ return _args.watched(read, present, watch, timeout)
1037
+
1038
+ def _marks(self, run_id: str) -> builtins.list[results.Mark]:
1039
+ with self._catalog() as source, _translated():
1040
+ rows = source.list_marks(run_id)
1041
+ wanted = {marked for _, marked in rows}
1042
+ names = {
1043
+ row.run_id: row.name
1044
+ for row in source.runs_query()
1045
+ if row.run_id in wanted
1046
+ }
1047
+ return [
1048
+ results.Mark(name=word, run_id=marked, run_name=names.get(marked, ""))
1049
+ for word, marked in rows
1050
+ ]
1051
+
1052
+
1053
+ class Runs:
1054
+ """The account's runs, as `Client.runs`; not created directly.
1055
+
1056
+ Call it to list runs, as `machine runs` does, and index it by name, id,
1057
+ unique id prefix or `%mark` to get one.
1058
+
1059
+ Example:
1060
+ >>> run = client.runs["app"]
1061
+ >>> [r.name for r in client.runs(states=["running"])]
1062
+ ['app', 'app/try-1']
1063
+ """
1064
+
1065
+ def __init__(self, client: Client) -> None:
1066
+ self._client = client
1067
+
1068
+ @overload
1069
+ def __call__(
1070
+ self,
1071
+ root: "Run | str | None" = ...,
1072
+ *,
1073
+ states: Optional[builtins.list[str]] = ...,
1074
+ running: bool = ...,
1075
+ roots: bool = ...,
1076
+ labels: Optional[dict[str, str]] = ...,
1077
+ flags: Optional[dict[str, int]] = ...,
1078
+ disk: "Disk | str | None" = ...,
1079
+ parents: Optional[str] = ...,
1080
+ synced: Optional[bool] = ...,
1081
+ since: "_when.When | None" = ...,
1082
+ until: "_when.When | None" = ...,
1083
+ sort: str = ...,
1084
+ reverse: bool = ...,
1085
+ limit: Optional[int] = ...,
1086
+ offset: int = ...,
1087
+ size: bool = ...,
1088
+ watch: Literal[False] = ...,
1089
+ timeout: Optional[float] = ...,
1090
+ ) -> builtins.list[Run]: ...
1091
+
1092
+ @overload
1093
+ def __call__(
1094
+ self,
1095
+ root: "Run | str | None" = ...,
1096
+ *,
1097
+ states: Optional[builtins.list[str]] = ...,
1098
+ running: bool = ...,
1099
+ roots: bool = ...,
1100
+ labels: Optional[dict[str, str]] = ...,
1101
+ flags: Optional[dict[str, int]] = ...,
1102
+ disk: "Disk | str | None" = ...,
1103
+ parents: Optional[str] = ...,
1104
+ synced: Optional[bool] = ...,
1105
+ since: "_when.When | None" = ...,
1106
+ until: "_when.When | None" = ...,
1107
+ sort: str = ...,
1108
+ reverse: bool = ...,
1109
+ limit: Optional[int] = ...,
1110
+ offset: int = ...,
1111
+ size: bool = ...,
1112
+ watch: Literal[True],
1113
+ timeout: Optional[float] = ...,
1114
+ ) -> Generator[builtins.list[Run], None, None]: ...
1115
+
1116
+ def __call__(
1117
+ self,
1118
+ root: "Run | str | None" = None,
1119
+ *,
1120
+ states: Optional[builtins.list[str]] = None,
1121
+ running: bool = False,
1122
+ roots: bool = False,
1123
+ labels: Optional[dict[str, str]] = None,
1124
+ flags: Optional[dict[str, int]] = None,
1125
+ disk: "Disk | str | None" = None,
1126
+ parents: Optional[str] = None,
1127
+ synced: Optional[bool] = None,
1128
+ since: "_when.When | None" = None,
1129
+ until: "_when.When | None" = None,
1130
+ sort: str = "created",
1131
+ reverse: bool = False,
1132
+ limit: Optional[int] = None,
1133
+ offset: int = 0,
1134
+ size: bool = False,
1135
+ watch: bool = False,
1136
+ timeout: Optional[float] = None,
1137
+ ) -> "builtins.list[Run] | Generator[builtins.list[Run], None, None]":
1138
+ """List runs, newest first, as `machine runs` does.
1139
+
1140
+ Every run and branch is returned, or those matching every filter
1141
+ given. The list is read from the catalog, so stopped runs are listed
1142
+ too, and with no session it answers from the account's catalog.
1143
+ Each run's `listing` holds its row. Every matching run is returned
1144
+ unless `limit` is given.
1145
+
1146
+ With `watch`, it yields the list at once, then again each time it
1147
+ changes: a run created or deleted, or one changing state. Leave the
1148
+ loop, or pass `timeout`, to stop watching.
1149
+
1150
+ Example:
1151
+ >>> client.runs(labels={"suite": "nightly"}, states=["^running"])
1152
+ >>> client.runs("app", sort="name")
1153
+ >>> [(r.listing.running, r.listing.runs) for r in client.runs(roots=True)]
1154
+ [(1, 3), (0, 1)]
1155
+
1156
+ Args:
1157
+ root (Run or str, optional): List one tree, by its root or any
1158
+ run in it.
1159
+ states (list[str], optional): Keep these states: `running`,
1160
+ `paused`, `halted`, `recovering`, `read-only`, `stopped`,
1161
+ `killed`, `terminated`, `died`, `failed`; `^state` leaves one
1162
+ out.
1163
+ running (bool, optional): Keep running runs, as
1164
+ `states=["running"]`. Defaults to False.
1165
+ roots (bool, optional): One run per tree, its root, with the
1166
+ tree's counts in `listing.running` and `listing.runs`.
1167
+ Defaults to False.
1168
+ labels (dict[str, str], optional): Keep runs with every one of
1169
+ these labels.
1170
+ flags (dict[str, int], optional): Keep runs whose flags match: a
1171
+ flag name, such as `rng` or `daemon`, to 1 for set or 0 for
1172
+ unset.
1173
+ disk (str, optional): Keep runs that boot this disk, by name
1174
+ or id.
1175
+ parents (str, optional): Keep runs that read their data parents
1176
+ `local` or `remote`.
1177
+ synced (bool, optional): True keeps runs published to shared
1178
+ storage, False those with nothing published.
1179
+ since (datetime or int or str, optional): Keep those created at
1180
+ or after this time: a datetime, Unix seconds, a date or an
1181
+ age such as `7d`.
1182
+ until (datetime or int or str, optional): Keep those created at
1183
+ or before this time.
1184
+ sort (str, optional): `created`, newest first, or `name`,
1185
+ `cpus`, `memory`, `rng-seed` or `limit`, lowest first.
1186
+ Defaults to `created`.
1187
+ reverse (bool, optional): Turn the order round. Defaults to
1188
+ False.
1189
+ limit (int, optional): Return at most this many.
1190
+ offset (int, optional): Skip this many first. Defaults to 0.
1191
+ size (bool, optional): Measure each run's size on the session,
1192
+ into `listing.disk_bytes` and `listing.ram_bytes`; needs a
1193
+ session. Defaults to False.
1194
+ watch (bool, optional): Yield the list each time it changes.
1195
+ Defaults to False.
1196
+ timeout (float, optional): With `watch`, end the generator after
1197
+ this many seconds, without raising; None watches until the
1198
+ caller leaves the loop.
1199
+
1200
+ Returns:
1201
+ list[Run]: The runs; with `watch`, an iterator of such lists.
1202
+
1203
+ Raises:
1204
+ InvalidArgument: A filter, sort key or time is not valid.
1205
+ """
1206
+ terms = list(states or [])
1207
+ if running:
1208
+ terms.append("running")
1209
+ for term in terms:
1210
+ _args.check_choice(
1211
+ "state", term.removeprefix("^"), _machines.CATALOG_STATE_CHOICES
1212
+ )
1213
+ for flag in flags or {}:
1214
+ _args.check_choice("flag", flag, _machines.CATALOG_FLAG_NAMES)
1215
+ _args.check_choice("parents", parents, _PARENTS)
1216
+ _args.check_choice("sort", sort, _sorting.CATALOG_SORT_COLS)
1217
+ columns: dict[str, object] = {}
1218
+ if parents is not None:
1219
+ columns["parents"] = parents
1220
+ if synced is not None:
1221
+ columns["durable_through"] = synced
1222
+ query = _machines.CatalogQuery(
1223
+ states=_machines.resolve_states(terms or None),
1224
+ disk=None if disk is None else _args.disk_ref(disk),
1225
+ filters=columns or None,
1226
+ flag_filters=dict(flags) if flags else None,
1227
+ label_filters=(
1228
+ {_machines.to_wire_label_name(k): v for k, v in labels.items()}
1229
+ if labels
1230
+ else None
1231
+ ),
1232
+ since=_when.unix_seconds(since),
1233
+ until=_when.unix_seconds(until),
1234
+ sort=_sorting.CATALOG_SORT_FIELDS[sort],
1235
+ reverse=_sorting.descending(sort, reverse),
1236
+ limit=limit,
1237
+ offset=offset,
1238
+ usage=size,
1239
+ )
1240
+ catalog = self._client._connection if size else self._client._catalog
1241
+
1242
+ def read() -> Sequence[_machines.RunRootRow | _machines.RunTreeRow]:
1243
+ with catalog() as source, _translated():
1244
+ if roots and root is None:
1245
+ return _machines.catalog_roots(source, query)
1246
+ scope = None
1247
+ if root is not None:
1248
+ ref = root.id if isinstance(root, Run) else root
1249
+ scope = _machines.tree_root(source, source.resolve_run_ref(ref))
1250
+ return _machines.catalog_runs(source, query, root=scope)
1251
+
1252
+ def present(
1253
+ rows: Sequence[_machines.RunRootRow | _machines.RunTreeRow],
1254
+ ) -> builtins.list[Run]:
1255
+ return [
1256
+ Run(self._client, row.run_id, row.name, results.listing(row))
1257
+ for row in rows
1258
+ ]
1259
+
1260
+ return _args.watched(read, present, watch, timeout)
1261
+
1262
+ def get(self, ref: str) -> Run:
1263
+ """Get a run by name, as every command that takes a run resolves
1264
+ one; `runs[ref]` does the same.
1265
+
1266
+ Args:
1267
+ ref (str): The run's name, a branch's as `root/branch`, its id, a
1268
+ prefix of the id only it has, or `%mark`.
1269
+
1270
+ Returns:
1271
+ Run: The run.
1272
+
1273
+ Raises:
1274
+ NotFound: No run matches.
1275
+ InvalidArgument: The prefix matches more than one run.
1276
+ """
1277
+ with self._client._catalog() as source, _translated():
1278
+ run_id = source.resolve_run_ref(ref)
1279
+ name = self._client._name(source, run_id)
1280
+ return Run(self._client, run_id, name)
1281
+
1282
+ def __getitem__(self, ref: str) -> Run:
1283
+ return self.get(ref)
1284
+
1285
+
1286
+ class Marks:
1287
+ """The marks of every tree, as `Client.marks`; not created directly.
1288
+
1289
+ `Run.marks` lists one tree's, and adds and removes a run's.
1290
+
1291
+ Example:
1292
+ >>> [(m.name, m.run_name) for m in client.marks.list()]
1293
+ [('found-race', 'app/try-3')]
1294
+ """
1295
+
1296
+ def __init__(self, client: Client) -> None:
1297
+ self._client = client
1298
+
1299
+ def list(self) -> builtins.list[results.Mark]:
1300
+ """List the marks of every tree, as `machine marks list` does.
1301
+
1302
+ Answers with no session, from the account's catalog.
1303
+
1304
+ Returns:
1305
+ list[Mark]: Each mark and the run that carries it.
1306
+ """
1307
+ return self._client._marks("")
1308
+
1309
+
1310
+ class Storage:
1311
+ """What the account stores, as `Client.storage`; not created directly.
1312
+
1313
+ Runs and disks live in the account's shared storage; deleting them
1314
+ frees their space once a prune reclaims it.
1315
+
1316
+ Example:
1317
+ >>> client.storage.show()["used_bytes"]
1318
+ 52428800
1319
+ >>> client.storage.prune()
1320
+ """
1321
+
1322
+ def __init__(self, client: Client) -> None:
1323
+ self._client = client
1324
+
1325
+ def show(self, *, refresh: bool = False) -> results.StorageInfo:
1326
+ """Read what the account stores and its allowance, as `machine
1327
+ storage show` does.
1328
+
1329
+ The sizes come from the last measurement, which the document dates.
1330
+ `refresh` starts a new measurement; `ops` shows it running.
1331
+
1332
+ Args:
1333
+ refresh (bool, optional): Measure again instead of reading the
1334
+ last measurement. Defaults to False.
1335
+
1336
+ Returns:
1337
+ StorageInfo: The sizes, the allowance,
1338
+ and under `prune` the current or last prune.
1339
+
1340
+ Raises:
1341
+ NotSignedIn: There are no credentials.
1342
+ """
1343
+ client, creds = self._client._account()
1344
+ with _translated():
1345
+ used = api.auth.authed(creds, lambda t: client.storage(t, refresh=refresh))
1346
+ running = api.auth.authed(creds, client.prune_status)
1347
+ return results.storage({**used, "prune": running})
1348
+
1349
+ @overload
1350
+ def ops(
1351
+ self,
1352
+ *,
1353
+ op_id: Optional[int] = ...,
1354
+ states: Optional[builtins.list[str]] = ...,
1355
+ types: Optional[builtins.list[str]] = ...,
1356
+ since: "_when.When | None" = ...,
1357
+ until: "_when.When | None" = ...,
1358
+ limit: Optional[int] = ...,
1359
+ offset: int = ...,
1360
+ watch: Literal[False] = ...,
1361
+ timeout: Optional[float] = ...,
1362
+ ) -> builtins.list[results.StorageOp]: ...
1363
+
1364
+ @overload
1365
+ def ops(
1366
+ self,
1367
+ *,
1368
+ op_id: Optional[int] = ...,
1369
+ states: Optional[builtins.list[str]] = ...,
1370
+ types: Optional[builtins.list[str]] = ...,
1371
+ since: "_when.When | None" = ...,
1372
+ until: "_when.When | None" = ...,
1373
+ limit: Optional[int] = ...,
1374
+ offset: int = ...,
1375
+ watch: Literal[True],
1376
+ timeout: Optional[float] = ...,
1377
+ ) -> Generator[builtins.list[results.StorageOp], None, None]: ...
1378
+
1379
+ def ops(
1380
+ self,
1381
+ *,
1382
+ op_id: Optional[int] = None,
1383
+ states: Optional[builtins.list[str]] = None,
1384
+ types: Optional[builtins.list[str]] = None,
1385
+ since: "_when.When | None" = None,
1386
+ until: "_when.When | None" = None,
1387
+ limit: Optional[int] = None,
1388
+ offset: int = 0,
1389
+ watch: bool = False,
1390
+ timeout: Optional[float] = None,
1391
+ ) -> "builtins.list[results.StorageOp] | Generator[builtins.list[results.StorageOp], None, None]":
1392
+ """List the account's storage operations, newest first, as `machine
1393
+ storage ops` does.
1394
+
1395
+ A storage operation is a measurement, a prune or a check. The list is
1396
+ every operation in every state; `states` keeps some. Every matching
1397
+ operation is returned unless `limit` is given.
1398
+ With `watch`, it yields the list at once, then again each time it
1399
+ changes, such as a prune finishing.
1400
+
1401
+ Example:
1402
+ >>> client.storage.ops(states=["failed"], since="1d")
1403
+ [{'op_id': '42', 'op_type': 'prune', 'state': 'failed', ...}]
1404
+
1405
+ Args:
1406
+ op_id (int, optional): Return this operation alone, whatever its
1407
+ state or type.
1408
+ states (list[str], optional): Keep these states: `pending`,
1409
+ `running`, `done`, `failed`; `^state` leaves one out.
1410
+ Defaults to every state.
1411
+ types (list[str], optional): Keep these types: `measure`,
1412
+ `prune`, `verify`, `check`; `^type` leaves one out. Defaults
1413
+ to every type.
1414
+ since (datetime or int or str, optional): Keep those started at
1415
+ or after this time: a datetime, Unix seconds, a date or an
1416
+ age such as `7d`.
1417
+ until (datetime or int or str, optional): Keep those started at
1418
+ or before this time.
1419
+ limit (int, optional): Return at most this many.
1420
+ offset (int, optional): Skip this many first. Defaults to 0.
1421
+ watch (bool, optional): Yield the list each time it changes.
1422
+ Defaults to False.
1423
+ timeout (float, optional): With `watch`, end the generator after
1424
+ this many seconds, without raising; None watches until the
1425
+ caller leaves the loop.
1426
+
1427
+ Returns:
1428
+ list[StorageOp]: One record per operation: its id,
1429
+ type, state, start time and error; with `watch`, an iterator of
1430
+ such lists.
1431
+
1432
+ Raises:
1433
+ InvalidArgument: A state, type or time is not valid.
1434
+ NotSignedIn: There are no credentials.
1435
+ """
1436
+ filters = _args.op_filters(
1437
+ op_id,
1438
+ states,
1439
+ types,
1440
+ _machines.STORAGE_OP_TYPE_CHOICES,
1441
+ _machines.STORAGE_OP_STATE_CHOICES,
1442
+ )
1443
+
1444
+ def read() -> builtins.list[results.StorageOp]:
1445
+ with self._client._account_catalog() as source:
1446
+ rows = _machines.list_storage_ops(
1447
+ source,
1448
+ op_id=op_id,
1449
+ states=filters.states,
1450
+ op_types=filters.types,
1451
+ since=_when.unix_seconds(since),
1452
+ until=_when.unix_seconds(until),
1453
+ limit=limit,
1454
+ offset=offset,
1455
+ )
1456
+ return [results.storage_op(dataclasses.asdict(row)) for row in rows]
1457
+
1458
+ return _args.watched(read, _args.same, watch, timeout)
1459
+
1460
+ def prune(self, *, status: bool = False) -> Optional[results.Prune]:
1461
+ """Start reclaiming the space deleted runs and disks still hold, as
1462
+ `machine storage prune` does.
1463
+
1464
+ The prune runs on the service after this returns; `status` and `ops`
1465
+ show it. It needs the account's storage to itself, so it is refused
1466
+ while any session is running: `sessions.delete(all=True)` first.
1467
+
1468
+ Args:
1469
+ status (bool, optional): Return the current or last prune
1470
+ instead of starting one. Defaults to False.
1471
+
1472
+ Returns:
1473
+ Prune: The prune; with `status`,
1474
+ None when there has been none.
1475
+
1476
+ Raises:
1477
+ Conflict: A session is running.
1478
+ NotSignedIn: There are no credentials.
1479
+ """
1480
+ client, creds = self._client._account()
1481
+ with _translated():
1482
+ if status:
1483
+ row: Optional[dict[str, Any]] = api.auth.authed(
1484
+ creds, client.prune_status
1485
+ )
1486
+ return None if row is None else results.prune(row)
1487
+ started: dict[str, Any] = api.auth.authed(creds, client.prune_start)
1488
+ return results.prune(started)
1489
+
1490
+ def check(
1491
+ self,
1492
+ *,
1493
+ wait: bool = True,
1494
+ timeout: Optional[float] = None,
1495
+ status: bool = False,
1496
+ ) -> Optional[results.StorageCheck]:
1497
+ """Read every object of the account's storage back and check it
1498
+ against its name, as `machine storage check` does.
1499
+
1500
+ Nothing is written and nothing is locked, so it runs beside sessions
1501
+ and beside a prune. The check runs on the service: it goes on when a
1502
+ wait here ends, and `ops` lists it. One runs at a time, and asking
1503
+ while one runs follows that one.
1504
+
1505
+ Example:
1506
+ >>> found = client.storage.check()
1507
+ >>> (found.state, found.failed, found.unreadable)
1508
+ ('done', 0, [])
1509
+
1510
+ Args:
1511
+ wait (bool, optional): Return once the check has ended. Defaults
1512
+ to True.
1513
+ timeout (float, optional): Seconds to wait; None waits without a
1514
+ limit.
1515
+ status (bool, optional): Return the current or last check
1516
+ instead of starting one. Defaults to False.
1517
+
1518
+ Returns:
1519
+ StorageCheck: The check, with `state` `failed` and `unreadable`
1520
+ filled in when an object could not be read; with `status`, None
1521
+ when there has been none.
1522
+
1523
+ Raises:
1524
+ Conflict: The account has no storage yet.
1525
+ Timeout: The check had not ended within `timeout`. It goes on.
1526
+ NotSignedIn: There are no credentials.
1527
+ """
1528
+ client, creds = self._client._account()
1529
+ with _translated():
1530
+ if status:
1531
+ last: Optional[dict[str, Any]] = api.auth.authed(
1532
+ creds, client.storage_check
1533
+ )
1534
+ return None if last is None else results.storage_check(last)
1535
+ row: dict[str, Any] = api.auth.authed(creds, client.storage_check_start)
1536
+ if wait:
1537
+ row = _storage_ops.wait_check(
1538
+ lambda: api.auth.authed(creds, client.storage_check),
1539
+ row,
1540
+ timeout_s=timeout,
1541
+ )
1542
+ return results.storage_check(row)
1543
+
1544
+
1545
+ class Delete:
1546
+ """Deleting runs, as `Client.delete`; not created directly.
1547
+
1548
+ Call it to delete every run in the current session, or every run that
1549
+ boots a disk, as `machine delete -a` and `machine delete --disk` do.
1550
+ `cleanup` resumes deletes that were interrupted. `Run.delete` deletes
1551
+ one run and its branches.
1552
+
1553
+ Example:
1554
+ >>> client.delete(disk="app", dry_run=True)
1555
+ []
1556
+ >>> client.delete.cleanup().recovered
1557
+ 0
1558
+ """
1559
+
1560
+ def __init__(self, client: "Client") -> None:
1561
+ self._client = client
1562
+
1563
+ def __call__(
1564
+ self,
1565
+ *,
1566
+ all: bool = False,
1567
+ disk: "Disk | str | None" = None,
1568
+ stop: bool = False,
1569
+ force: bool = False,
1570
+ dry_run: bool = False,
1571
+ timeout: Optional[float] = None,
1572
+ ) -> builtins.list["Run"]:
1573
+ """Delete every run in the current session, or every run that boots
1574
+ a disk, as `machine delete -a` and `machine delete --disk` do.
1575
+
1576
+ `timeout` bounds the whole call. Run out part way, the run it
1577
+ stopped at goes on being deleted and the rest were not started.
1578
+
1579
+ `Run.delete` deletes one run and its branches; `cleanup` resumes
1580
+ deletes that were interrupted.
1581
+
1582
+ Example:
1583
+ >>> [r.name for r in client.delete(disk="app", dry_run=True)]
1584
+ ['app', 'app/try-1']
1585
+ >>> client.delete(all=True, stop=True)
1586
+
1587
+ Args:
1588
+ all (bool, optional): Delete every run in the session. Defaults
1589
+ to False.
1590
+ disk (str, optional): Delete every run that boots this disk,
1591
+ by name or id, whichever session it is in.
1592
+ stop (bool, optional): Kill running machines first. Defaults to
1593
+ False.
1594
+ force (bool, optional): As `stop`, and delete a run whose machine
1595
+ is already gone or was replaced. Defaults to False.
1596
+ dry_run (bool, optional): List what would be deleted or
1597
+ recovered, acting on nothing. Defaults to False.
1598
+ timeout (float, optional): Seconds to wait for every run to be
1599
+ gone; None waits without a limit.
1600
+
1601
+ Returns:
1602
+ list[Run]: The runs deleted, or with `dry_run` those that would
1603
+ be.
1604
+
1605
+ Raises:
1606
+ InvalidArgument: Neither `all` nor `disk` is given, both are,
1607
+ or the client has no session.
1608
+ NotFound: No run boots `disk`.
1609
+ ApiError: Some runs could not be deleted; the message names the
1610
+ first.
1611
+ """
1612
+ if all == (disk is not None):
1613
+ raise InvalidArgument(
1614
+ "Pass all=True or disk=, not both."
1615
+ if all
1616
+ else "Delete one run with run.delete(), or pass all=True or disk=."
1617
+ )
1618
+ stop = stop or force
1619
+ deadline = None if timeout is None else time.monotonic() + timeout
1620
+ rows = []
1621
+ if disk is not None:
1622
+ # Which runs boot a disk is the account's question: it holds the
1623
+ # disks, and a session's service has none.
1624
+ if self._client._local:
1625
+ raise InvalidArgument(
1626
+ "disk= needs a session: the local service has no account disks."
1627
+ )
1628
+ with self._client._account_catalog() as source, _translated():
1629
+ rows = _lifecycle.booting(source, _args.disk_ref(disk))
1630
+ with self._client._connection() as client, _translated():
1631
+ names = _names(client)
1632
+ if disk is not None:
1633
+ done, errors = _lifecycle.delete_by_disk(
1634
+ client,
1635
+ rows,
1636
+ force=stop,
1637
+ force_override=force,
1638
+ dry_run=dry_run,
1639
+ deadline=deadline,
1640
+ )
1641
+ else:
1642
+ done, errors = _lifecycle.delete_all(
1643
+ client,
1644
+ force=stop,
1645
+ force_override=force,
1646
+ dry_run=dry_run,
1647
+ deadline=deadline,
1648
+ )
1649
+ if isinstance(done, _machines.DeleteDryRunResult):
1650
+ return [
1651
+ Run(self._client, run_id, name) for name, run_id in done.would_delete
1652
+ ]
1653
+ _raise_first(errors, f"Deleted {done.deleted}")
1654
+ return [
1655
+ Run(self._client, run_id, names.get(run_id, "")) for run_id in done.run_ids
1656
+ ]
1657
+
1658
+ def cleanup(
1659
+ self, *, full_scan: bool = False, dry_run: bool = False
1660
+ ) -> results.Recovery:
1661
+ """Resume deletes that were interrupted, as `machine delete --cleanup -a`
1662
+ does.
1663
+
1664
+ A delete that stopped part way leaves a marker; this finishes the
1665
+ work each one names.
1666
+
1667
+ Args:
1668
+ full_scan (bool, optional): Scan every branch instead of the
1669
+ recorded roots, for a marker the index lost. Defaults to
1670
+ False.
1671
+ dry_run (bool, optional): List what would be recovered, doing
1672
+ nothing. Defaults to False.
1673
+
1674
+ Returns:
1675
+ Recovery: What it finished, what it left, and what went wrong.
1676
+
1677
+ Raises:
1678
+ InvalidArgument: The client has no session.
1679
+ """
1680
+ with self._client._connection() as client, _translated():
1681
+ return results.recovery(
1682
+ dataclasses.asdict(
1683
+ _machines.delete_cleanup(
1684
+ client, full_scan=full_scan, dry_run=dry_run
1685
+ )
1686
+ )
1687
+ )
1688
+
1689
+
1690
+ class Preload:
1691
+ """Copies onto the current session's disk, as `Client.preload`; not
1692
+ created directly.
1693
+
1694
+ A run is kept in shared storage and copied to a session's disk when it
1695
+ starts there; preloading copies it ahead of time, so starting it does
1696
+ not wait for the download. Call it with `all=True` to copy everything
1697
+ the session's runs need, as `machine preload -a` does. `Run.preload`
1698
+ copies one run.
1699
+
1700
+ Example:
1701
+ >>> client.preload(all=True)
1702
+ >>> client.preload.disk("app")
1703
+ """
1704
+
1705
+ def __init__(self, client: Client) -> None:
1706
+ self._client = client
1707
+
1708
+ def __call__(self, *, all: bool, timeout: Optional[float] = None) -> None:
1709
+ """Copy every run folder and boot disk the session's runs need, as
1710
+ `machine preload -a` does.
1711
+
1712
+ Args:
1713
+ all (bool): Copy everything; required, as `-a` is.
1714
+ timeout (float, optional): Seconds to wait for the copies; None
1715
+ waits without a limit.
1716
+
1717
+ Raises:
1718
+ InvalidArgument: `all` is False, or the client has no session.
1719
+ Timeout: The copies did not finish within `timeout`.
1720
+ """
1721
+ _require_all(all, "Preload one run with run.preload().")
1722
+ with self._client._copies() as client, _translated():
1723
+ _machines.preload_all_both(client, timeout_s=timeout)
1724
+
1725
+ def run(self, *, all: bool, timeout: Optional[float] = None) -> None:
1726
+ """Copy every data parent the session's runs need, as `machine
1727
+ preload run -a` does. `Run.preload` copies one run.
1728
+
1729
+ Args:
1730
+ all (bool): Copy every one; required, as `-a` is.
1731
+ timeout (float, optional): Seconds to wait for the copies; None
1732
+ waits without a limit.
1733
+
1734
+ Raises:
1735
+ InvalidArgument: `all` is False, or the client has no session.
1736
+ Timeout: The copies did not finish within `timeout`.
1737
+ """
1738
+ _require_all(all, "Preload one run with run.preload().")
1739
+ with self._client._copies() as client, _translated():
1740
+ _machines.preload_all(client, timeout_s=timeout)
1741
+
1742
+ def disk(
1743
+ self,
1744
+ disk: "Disk | str | None" = None,
1745
+ *,
1746
+ all: bool = False,
1747
+ timeout: Optional[float] = None,
1748
+ ) -> None:
1749
+ """Copy a disk onto the session, as `machine preload disk` does, so
1750
+ creating a run from it does not wait for the download.
1751
+
1752
+ Args:
1753
+ disk (str, optional): The disk's name or id.
1754
+ all (bool, optional): Copy every boot disk the session's runs
1755
+ need instead. Defaults to False.
1756
+ timeout (float, optional): Seconds to wait for the copy; None
1757
+ waits without a limit.
1758
+
1759
+ Raises:
1760
+ InvalidArgument: Neither or both of `disk` and `all` are given,
1761
+ or the client has no session.
1762
+ NotFound: No disk has this name.
1763
+ Timeout: The copy did not finish within `timeout`.
1764
+ """
1765
+ with self._client._copies() as client, _translated():
1766
+ if _one_or_all(disk, all) is None:
1767
+ _machines.preload_all(client, timeout_s=timeout, disks=True)
1768
+ else:
1769
+ digest = self._client._disk_id(str(disk))
1770
+ _machines.preload_disk(client, digest, timeout_s=timeout)
1771
+
1772
+
1773
+ class Offload:
1774
+ """Copies dropped from the current session, as `Client.offload`;
1775
+ not created directly.
1776
+
1777
+ Offloading frees the session's storage; the runs and disks stay in shared
1778
+ storage and are copied back when a run needs them. Call it with no
1779
+ arguments to list what can be dropped, as `machine offload` does, or
1780
+ with `all=True` to drop all of it. `Run.offload` drops one run.
1781
+
1782
+ Example:
1783
+ >>> client.offload()["runs"]
1784
+ [{'run_id': 'whAK...', 'name': 'app', 'disk_bytes': 52428800, ...}]
1785
+ >>> client.offload(all=True)
1786
+ """
1787
+
1788
+ def __init__(self, client: Client) -> None:
1789
+ self._client = client
1790
+
1791
+ def __call__(
1792
+ self,
1793
+ *,
1794
+ all: bool,
1795
+ runs: bool = False,
1796
+ disks: bool = False,
1797
+ timeout: Optional[float] = None,
1798
+ ) -> None:
1799
+ """Drop every copy not in use, as `machine offload -a` does.
1800
+
1801
+ `list` reads what can be dropped; this drops it. `Run.offload` drops
1802
+ one run, and `disk` one disk.
1803
+
1804
+ Example:
1805
+ >>> client.offload(all=True)
1806
+ >>> [c.name for c in client.offload.list().runs]
1807
+ []
1808
+
1809
+ Args:
1810
+ all (bool): Drop every one; required, as `-a` is.
1811
+ runs (bool, optional): Only the session's run folders. Defaults
1812
+ to False.
1813
+ disks (bool, optional): Only the session's disk files.
1814
+ Defaults to False.
1815
+ timeout (float, optional): Seconds to wait; None waits without a
1816
+ limit.
1817
+
1818
+ Raises:
1819
+ InvalidArgument: `all` is False, or the client has no session.
1820
+ """
1821
+ _require_all(all, "Read what can be dropped with client.offload.list().")
1822
+ both = runs == disks
1823
+ with self._client._copies() as client, _translated():
1824
+ if both:
1825
+ _machines.offload_all_both(client, timeout_s=timeout)
1826
+ else:
1827
+ _machines.offload_all(client, timeout_s=timeout, disks=disks)
1828
+
1829
+ def list(self, *, runs: bool = False, disks: bool = False) -> results.Copies:
1830
+ """List the session's copies that can be dropped, as `machine
1831
+ offload list` does.
1832
+
1833
+ Only copies not in use are listed; the rest are counted.
1834
+
1835
+ Args:
1836
+ runs (bool, optional): Only the session's run folders. Defaults
1837
+ to False.
1838
+ disks (bool, optional): Only the session's disk files.
1839
+ Defaults to False.
1840
+
1841
+ Returns:
1842
+ Copies: The run folders and the disk files it holds.
1843
+
1844
+ Raises:
1845
+ InvalidArgument: The client has no session.
1846
+ """
1847
+ both = runs == disks
1848
+ with self._client._copies() as client, _translated():
1849
+ return results.copies(
1850
+ _machines.cache_list(
1851
+ client, runs=runs or both, disks=disks or both
1852
+ ).to_json()
1853
+ )
1854
+
1855
+ def run(self, *, all: bool, timeout: Optional[float] = None) -> None:
1856
+ """Drop every run folder not in use, as `machine offload run -a`
1857
+ does. `Run.offload` drops one run.
1858
+
1859
+ Args:
1860
+ all (bool): Drop every one; required, as `-a` is.
1861
+ timeout (float, optional): Seconds to wait; None waits without a
1862
+ limit.
1863
+
1864
+ Raises:
1865
+ InvalidArgument: `all` is False, or the client has no session.
1866
+ """
1867
+ _require_all(all, "Offload one run with run.offload().")
1868
+ with self._client._copies() as client, _translated():
1869
+ _machines.offload_all(client, timeout_s=timeout)
1870
+
1871
+ def disk(
1872
+ self,
1873
+ disk: "Disk | str | None" = None,
1874
+ *,
1875
+ all: bool = False,
1876
+ timeout: Optional[float] = None,
1877
+ ) -> None:
1878
+ """Drop the session's copy of a disk, as `machine offload disk`
1879
+ does. The disk stays in the account.
1880
+
1881
+ Args:
1882
+ disk (str, optional): The disk's name or id.
1883
+ all (bool, optional): Drop every disk not in use instead.
1884
+ Defaults to False.
1885
+ timeout (float, optional): Seconds to wait; None waits without a
1886
+ limit.
1887
+
1888
+ Raises:
1889
+ InvalidArgument: Neither or both of `disk` and `all` are given,
1890
+ or the client has no session.
1891
+ NotFound: No disk has this name.
1892
+ Conflict: A running machine uses the copy.
1893
+ """
1894
+ with self._client._copies() as client, _translated():
1895
+ if _one_or_all(disk, all) is None:
1896
+ _machines.offload_all(client, timeout_s=timeout, disks=True)
1897
+ else:
1898
+ digest = self._client._disk_id(str(disk))
1899
+ _machines.offload_disk(client, digest, timeout_s=timeout)
1900
+
1901
+
1902
+ def _require_all(all: bool, hint: str) -> None:
1903
+ """InvalidArgument unless `all`, the only form a many-run command has."""
1904
+ if not all:
1905
+ raise InvalidArgument(f"Pass all=True. {hint}")
1906
+
1907
+
1908
+ def _one_or_all(name: "Disk | str | None", all: bool) -> Optional[str]:
1909
+ """The disk named, or None for `all`; InvalidArgument unless exactly one
1910
+ is given. A `Disk` names itself, as a run and a session do."""
1911
+ if (name is None) == (not all):
1912
+ raise InvalidArgument("Name a disk, or pass all=True.")
1913
+ return None if name is None else _args.disk_ref(name)
1914
+
1915
+
1916
+ def _names(client: _ipc.Client) -> dict[str, str]:
1917
+ """Every run's name by id, read before a many-run command removes them."""
1918
+ return {b.run_id: b.name for b in client.branch_list()}
1919
+
1920
+
1921
+ def _raise_first(errors: builtins.list[str], done: str) -> None:
1922
+ """ApiError naming the first of `errors`, when there are any."""
1923
+ if errors:
1924
+ raise ApiError(f"{done}, {len(errors)} failed; first {errors[0]}")