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.
- testflows/machine/v1/__init__.py +278 -0
- testflows/machine/v1/_args.py +528 -0
- testflows/machine/v1/_requires.py +103 -0
- testflows/machine/v1/_service.py +109 -0
- testflows/machine/v1/_version.py +16 -0
- testflows/machine/v1/_when.py +55 -0
- testflows/machine/v1/client.py +1924 -0
- testflows/machine/v1/disks.py +669 -0
- testflows/machine/v1/errors.py +255 -0
- testflows/machine/v1/login.py +107 -0
- testflows/machine/v1/ping.py +70 -0
- testflows/machine/v1/results.py +3231 -0
- testflows/machine/v1/runs.py +7648 -0
- testflows/machine/v1/sessions.py +751 -0
- testflows_machine-0.1.0.dist-info/METADATA +116 -0
- testflows_machine-0.1.0.dist-info/RECORD +20 -0
- testflows_machine-0.1.0.dist-info/WHEEL +5 -0
- testflows_machine-0.1.0.dist-info/licenses/LICENSE +203 -0
- testflows_machine-0.1.0.dist-info/licenses/NOTICE +7 -0
- testflows_machine-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -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
|
+
)
|