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,669 @@
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
+ """Disks: the account's catalog of what runs boot from."""
15
+
16
+ from __future__ import annotations
17
+
18
+ import builtins
19
+ import dataclasses
20
+ import shutil
21
+ import tempfile
22
+ from dataclasses import dataclass
23
+ from pathlib import Path
24
+ from typing import Any, Generator, Literal, Optional, overload
25
+
26
+ from testflows.machine._core import api
27
+ from testflows.machine._core import bake as _bake
28
+ from testflows.machine._core import build as _build
29
+ from testflows.machine._core import disks as _disks
30
+ from testflows.machine._core import storage_ops as _storage_ops
31
+ from . import _args
32
+ from . import _when
33
+ from . import results
34
+ from .errors import InvalidArgument, _translated
35
+
36
+
37
+ @dataclass(frozen=True)
38
+ class Disk:
39
+ """One disk: a name for its content, identified by its SHA-256.
40
+
41
+ Attributes:
42
+ name (str): The disk's name, unique in the account.
43
+ id (str): The content's SHA-256, `sha256:<hex>`.
44
+ size_bytes (int): The content's size in bytes.
45
+ state (str): `ready` once its content is verified, `transferring`
46
+ while a build is under way.
47
+ created_at (str, optional): When the disk was created, ISO 8601.
48
+ labels (dict[str, str]): What the build attached to this name. A run
49
+ created from this disk inherits them.
50
+ data_bytes (int, optional): The bytes the disk takes in account
51
+ storage, after deduplication and compression. A piece it shares
52
+ with another disk is counted in both. None when the disk has not
53
+ been measured.
54
+ """
55
+
56
+ name: str
57
+ id: str
58
+ size_bytes: int
59
+ state: str
60
+ created_at: Optional[str]
61
+ labels: dict[str, str] = dataclasses.field(default_factory=dict)
62
+ data_bytes: Optional[int] = None
63
+
64
+ def as_json(self) -> dict[str, Any]:
65
+ """The fields as a JSON-serializable dict.
66
+
67
+ Returns:
68
+ dict[str, Any]: One key per attribute.
69
+ """
70
+ return dataclasses.asdict(self)
71
+
72
+
73
+ class Disks:
74
+ """The account's disks, as `Client.disks`; not created directly.
75
+
76
+ Call it to list them, as `machine disks` does. A disk is what a run
77
+ boots: `Client.create` takes a disk's name. They belong to the account,
78
+ so every call here answers with no session.
79
+
80
+ Example:
81
+ >>> disk = client.disks.build("app", binary="build/app")
82
+ >>> [d.name for d in client.disks()]
83
+ ['app']
84
+ """
85
+
86
+ def __init__(self, client: api.client.Client, creds: dict[str, Any]) -> None:
87
+ self._client = client
88
+ self._creds = creds
89
+
90
+ @overload
91
+ def __call__(
92
+ self,
93
+ *,
94
+ deleted: bool = ...,
95
+ since: "_when.When | None" = ...,
96
+ limit: Optional[int] = ...,
97
+ offset: int = ...,
98
+ label: Optional[dict[str, str]] = ...,
99
+ watch: Literal[False] = ...,
100
+ timeout: Optional[float] = ...,
101
+ ) -> builtins.list[Disk]: ...
102
+
103
+ @overload
104
+ def __call__(
105
+ self,
106
+ *,
107
+ deleted: bool = ...,
108
+ since: "_when.When | None" = ...,
109
+ limit: Optional[int] = ...,
110
+ offset: int = ...,
111
+ label: Optional[dict[str, str]] = ...,
112
+ watch: Literal[True],
113
+ timeout: Optional[float] = ...,
114
+ ) -> Generator[builtins.list[Disk], None, None]: ...
115
+
116
+ def __call__(
117
+ self,
118
+ *,
119
+ deleted: bool = False,
120
+ since: "_when.When | None" = None,
121
+ limit: Optional[int] = None,
122
+ offset: int = 0,
123
+ label: Optional[dict[str, str]] = None,
124
+ watch: bool = False,
125
+ timeout: Optional[float] = None,
126
+ ) -> "builtins.list[Disk] | Generator[builtins.list[Disk], None, None]":
127
+ """List the account's disks, as `machine disks` does; the same as
128
+ `list`.
129
+
130
+ Args:
131
+ deleted (bool, optional): List the disks that were removed
132
+ instead. Defaults to False.
133
+ since (datetime or int or str, optional): Keep those created, or
134
+ removed, at or after this time.
135
+ limit (int, optional): List at most this many; None lists all.
136
+ offset (int, optional): Skip this many first. Defaults to 0.
137
+ label (dict[str, str], optional): Keep only the disks carrying
138
+ every one of these labels, by exact value.
139
+ watch (bool, optional): Yield the list each time it changes.
140
+ Defaults to False.
141
+ timeout (float, optional): With `watch`, end the generator after
142
+ this many seconds, without raising; None watches until the
143
+ caller leaves the loop.
144
+
145
+ Returns:
146
+ list[Disk]: The disks; with `watch`, an iterator of such lists.
147
+ """
148
+ return _args.watched(
149
+ lambda: self._list(deleted, since, limit, offset, label),
150
+ _args.same,
151
+ watch,
152
+ timeout,
153
+ )
154
+
155
+ @overload
156
+ def list(
157
+ self,
158
+ *,
159
+ deleted: bool = ...,
160
+ since: "_when.When | None" = ...,
161
+ limit: Optional[int] = ...,
162
+ offset: int = ...,
163
+ label: Optional[dict[str, str]] = ...,
164
+ watch: Literal[False] = ...,
165
+ timeout: Optional[float] = ...,
166
+ ) -> builtins.list[Disk]: ...
167
+
168
+ @overload
169
+ def list(
170
+ self,
171
+ *,
172
+ deleted: bool = ...,
173
+ since: "_when.When | None" = ...,
174
+ limit: Optional[int] = ...,
175
+ offset: int = ...,
176
+ label: Optional[dict[str, str]] = ...,
177
+ watch: Literal[True],
178
+ timeout: Optional[float] = ...,
179
+ ) -> Generator[builtins.list[Disk], None, None]: ...
180
+
181
+ def list(
182
+ self,
183
+ *,
184
+ deleted: bool = False,
185
+ since: "_when.When | None" = None,
186
+ limit: Optional[int] = None,
187
+ offset: int = 0,
188
+ label: Optional[dict[str, str]] = None,
189
+ watch: bool = False,
190
+ timeout: Optional[float] = None,
191
+ ) -> "builtins.list[Disk] | Generator[builtins.list[Disk], None, None]":
192
+ """List the account's disks, newest first, as `machine disks list`
193
+ does.
194
+
195
+ Every disk is returned unless `limit` is given. With `watch`, it
196
+ yields the list at once, then again each time it changes: a disk
197
+ added, renamed, deleted, or finishing its transfer. Use it to wait
198
+ for an upload another program started.
199
+
200
+ Example:
201
+ >>> [d.name for d in client.disks.list(since="7d")]
202
+ ['app', 'app-debug']
203
+ >>> for disks in client.disks.list(watch=True, timeout=600):
204
+ ... if any(d.name == "app" and d.state == "ready" for d in disks):
205
+ ... break
206
+
207
+ Args:
208
+ deleted (bool, optional): List the disks that were removed
209
+ instead. Defaults to False.
210
+ since (datetime or int or str, optional): Keep those created, or
211
+ removed, at or after this time: a datetime, Unix seconds, a
212
+ date such as `2026-06-01` or an age such as `7d`.
213
+ limit (int, optional): List at most this many; None lists all.
214
+ offset (int, optional): Skip this many first. Defaults to 0.
215
+ label (dict[str, str], optional): Keep only the disks carrying
216
+ every one of these labels, by exact value.
217
+ watch (bool, optional): Yield the list each time it changes.
218
+ Defaults to False.
219
+ timeout (float, optional): With `watch`, end the generator after
220
+ this many seconds, without raising; None watches until the
221
+ caller leaves the loop.
222
+
223
+ Returns:
224
+ list[Disk]: The disks; with `watch`, an iterator of such lists.
225
+
226
+ Raises:
227
+ InvalidArgument: `since` is not a time.
228
+ NotSignedIn: There are no credentials.
229
+ """
230
+ return _args.watched(
231
+ lambda: self._list(deleted, since, limit, offset, label),
232
+ _args.same,
233
+ watch,
234
+ timeout,
235
+ )
236
+
237
+ def build(
238
+ self,
239
+ name: Optional[str] = None,
240
+ *,
241
+ binary: "str | Path | None" = None,
242
+ from_: Optional[str] = None,
243
+ image: Optional[str] = None,
244
+ compose: "str | Path | None" = None,
245
+ entrypoint: Optional[str] = None,
246
+ command: Optional[builtins.list[str]] = None,
247
+ add: Optional[builtins.list[str]] = None,
248
+ env: Optional[dict[str, str]] = None,
249
+ label: Optional[dict[str, str]] = None,
250
+ size: Optional[int] = None,
251
+ load_at_boot: bool = False,
252
+ ) -> Disk:
253
+ """Build a disk, as `machine disks build` does.
254
+
255
+ Exactly one source. `binary` wraps a static x86_64 executable in an
256
+ image built around it. `from_` names a public image, which the build
257
+ pulls. Neither needs Docker. `image` takes a Docker image, as a save
258
+ tar or a name in the local Docker. `compose` takes a project directory
259
+ and the images its services name.
260
+
261
+ A binary or an image runs as one container; a project runs every
262
+ service in it. The build itself runs in the account, so the platform
263
+ the disk is made of is never the caller's to supply.
264
+
265
+ With `from_` or `binary`, `add` puts files in the image as one more
266
+ layer. An entry is `path` or `path:dest`. Without a destination the
267
+ path lands in the image's working directory under its own name; a
268
+ destination ending in `/` is a directory.
269
+
270
+ Example:
271
+ >>> disk = client.disks.build("app", binary="build/app", command=["--port", "8080"])
272
+ >>> run = client.create(disk=disk.name)
273
+ >>> hello = client.disks.build(
274
+ ... "hello", from_="python:3.12", add=["hello.py"], command=["python", "hello.py"]
275
+ ... )
276
+ >>> stack = client.disks.build("stack", compose="./deploy")
277
+
278
+ Args:
279
+ name (str, optional): The disk's name; defaults to what the source
280
+ is called.
281
+ binary (str or Path, optional): A static x86_64 executable.
282
+ from_ (str, optional): A public image, by name.
283
+ image (str, optional): A Docker image, by save tar or by name.
284
+ compose (str or Path, optional): A Compose project directory.
285
+ entrypoint (str, optional): The executable the service runs. Not
286
+ for `compose`, whose file says.
287
+ command (list[str], optional): Arguments the service runs with.
288
+ Not for `compose`, whose file says.
289
+ add (list[str], optional): Files and directories to put in the
290
+ image, each `path` or `path:dest`. For `from_` and `binary`.
291
+ env (dict[str, str], optional): Environment variables the service
292
+ runs with. Not for `compose`, whose file says. The disk holds
293
+ each value as written.
294
+ label (dict[str, str], optional): Labels to attach to the name,
295
+ replacing whatever it carried. A run created from this disk
296
+ inherits them. An empty value removes one.
297
+ size (int, optional): The disk's size in MB, which is the size of
298
+ the guest's root filesystem. Defaults to what the source needs
299
+ plus a gigabyte, rounded up to a whole GB. The platform takes
300
+ about 285MB of it, the images take what they unpack to, and
301
+ the rest is what the guest can write. A size below what the
302
+ source needs is refused.
303
+ load_at_boot (bool): Keep the images on the disk as save tars
304
+ that Docker loads each time the disk boots. By default the
305
+ build writes them into the disk's Docker store, and the disk
306
+ boots with every image present. A guest that runs `docker
307
+ save` or `docker push` on one of them needs this. Such a disk
308
+ holds each image twice and is sized for both.
309
+
310
+ Returns:
311
+ Disk: The disk built.
312
+
313
+ Raises:
314
+ InvalidArgument: No source, more than one, a source the build
315
+ cannot use, or a project a disk cannot run.
316
+ Conflict: A transfer to the name is under way, or runs still boot
317
+ what the name holds.
318
+ """
319
+ named = [
320
+ n
321
+ for n in ("binary", "from_", "image", "compose")
322
+ if locals()[n] is not None
323
+ ]
324
+ if len(named) != 1:
325
+ raise InvalidArgument(
326
+ "Pass exactly one of binary=, from_=, image= or compose=,"
327
+ f" not {len(named)}."
328
+ )
329
+ kind = named[0]
330
+ source = str(binary or from_ or image or compose)
331
+ entry = [entrypoint] if entrypoint else None
332
+ disk_name = name or _build.default_name(source)
333
+ if add and kind not in ("binary", "from_"):
334
+ raise InvalidArgument(f"add= goes with from_= or binary=, not {kind}=.")
335
+ with _translated():
336
+ added = [_build.parse_added(spec) for spec in add or []]
337
+ # A project takes no env= at all, and is told that below: checking
338
+ # the names first would refuse a malformed one for its name.
339
+ environment = (
340
+ {} if kind == "compose" else _build.checked_environment(env or {})
341
+ )
342
+ if kind == "binary":
343
+ pack = _build.pack_from_binary(
344
+ Path(source),
345
+ tag=f"{disk_name}:built",
346
+ entrypoint=entry,
347
+ command=command,
348
+ added=added,
349
+ environment=environment,
350
+ )
351
+ elif kind == "from_":
352
+ pack = _build.pack_from_registry(
353
+ source,
354
+ tag=f"{disk_name}:built",
355
+ entrypoint=entry,
356
+ command=command,
357
+ added=added,
358
+ environment=environment,
359
+ )
360
+ elif kind == "image":
361
+ pack = _build.pack_from_image(
362
+ source, entrypoint=entry, command=command, environment=environment
363
+ )
364
+ else:
365
+ if entry or command or env:
366
+ raise InvalidArgument(
367
+ "compose= takes no entrypoint=, no env= and no command=;"
368
+ " set them on the service in the compose file."
369
+ )
370
+ pack = _build.pack_from_compose(Path(source))
371
+ if load_at_boot:
372
+ pack = _build.loading_at_boot(pack)
373
+ footprint = pack.footprint
374
+ disk_mb = footprint.default_mb if size is None else size
375
+ if disk_mb < footprint.needed_mb:
376
+ pack.remove()
377
+ raise InvalidArgument(
378
+ f"size={disk_mb} is smaller than {disk_name} needs: the platform"
379
+ f" and the images take {footprint.used_mb}MB before the machine"
380
+ f" writes anything, and its volumes grow to"
381
+ f" {footprint.volumes_mb}MB."
382
+ )
383
+ carried = Path(tempfile.mkdtemp(prefix="machine-build-")) / f"{disk_name}.pack"
384
+ try:
385
+ with _translated():
386
+ _bake.pack_tar(pack, carried)
387
+ _disks.build(
388
+ self._client,
389
+ self._creds,
390
+ carried,
391
+ disk_name,
392
+ labels=label,
393
+ disk_mb=disk_mb,
394
+ )
395
+ finally:
396
+ pack.remove()
397
+ shutil.rmtree(carried.parent, ignore_errors=True)
398
+ return self.show(disk_name)
399
+
400
+ def show(self, name: "Disk | str") -> Disk:
401
+ """Read a disk, as `machine disks show` does.
402
+
403
+ Args:
404
+ name (str): The disk's name.
405
+
406
+ Returns:
407
+ Disk: The disk.
408
+
409
+ Raises:
410
+ NotFound: No disk has this name.
411
+ """
412
+ named = _args.disk_ref(name)
413
+ with _translated():
414
+ row = api.auth.authed(
415
+ self._creds, lambda t: self._client.disk_get(t, named)
416
+ )
417
+ return _disk(row)
418
+
419
+ def verify(
420
+ self,
421
+ name: "Disk | str",
422
+ *,
423
+ wait: bool = True,
424
+ timeout: Optional[float] = None,
425
+ ) -> results.StorageOp:
426
+ """Check a stored disk against its id, as `machine disks verify`
427
+ does.
428
+
429
+ The disk is read back out of storage and its id computed again, which
430
+ is what it is stored under. The check runs on the service: it goes on
431
+ when a wait here ends, and `Storage.ops` lists it. One runs at a time
432
+ for an account.
433
+
434
+ Example:
435
+ >>> client.disks.verify("app").state
436
+ 'done'
437
+
438
+ Args:
439
+ name (str): The disk's name.
440
+ wait (bool, optional): Return once the check has ended. Defaults
441
+ to True.
442
+ timeout (float, optional): Seconds to wait; None waits without a
443
+ limit.
444
+
445
+ Returns:
446
+ StorageOp: The check. `state` is `done` for a disk that reads as
447
+ it was stored, and `failed` with `error` saying what was wrong.
448
+ With `wait` False it is the check as it started.
449
+
450
+ Raises:
451
+ NotFound: No disk has this name.
452
+ Conflict: A check is already running, or the disk is still
453
+ uploading.
454
+ Timeout: The check had not ended within `timeout`. It goes on.
455
+ """
456
+ named = _args.disk_ref(name)
457
+ with _translated():
458
+ started = api.auth.authed(
459
+ self._creds, lambda t: self._client.disk_verify(t, named)
460
+ )
461
+ op_id = int(started["op_id"])
462
+
463
+ def read() -> dict[str, Any]:
464
+ rows = api.auth.authed(
465
+ self._creds, lambda t: self._client.op_list(t, op_id=op_id)
466
+ )
467
+ if not rows:
468
+ raise RuntimeError(f"disk check {op_id} is not listed")
469
+ return dict(rows[0])
470
+
471
+ if not wait:
472
+ return results.storage_op(read())
473
+ return results.storage_op(
474
+ _storage_ops.wait_op(
475
+ read, what=f"the check of {named}", timeout_s=timeout
476
+ )
477
+ )
478
+
479
+ @overload
480
+ def transfers(
481
+ self,
482
+ *,
483
+ active: bool = ...,
484
+ since: "_when.When | None" = ...,
485
+ watch: Literal[False] = ...,
486
+ timeout: Optional[float] = ...,
487
+ ) -> builtins.list[results.Transfer]: ...
488
+
489
+ @overload
490
+ def transfers(
491
+ self,
492
+ *,
493
+ active: bool = ...,
494
+ since: "_when.When | None" = ...,
495
+ watch: Literal[True],
496
+ timeout: Optional[float] = ...,
497
+ ) -> Generator[builtins.list[results.Transfer], None, None]: ...
498
+
499
+ def transfers(
500
+ self,
501
+ *,
502
+ active: bool = False,
503
+ since: "_when.When | None" = None,
504
+ watch: bool = False,
505
+ timeout: Optional[float] = None,
506
+ ) -> "builtins.list[results.Transfer] | Generator[builtins.list[results.Transfer], None, None]":
507
+ """List uploads, as `machine disks transfers` does.
508
+
509
+ Without `since`, the transfers under way; with it, the history from
510
+ then on as well. With `watch`, it yields the list at once, then again
511
+ each time it changes, progress included.
512
+
513
+ Args:
514
+ active (bool, optional): With `since`, keep only those under way.
515
+ Defaults to False.
516
+ since (datetime or int or str, optional): List every transfer
517
+ from this time on, finished ones included: a datetime, Unix
518
+ seconds, a date or an age such as `7d`.
519
+ watch (bool, optional): Yield the list each time it changes.
520
+ Defaults to False.
521
+ timeout (float, optional): With `watch`, end the generator after
522
+ this many seconds, without raising; None watches until the
523
+ caller leaves the loop.
524
+
525
+ Returns:
526
+ list[Transfer]: One record per transfer, with its progress and
527
+ speed; with `watch`, an iterator of such lists.
528
+
529
+ Raises:
530
+ InvalidArgument: `since` is not a time, or `active` was given
531
+ without it: the list is already only what is under way.
532
+ """
533
+ cutoff = _when.iso(since)
534
+ if active and cutoff is None:
535
+ raise InvalidArgument(
536
+ "active= needs since=: without it the list is only what is"
537
+ " under way."
538
+ )
539
+
540
+ def read() -> builtins.list[results.Transfer]:
541
+ with _translated():
542
+ if cutoff is None:
543
+ rows: builtins.list[dict[str, Any]] = api.auth.authed(
544
+ self._creds, self._client.transfers_list
545
+ )
546
+ else:
547
+ rows = api.auth.authed(
548
+ self._creds,
549
+ lambda t: self._client.transfers_list(
550
+ t, since=cutoff, active=active
551
+ ),
552
+ )
553
+ return [results.transfer(row) for row in rows]
554
+
555
+ return _args.watched(read, _args.same, watch, timeout)
556
+
557
+ def delete(self, *names: "Disk | str", force: bool = False) -> None:
558
+ """Delete disks, as `machine disks delete` does.
559
+
560
+ Deletion is permanent. The name is free as soon as this returns, and
561
+ the disk reads as `deleting` until its bytes are reclaimed, which is
562
+ when they stop counting against the storage quota. A disk that runs
563
+ still boot is refused unless `force` is True; with it, those runs can
564
+ no longer start. A deleted disk is listed by `list(deleted=True)`.
565
+
566
+ Example:
567
+ >>> client.disks.delete("app-old", "app-debug")
568
+
569
+ Args:
570
+ *names (str): The disks' names.
571
+ force (bool, optional): Delete even while runs still boot them.
572
+ Defaults to False.
573
+
574
+ Raises:
575
+ InvalidArgument: No name is given.
576
+ NotFound: No disk has one of the names.
577
+ Conflict: Runs boot one and `force` is False, or a transfer to
578
+ one is under way.
579
+ """
580
+ if not names:
581
+ raise InvalidArgument("Disk name required.")
582
+ for name in names:
583
+ with _translated():
584
+ api.auth.authed(
585
+ self._creds,
586
+ lambda t: self._client.disk_delete(
587
+ t, _args.disk_ref(name), force=force
588
+ ),
589
+ )
590
+
591
+ def rename(self, name: "Disk | str", new_name: str) -> Disk:
592
+ """Rename a disk, as `machine disks rename` does.
593
+
594
+ Args:
595
+ name (str): The disk's name.
596
+ new_name (str): Its new name.
597
+
598
+ Returns:
599
+ Disk: The disk, renamed.
600
+
601
+ Raises:
602
+ InvalidArgument: `new_name` is not a valid disk name.
603
+ NotFound: No disk has the name `name`.
604
+ Conflict: A disk has the name `new_name`, or a transfer to
605
+ `name` is under way.
606
+ """
607
+ if not _disks.valid_name(new_name):
608
+ raise InvalidArgument(f"Invalid disk name {new_name!r}.")
609
+ with _translated():
610
+ api.auth.authed(
611
+ self._creds,
612
+ lambda t: self._client.disk_rename(t, _args.disk_ref(name), new_name),
613
+ )
614
+ return self.show(new_name)
615
+
616
+ def cancel(self, name: "Disk | str") -> None:
617
+ """Cancel the transfer to a disk, as `machine disks cancel` does.
618
+
619
+ Use it when an upload was interrupted and still holds the name, which
620
+ refuses a new upload, a rename and a delete of that name.
621
+
622
+ Args:
623
+ name (str): The disk's name.
624
+
625
+ Raises:
626
+ NotFound: No transfer to the disk is under way.
627
+ """
628
+ with _translated():
629
+ api.auth.authed(
630
+ self._creds,
631
+ lambda t: self._client.disk_cancel(t, _args.disk_ref(name)),
632
+ )
633
+
634
+ def _list(
635
+ self,
636
+ deleted: bool,
637
+ since: "_when.When | None",
638
+ limit: Optional[int],
639
+ offset: int,
640
+ label: Optional[dict[str, str]] = None,
641
+ ) -> builtins.list[Disk]:
642
+ cutoff = _when.iso(since)
643
+ with _translated():
644
+ rows = api.auth.authed(
645
+ self._creds,
646
+ lambda t: self._client.disk_list(
647
+ t,
648
+ deleted=deleted,
649
+ since=cutoff,
650
+ limit=limit,
651
+ offset=offset,
652
+ labels=label,
653
+ ),
654
+ )
655
+ return [_disk(row) for row in rows]
656
+
657
+
658
+ def _disk(row: dict[str, Any]) -> Disk:
659
+ """The public form of a disk row."""
660
+ created = row.get("created_at")
661
+ return Disk(
662
+ labels={str(k): str(v) for k, v in (row.get("labels") or {}).items()},
663
+ name=str(row["name"]),
664
+ id=str(row["disk_id"]),
665
+ size_bytes=int(row.get("size_bytes") or 0),
666
+ state=str(row.get("state") or ""),
667
+ created_at=None if created is None else str(created),
668
+ data_bytes=None if row.get("data_bytes") is None else int(row["data_bytes"]),
669
+ )