virtx 0.2.0__py3-none-win_amd64.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.
- virtx/__init__.py +136 -0
- virtx/_cli.py +21 -0
- virtx/_library.py +337 -0
- virtx/client.py +494 -0
- virtx/files.py +146 -0
- virtx/image.py +288 -0
- virtx/job.py +75 -0
- virtx/portforward.py +67 -0
- virtx/project.py +91 -0
- virtx/py.typed +0 -0
- virtx/sandbox.py +254 -0
- virtx/virtx_core.dll +0 -0
- virtx/volume.py +147 -0
- virtx-0.2.0.dist-info/METADATA +108 -0
- virtx-0.2.0.dist-info/RECORD +17 -0
- virtx-0.2.0.dist-info/WHEEL +4 -0
- virtx-0.2.0.dist-info/entry_points.txt +2 -0
virtx/client.py
ADDED
|
@@ -0,0 +1,494 @@
|
|
|
1
|
+
"""The client: a ``VirtxClient*`` held, and each request of ``virtx.h`` as a method."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import atexit
|
|
6
|
+
import ctypes
|
|
7
|
+
import json
|
|
8
|
+
import os
|
|
9
|
+
import weakref
|
|
10
|
+
from collections.abc import AsyncIterator, Callable, Iterable, Mapping
|
|
11
|
+
from dataclasses import dataclass
|
|
12
|
+
from typing import Any, Generic, Self, TypeVar
|
|
13
|
+
|
|
14
|
+
from ._library import OK, Library, VirtxError, _Bytes, library
|
|
15
|
+
from ._library import args as _args
|
|
16
|
+
from .image import (
|
|
17
|
+
BearerAuth,
|
|
18
|
+
ImageDownloadOutput,
|
|
19
|
+
ImageJob,
|
|
20
|
+
ImageJobEntry,
|
|
21
|
+
ImageListOutputItem,
|
|
22
|
+
ImageName,
|
|
23
|
+
ImagePruneOutput,
|
|
24
|
+
ImageUploadOutput,
|
|
25
|
+
Recipe,
|
|
26
|
+
RegistryAuth,
|
|
27
|
+
image_name,
|
|
28
|
+
)
|
|
29
|
+
from .job import StartedJob
|
|
30
|
+
from .project import Project
|
|
31
|
+
from .sandbox import Sandbox, SandboxVolume
|
|
32
|
+
from .volume import Volume
|
|
33
|
+
|
|
34
|
+
T = TypeVar("T")
|
|
35
|
+
C = TypeVar("C")
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
@dataclass(frozen=True)
|
|
39
|
+
class Progress(Generic[C]):
|
|
40
|
+
"""A notification about a request: how far it has got, what that will reach when known, and
|
|
41
|
+
its ``content``, if it sent one, such as a line of its log."""
|
|
42
|
+
|
|
43
|
+
progress: int
|
|
44
|
+
total: int | None = None
|
|
45
|
+
content: C | None = None
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
@dataclass(frozen=True)
|
|
49
|
+
class Output(Generic[T]):
|
|
50
|
+
"""What a request answered, after its progress."""
|
|
51
|
+
|
|
52
|
+
value: T
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
Event = Output[T] | Progress[C]
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def _event(item: Mapping[str, Any], output: Callable[[Any], T]) -> Event[T, Any]:
|
|
59
|
+
if "progress" in item:
|
|
60
|
+
progress = item["progress"]
|
|
61
|
+
return Progress(progress["progress"], progress.get("total"), progress.get("content"))
|
|
62
|
+
return Output(output(item["output"]))
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
# Every client not yet closed, closed at exit: a hold left to the interpreter's teardown would
|
|
66
|
+
# end its session after the waker's callbacks can still run.
|
|
67
|
+
def _header_array(headers: Mapping[str, str] | None) -> ctypes.Array[ctypes.c_char_p]:
|
|
68
|
+
"""``headers`` as ``virtx_client_connect`` takes them: each name then its value."""
|
|
69
|
+
strings = [s.encode() for name, value in (headers or {}).items() for s in (name, value)]
|
|
70
|
+
return (ctypes.c_char_p * len(strings))(*strings)
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
@dataclass(frozen=True)
|
|
74
|
+
class CommandAuth:
|
|
75
|
+
"""The token ``program`` with ``args`` prints, sent as ``Authorization: Bearer <token>``:
|
|
76
|
+
a token alone, or ``{"token": ..., "expires_in": <seconds>}``. It is run for the first
|
|
77
|
+
request, and again when its token is a minute from running out or the server refuses it:
|
|
78
|
+
a person's short-lived token, as ``virtx token --json`` prints it."""
|
|
79
|
+
|
|
80
|
+
program: str
|
|
81
|
+
args: tuple[str, ...] = ()
|
|
82
|
+
|
|
83
|
+
def to_dict(self) -> dict[str, Any]:
|
|
84
|
+
"""As the wire has it."""
|
|
85
|
+
return {"type": "command", "program": self.program, "args": list(self.args)}
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
Auth = BearerAuth | CommandAuth
|
|
89
|
+
"""The credentials a server wants with every request."""
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def _auth_bytes(auth: Auth | None) -> bytes:
|
|
93
|
+
"""``auth`` as ``virtx_client_connect`` takes it: JSON, or nothing for none."""
|
|
94
|
+
return b"" if auth is None else json.dumps(auth.to_dict()).encode()
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
_open: weakref.WeakSet[Client] = weakref.WeakSet()
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
@atexit.register
|
|
101
|
+
def _close_all() -> None:
|
|
102
|
+
for client in list(_open):
|
|
103
|
+
client.close()
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
async def ensure_virtx() -> str:
|
|
107
|
+
"""Fetch ``virtx-stdio``, the server of the library's version, into this host's cache if it
|
|
108
|
+
is not there, and give its path: what ``Client.spawn()`` without a program starts.
|
|
109
|
+
|
|
110
|
+
The server is kept one directory per version, so a library that is upgraded fetches its
|
|
111
|
+
own. ``$VIRTX_STDIO`` names a server to use as it is; ``$VIRTX_STDIO_VERSION`` another
|
|
112
|
+
version; ``$VIRTX_DIST_URL`` where releases are fetched from; ``$VIRTX_HOME`` the cache.
|
|
113
|
+
"""
|
|
114
|
+
lib = library()
|
|
115
|
+
return await lib.answer(lib.virtx_ensure_virtx())
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
class Client:
|
|
119
|
+
"""A client of one server, over stdio or HTTP, made by ``libvirtx_core``.
|
|
120
|
+
|
|
121
|
+
Each method is a coroutine, or an async iterator for a request that streams: a job's log,
|
|
122
|
+
or the progress of a download or upload. One that starts a job answers a ``StartedJob``,
|
|
123
|
+
both.
|
|
124
|
+
Holds of one session are counted: ``clone`` takes another, ``close`` lets this one go, and
|
|
125
|
+
the session ends with the last, which answers every request still waiting with an error.
|
|
126
|
+
"""
|
|
127
|
+
|
|
128
|
+
def __init__(self, raw: int, lib: Library) -> None:
|
|
129
|
+
self._raw: int | None = raw
|
|
130
|
+
self._lib = lib
|
|
131
|
+
_open.add(self)
|
|
132
|
+
|
|
133
|
+
@classmethod
|
|
134
|
+
def spawn(cls, program: str | None = None, args: Iterable[str] = ()) -> Client:
|
|
135
|
+
"""Start ``program`` with ``args`` as the server, and talk to it over its stdin and
|
|
136
|
+
stdout. Without ``program``, the server is ``virtx-stdio`` of this library's version,
|
|
137
|
+
fetched first if this host has none -- blocking for the fetch; ``ensure_virtx`` does
|
|
138
|
+
that fetch alone, on the event loop."""
|
|
139
|
+
lib = library()
|
|
140
|
+
if program is None:
|
|
141
|
+
program = lib.wait(lib.virtx_ensure_virtx())
|
|
142
|
+
argv = [arg.encode() for arg in args]
|
|
143
|
+
array = (ctypes.c_char_p * len(argv))(*argv)
|
|
144
|
+
raw = ctypes.c_void_p()
|
|
145
|
+
error = _Bytes()
|
|
146
|
+
status = lib.virtx_client_spawn(
|
|
147
|
+
program.encode(),
|
|
148
|
+
array,
|
|
149
|
+
len(argv),
|
|
150
|
+
ctypes.byref(raw),
|
|
151
|
+
ctypes.byref(error),
|
|
152
|
+
)
|
|
153
|
+
return cls._opened(lib, status, raw, error)
|
|
154
|
+
|
|
155
|
+
@classmethod
|
|
156
|
+
def connect(
|
|
157
|
+
cls,
|
|
158
|
+
url: str,
|
|
159
|
+
auth: Auth | None = None,
|
|
160
|
+
project: str | None = None,
|
|
161
|
+
headers: Mapping[str, str] | None = None,
|
|
162
|
+
) -> Client:
|
|
163
|
+
"""Reach the server at ``url``, its base ``http`` or ``https`` URL, sending ``auth``, the
|
|
164
|
+
credentials it wants, ``project``, the project every request is in (the user's own
|
|
165
|
+
without one), and ``headers``, whatever else it asks of each request, with
|
|
166
|
+
every request. ``Authorization`` is ``auth``'s, and ``virtx-project`` names ``project``,
|
|
167
|
+
over one given as a header. Refused when a token would go in the clear: over ``http`` to
|
|
168
|
+
any host but this machine."""
|
|
169
|
+
lib = library()
|
|
170
|
+
auth_json = _auth_bytes(auth)
|
|
171
|
+
array = _header_array(headers)
|
|
172
|
+
raw = ctypes.c_void_p()
|
|
173
|
+
error = _Bytes()
|
|
174
|
+
status = lib.virtx_client_connect(
|
|
175
|
+
url.encode(),
|
|
176
|
+
auth_json,
|
|
177
|
+
len(auth_json),
|
|
178
|
+
array,
|
|
179
|
+
len(array) // 2,
|
|
180
|
+
ctypes.byref(raw),
|
|
181
|
+
ctypes.byref(error),
|
|
182
|
+
)
|
|
183
|
+
client = cls._opened(lib, status, raw, error)
|
|
184
|
+
try:
|
|
185
|
+
client.set_project(project)
|
|
186
|
+
except BaseException:
|
|
187
|
+
client.close()
|
|
188
|
+
raise
|
|
189
|
+
return client
|
|
190
|
+
|
|
191
|
+
def set_auth(self, auth: Auth | None) -> None:
|
|
192
|
+
"""Send ``auth`` with every request from now on, in place of what was given at
|
|
193
|
+
``connect``: a new token, when the server's are short-lived. A forwarder already open
|
|
194
|
+
sends it with its next connection. Over stdio, where none is sent, nothing changes.
|
|
195
|
+
Refused as at ``connect``, the auth unchanged."""
|
|
196
|
+
auth_json = _auth_bytes(auth)
|
|
197
|
+
error = _Bytes()
|
|
198
|
+
status = self._lib.virtx_client_set_auth(
|
|
199
|
+
self._held(), auth_json, len(auth_json), ctypes.byref(error)
|
|
200
|
+
)
|
|
201
|
+
if status != OK:
|
|
202
|
+
self._lib.take(status, error)
|
|
203
|
+
|
|
204
|
+
def set_headers(self, headers: Mapping[str, str]) -> None:
|
|
205
|
+
"""Send ``headers`` with every request from now on, in place of those given at
|
|
206
|
+
``connect``. A forwarder already open sends them with its next connection. Over stdio,
|
|
207
|
+
where none are sent, nothing changes. A header that cannot be sent raises, the headers
|
|
208
|
+
unchanged."""
|
|
209
|
+
array = _header_array(headers)
|
|
210
|
+
error = _Bytes()
|
|
211
|
+
status = self._lib.virtx_client_set_headers(
|
|
212
|
+
self._held(), array, len(array) // 2, ctypes.byref(error)
|
|
213
|
+
)
|
|
214
|
+
if status != OK:
|
|
215
|
+
self._lib.take(status, error)
|
|
216
|
+
|
|
217
|
+
def set_project(self, project: str | None) -> None:
|
|
218
|
+
"""Name ``project`` in every request from now on, over either transport, in place of a
|
|
219
|
+
``virtx-project`` among the headers given. With ``None``, that header names it where
|
|
220
|
+
there is one, and otherwise none is named, for the user's own project. A name no header
|
|
221
|
+
carries raises, the project unchanged."""
|
|
222
|
+
error = _Bytes()
|
|
223
|
+
status = self._lib.virtx_client_set_project(
|
|
224
|
+
self._held(), None if project is None else project.encode(), ctypes.byref(error)
|
|
225
|
+
)
|
|
226
|
+
if status != OK:
|
|
227
|
+
self._lib.take(status, error)
|
|
228
|
+
|
|
229
|
+
@classmethod
|
|
230
|
+
def _opened(cls, lib: Library, status: int, raw: ctypes.c_void_p, error: _Bytes) -> Client:
|
|
231
|
+
if status == OK and raw.value:
|
|
232
|
+
return cls(raw.value, lib)
|
|
233
|
+
lib.take(status, error)
|
|
234
|
+
raise VirtxError(f"unknown status {status}")
|
|
235
|
+
|
|
236
|
+
@classmethod
|
|
237
|
+
def from_raw(cls, raw: int) -> Client:
|
|
238
|
+
"""Take over one hold of the ``VirtxClient*`` ``raw``, as ``into_raw`` or C's
|
|
239
|
+
``virtx_client_retain`` gave it, made by the library this process opened."""
|
|
240
|
+
return cls(raw, library())
|
|
241
|
+
|
|
242
|
+
def as_raw(self) -> int:
|
|
243
|
+
"""The ``VirtxClient*`` this holds, still held by it."""
|
|
244
|
+
return self._held()
|
|
245
|
+
|
|
246
|
+
def into_raw(self) -> int:
|
|
247
|
+
"""Give up this hold of the ``VirtxClient*``, for whoever takes the pointer to release.
|
|
248
|
+
This client is closed after."""
|
|
249
|
+
raw = self._held()
|
|
250
|
+
self._raw = None
|
|
251
|
+
_open.discard(self)
|
|
252
|
+
return raw
|
|
253
|
+
|
|
254
|
+
def clone(self) -> Client:
|
|
255
|
+
"""Another hold of the same session."""
|
|
256
|
+
raw = self._held()
|
|
257
|
+
self._lib.virtx_client_retain(raw)
|
|
258
|
+
return Client(raw, self._lib)
|
|
259
|
+
|
|
260
|
+
def close(self) -> None:
|
|
261
|
+
"""Let go of this hold; the last ends the session, blocking until it has. Closing twice
|
|
262
|
+
does nothing."""
|
|
263
|
+
raw = self._let_go()
|
|
264
|
+
if raw is not None:
|
|
265
|
+
self._lib.wait(self._lib.virtx_client_release(raw))
|
|
266
|
+
|
|
267
|
+
async def aclose(self) -> None:
|
|
268
|
+
"""``close``, awaited on the event loop."""
|
|
269
|
+
raw = self._let_go()
|
|
270
|
+
if raw is not None:
|
|
271
|
+
await self._lib.answer(self._lib.virtx_client_release(raw))
|
|
272
|
+
|
|
273
|
+
def _let_go(self) -> int | None:
|
|
274
|
+
raw, self._raw = self._raw, None
|
|
275
|
+
_open.discard(self)
|
|
276
|
+
return raw
|
|
277
|
+
|
|
278
|
+
def __enter__(self) -> Self:
|
|
279
|
+
return self
|
|
280
|
+
|
|
281
|
+
def __exit__(self, *exc: object) -> None:
|
|
282
|
+
self.close()
|
|
283
|
+
|
|
284
|
+
async def __aenter__(self) -> Self:
|
|
285
|
+
return self
|
|
286
|
+
|
|
287
|
+
async def __aexit__(self, *exc: object) -> None:
|
|
288
|
+
await self.aclose()
|
|
289
|
+
|
|
290
|
+
def __del__(self) -> None:
|
|
291
|
+
if getattr(self, "_raw", None) is not None:
|
|
292
|
+
self.close()
|
|
293
|
+
|
|
294
|
+
def _held(self) -> int:
|
|
295
|
+
if self._raw is None:
|
|
296
|
+
raise VirtxError("the client is closed")
|
|
297
|
+
return self._raw
|
|
298
|
+
|
|
299
|
+
async def _call(self, name: str, args: bytes | None = None, *, raw: bool = False) -> Any:
|
|
300
|
+
start = getattr(self._lib, name)
|
|
301
|
+
held = self._held()
|
|
302
|
+
handle = start(held) if args is None else start(held, args, len(args))
|
|
303
|
+
return await self._lib.answer(handle, raw)
|
|
304
|
+
|
|
305
|
+
def _items(self, name: str, args: bytes) -> AsyncIterator[Any]:
|
|
306
|
+
handle = getattr(self._lib, name)(self._held(), args, len(args))
|
|
307
|
+
return self._lib.items(handle)
|
|
308
|
+
|
|
309
|
+
async def _events(
|
|
310
|
+
self, name: str, args: bytes, output: Callable[[Any], T]
|
|
311
|
+
) -> AsyncIterator[Event[T, Any]]:
|
|
312
|
+
async for item in self._items(name, args):
|
|
313
|
+
yield _event(item, output)
|
|
314
|
+
|
|
315
|
+
def _image_job(self, name: str, args: bytes) -> StartedJob[ImageJob, ImageJobEntry]:
|
|
316
|
+
async def start() -> ImageJob:
|
|
317
|
+
return ImageJob.from_dict(self, await self._call(name, args))
|
|
318
|
+
|
|
319
|
+
return StartedJob(start, lambda job: job.log())
|
|
320
|
+
|
|
321
|
+
def build_image(
|
|
322
|
+
self, recipe: Recipe | Mapping[str, Any], reference: str
|
|
323
|
+
) -> StartedJob[ImageJob, ImageJobEntry]:
|
|
324
|
+
"""Build ``recipe``, to point ``reference`` at what it builds: awaited, the job;
|
|
325
|
+
iterated, its log, as ``ImageJob.log``'s; ``complete``, its digest, as
|
|
326
|
+
``ImageJob.complete``'s. Sent when first awaited, iterated or completed."""
|
|
327
|
+
recipe = recipe.to_dict() if isinstance(recipe, Recipe) else recipe
|
|
328
|
+
return self._image_job(
|
|
329
|
+
"virtx_client_build_image", _args(recipe=recipe, reference=reference)
|
|
330
|
+
)
|
|
331
|
+
|
|
332
|
+
def pull_image(
|
|
333
|
+
self, reference: str, auth: RegistryAuth | None = None
|
|
334
|
+
) -> StartedJob[ImageJob, ImageJobEntry]:
|
|
335
|
+
"""Pull ``reference`` from its registry, to point it at what it pulls; without ``auth``
|
|
336
|
+
the server pulls anonymously. Awaited, the job; iterated, its log, as
|
|
337
|
+
``ImageJob.log``'s; ``complete``, its digest, as ``ImageJob.complete``'s. Sent when first
|
|
338
|
+
awaited, iterated or completed."""
|
|
339
|
+
return self._image_job(
|
|
340
|
+
"virtx_client_pull_image", _args(reference=reference, auth=auth and auth.to_dict())
|
|
341
|
+
)
|
|
342
|
+
|
|
343
|
+
def push_image(
|
|
344
|
+
self, reference: str, auth: RegistryAuth | None = None
|
|
345
|
+
) -> StartedJob[ImageJob, ImageJobEntry]:
|
|
346
|
+
"""Push the image ``reference`` points at to the registry ``reference`` names; without
|
|
347
|
+
``auth`` the server pushes anonymously. Awaited, the job; iterated, its log, as
|
|
348
|
+
``ImageJob.log``'s; ``complete``, its digest, as ``ImageJob.complete``'s. Sent when first
|
|
349
|
+
awaited, iterated or completed."""
|
|
350
|
+
return self._image_job(
|
|
351
|
+
"virtx_client_push_image", _args(reference=reference, auth=auth and auth.to_dict())
|
|
352
|
+
)
|
|
353
|
+
|
|
354
|
+
async def list_image_job(self) -> list[ImageJob]:
|
|
355
|
+
"""Every image job the server holds."""
|
|
356
|
+
items = await self._call("virtx_client_list_image_job")
|
|
357
|
+
return [ImageJob.from_dict(self, item) for item in items]
|
|
358
|
+
|
|
359
|
+
async def get_image_job(self, id: str) -> ImageJob:
|
|
360
|
+
"""The image job ``id``."""
|
|
361
|
+
output = await self._call("virtx_client_get_image_job", _args(id=id))
|
|
362
|
+
return ImageJob.from_dict(self, output)
|
|
363
|
+
|
|
364
|
+
async def list_image(self) -> list[ImageListOutputItem]:
|
|
365
|
+
"""Every tag on the server's images, as ``name:tag``, with the digest it points at."""
|
|
366
|
+
items = await self._call("virtx_client_list_image")
|
|
367
|
+
return [ImageListOutputItem.from_dict(item) for item in items]
|
|
368
|
+
|
|
369
|
+
async def tag_image(self, source: str, target: str) -> None:
|
|
370
|
+
"""Point the tag ``target`` (``name:tag``) at the image ``source`` names (``name:tag`` or
|
|
371
|
+
``name@algorithm:hex``), moving it if it is in use."""
|
|
372
|
+
await self._call("virtx_client_tag_image", _args(source=source, target=target))
|
|
373
|
+
|
|
374
|
+
async def untag_image(self, reference: str) -> None:
|
|
375
|
+
"""Remove the tag ``reference`` (``name:tag``), leaving the image it points at."""
|
|
376
|
+
await self._call("virtx_client_untag_image", _args(reference=reference))
|
|
377
|
+
|
|
378
|
+
async def remove_image(self, reference: str) -> None:
|
|
379
|
+
"""Remove the image ``reference`` names (``name:tag`` or ``name@algorithm:hex``), and
|
|
380
|
+
every tag on it in that name."""
|
|
381
|
+
await self._call("virtx_client_remove_image", _args(reference=reference))
|
|
382
|
+
|
|
383
|
+
def download_image(
|
|
384
|
+
self, reference: str, path: str | os.PathLike[str]
|
|
385
|
+
) -> AsyncIterator[Event[ImageDownloadOutput, str]]:
|
|
386
|
+
"""Write the image ``reference`` names to ``path``, as an OCI image layout in a tar
|
|
387
|
+
archive, replacing what is there once all of it is written. Its events are a line of log
|
|
388
|
+
a blob, then what it wrote."""
|
|
389
|
+
return self._events(
|
|
390
|
+
"virtx_client_download_image",
|
|
391
|
+
_args(reference=reference, path=os.fspath(path)),
|
|
392
|
+
ImageDownloadOutput.from_dict,
|
|
393
|
+
)
|
|
394
|
+
|
|
395
|
+
def upload_image(
|
|
396
|
+
self, path: str | os.PathLike[str], reference: str
|
|
397
|
+
) -> AsyncIterator[Event[ImageUploadOutput, str]]:
|
|
398
|
+
"""Upload the image in the OCI image layout archive at ``path``, and point the tag
|
|
399
|
+
``reference`` (``name:tag``) at it: the archive's only image, or the one it names by that
|
|
400
|
+
tag. Its events are a line of log a blob, then what it uploaded."""
|
|
401
|
+
return self._events(
|
|
402
|
+
"virtx_client_upload_image",
|
|
403
|
+
_args(path=os.fspath(path), reference=reference),
|
|
404
|
+
ImageUploadOutput.from_dict,
|
|
405
|
+
)
|
|
406
|
+
|
|
407
|
+
async def prune_image(self) -> ImagePruneOutput:
|
|
408
|
+
"""Delete each image no tag points at and no sandbox uses, and what only such images
|
|
409
|
+
held."""
|
|
410
|
+
return ImagePruneOutput.from_dict(await self._call("virtx_client_prune_image"))
|
|
411
|
+
|
|
412
|
+
async def list_project(self) -> list[Project]:
|
|
413
|
+
"""Every project the client has a role in."""
|
|
414
|
+
items = await self._call("virtx_client_list_project")
|
|
415
|
+
return [Project.from_dict(self, item) for item in items]
|
|
416
|
+
|
|
417
|
+
async def create_project(self, name: str) -> Project:
|
|
418
|
+
"""Make the project ``name``, the client its owner."""
|
|
419
|
+
output = await self._call("virtx_client_create_project", _args(name=name))
|
|
420
|
+
return Project.from_dict(self, output)
|
|
421
|
+
|
|
422
|
+
async def get_project(self, name: str) -> Project:
|
|
423
|
+
"""The project ``name`` names -- a project of the user's by name, or any by its id --
|
|
424
|
+
with the client's role in it."""
|
|
425
|
+
output = await self._call("virtx_client_get_project", _args(name=name))
|
|
426
|
+
return Project.from_dict(self, output)
|
|
427
|
+
|
|
428
|
+
async def list_volume(self) -> list[Volume]:
|
|
429
|
+
"""Every volume the server holds."""
|
|
430
|
+
items = await self._call("virtx_client_list_volume")
|
|
431
|
+
return [Volume.from_dict(self, item) for item in items]
|
|
432
|
+
|
|
433
|
+
async def create_volume(self, name: str | None = None) -> Volume:
|
|
434
|
+
"""Keep a new, empty volume under ``name``; without one the server picks it."""
|
|
435
|
+
output = await self._call("virtx_client_create_volume", _args(name=name))
|
|
436
|
+
return Volume.from_dict(self, output)
|
|
437
|
+
|
|
438
|
+
async def get_volume(self, name: str) -> Volume:
|
|
439
|
+
"""The volume ``name``."""
|
|
440
|
+
output = await self._call("virtx_client_get_volume", _args(name=name))
|
|
441
|
+
return Volume.from_dict(self, output)
|
|
442
|
+
|
|
443
|
+
async def list_sandbox(self) -> list[Sandbox]:
|
|
444
|
+
"""Every sandbox the server holds, without its ports."""
|
|
445
|
+
items = await self._call("virtx_client_list_sandbox")
|
|
446
|
+
return [Sandbox.from_dict(self, item) for item in items]
|
|
447
|
+
|
|
448
|
+
async def create_sandbox(
|
|
449
|
+
self,
|
|
450
|
+
image: str | ImageName,
|
|
451
|
+
*,
|
|
452
|
+
network: bool = True,
|
|
453
|
+
ports: Iterable[int] = (),
|
|
454
|
+
vcpus: int | None = None,
|
|
455
|
+
memory_mib: int | None = None,
|
|
456
|
+
disk_gib: int | None = None,
|
|
457
|
+
gpu: bool | None = None,
|
|
458
|
+
gpu_memory_mib: int | None = None,
|
|
459
|
+
volumes: Iterable[SandboxVolume | Mapping[str, Any]] = (),
|
|
460
|
+
abins: Iterable[str] = (),
|
|
461
|
+
) -> Sandbox:
|
|
462
|
+
"""Make a sandbox of ``image``, with ``volumes`` mounted into it, each a ``SandboxVolume``,
|
|
463
|
+
and virtx's programs named in ``abins`` at ``/abin``, each with its ``SKILL.md`` at
|
|
464
|
+
``/abin/skills/{name}/``. ``ports`` are TCP ports in it to open, reserved as it is made
|
|
465
|
+
and answered here only, each with the ``url`` a ``PortForwarder`` reaches it by. Whatever
|
|
466
|
+
is left out the server picks. ``disk_gib`` is how much it may write over its image, in
|
|
467
|
+
GiB, at most 1024, which goes with it.
|
|
468
|
+
|
|
469
|
+
``image`` has to be on the server already, pulled or built: this does not pull it, and a
|
|
470
|
+
tag the server has no image by is refused with ``404``."""
|
|
471
|
+
return Sandbox.from_dict(
|
|
472
|
+
self,
|
|
473
|
+
await self._call(
|
|
474
|
+
"virtx_client_create_sandbox",
|
|
475
|
+
_args(
|
|
476
|
+
image=image_name(image).to_dict(),
|
|
477
|
+
network=network,
|
|
478
|
+
ports=list(ports),
|
|
479
|
+
vcpus=vcpus,
|
|
480
|
+
memory_mib=memory_mib,
|
|
481
|
+
disk_gib=disk_gib,
|
|
482
|
+
gpu=gpu,
|
|
483
|
+
gpu_memory_mib=gpu_memory_mib,
|
|
484
|
+
volumes=[
|
|
485
|
+
v.to_dict() if isinstance(v, SandboxVolume) else dict(v) for v in volumes
|
|
486
|
+
],
|
|
487
|
+
abins=list(abins),
|
|
488
|
+
),
|
|
489
|
+
),
|
|
490
|
+
)
|
|
491
|
+
|
|
492
|
+
async def get_sandbox(self, id: str) -> Sandbox:
|
|
493
|
+
"""The sandbox ``id``, without its ports."""
|
|
494
|
+
return Sandbox.from_dict(self, await self._call("virtx_client_get_sandbox", _args(id=id)))
|
virtx/files.py
ADDED
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
"""The files in a volume or a sandbox, reached with WebDAV at ``/volumes/{name}/files/`` or
|
|
2
|
+
``/sandboxes/{id}/files/``: the requests on them, and what they answer.
|
|
3
|
+
|
|
4
|
+
A path is relative to the root, ``/``-separated, as ``dir/file.txt``; the empty path is the
|
|
5
|
+
root. The server refuses one that leads outside.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
from collections.abc import Mapping
|
|
11
|
+
from dataclasses import dataclass
|
|
12
|
+
from typing import TYPE_CHECKING, Any
|
|
13
|
+
|
|
14
|
+
from ._library import args
|
|
15
|
+
|
|
16
|
+
if TYPE_CHECKING:
|
|
17
|
+
from .client import Client
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class Files:
|
|
21
|
+
"""The files of a ``Volume`` or a ``Sandbox``. A path is relative to its
|
|
22
|
+
root, ``/``-separated, as ``dir/file.txt``; the empty path is the root."""
|
|
23
|
+
|
|
24
|
+
if TYPE_CHECKING:
|
|
25
|
+
client: Client
|
|
26
|
+
|
|
27
|
+
@property
|
|
28
|
+
def _root(self) -> dict[str, str]:
|
|
29
|
+
"""Whose files these are, as the wire names them."""
|
|
30
|
+
raise NotImplementedError
|
|
31
|
+
|
|
32
|
+
async def _files_call(self, name: str, **fields: Any) -> Any:
|
|
33
|
+
return await self.client._call(name, args(**self._root, **fields))
|
|
34
|
+
|
|
35
|
+
async def stat_file(self, path: str) -> Metadata:
|
|
36
|
+
"""What is at ``path``."""
|
|
37
|
+
return Metadata.from_dict(await self._files_call("virtx_client_stat_file", path=path))
|
|
38
|
+
|
|
39
|
+
async def exists(self, path: str) -> bool:
|
|
40
|
+
"""Whether anything is at ``path``."""
|
|
41
|
+
return await self._files_call("virtx_client_file_exists", path=path)
|
|
42
|
+
|
|
43
|
+
async def is_file(self, path: str) -> bool:
|
|
44
|
+
"""Whether a file is at ``path``."""
|
|
45
|
+
return await self._files_call("virtx_client_is_file", path=path)
|
|
46
|
+
|
|
47
|
+
async def is_dir(self, path: str) -> bool:
|
|
48
|
+
"""Whether a directory is at ``path``."""
|
|
49
|
+
return await self._files_call("virtx_client_is_dir", path=path)
|
|
50
|
+
|
|
51
|
+
async def read_dir(self, path: str) -> list[DirEntry]:
|
|
52
|
+
"""The entries of the directory at ``path``."""
|
|
53
|
+
items = await self._files_call("virtx_client_read_dir", path=path)
|
|
54
|
+
return [DirEntry.from_dict(item) for item in items]
|
|
55
|
+
|
|
56
|
+
async def read_file(self, path: str, offset: int = 0, length: int | None = None) -> bytes:
|
|
57
|
+
"""The file at ``path``, from ``offset``, ``length`` bytes of it or all that is left."""
|
|
58
|
+
return await self.client._call(
|
|
59
|
+
"virtx_client_read_file",
|
|
60
|
+
args(**self._root, path=path, offset=offset, length=length),
|
|
61
|
+
raw=True,
|
|
62
|
+
)
|
|
63
|
+
|
|
64
|
+
async def read_text(self, path: str) -> str:
|
|
65
|
+
"""The whole file at ``path`` as text, which it has to be: UTF-8."""
|
|
66
|
+
return await self._files_call("virtx_client_read_text", path=path)
|
|
67
|
+
|
|
68
|
+
async def write_file(
|
|
69
|
+
self, path: str, content: bytes | str, if_match: str | None = None
|
|
70
|
+
) -> None:
|
|
71
|
+
"""Write ``content``, a ``str`` as UTF-8, as the whole file at ``path``, creating it if
|
|
72
|
+
it does not exist. Its parent directory must exist. With ``if_match``, the ``etag`` a
|
|
73
|
+
:class:`Metadata` of the file gave, the write goes only while the file still has it,
|
|
74
|
+
and is refused with a ``412`` otherwise."""
|
|
75
|
+
client = self.client
|
|
76
|
+
request = args(**self._root, path=path, if_match=if_match)
|
|
77
|
+
content = content.encode() if isinstance(content, str) else bytes(content)
|
|
78
|
+
handle = client._lib.virtx_client_write_file(
|
|
79
|
+
client._held(), request, len(request), content, len(content)
|
|
80
|
+
)
|
|
81
|
+
await client._lib.answer(handle)
|
|
82
|
+
|
|
83
|
+
async def create_dir(self, path: str) -> None:
|
|
84
|
+
"""Create the directory at ``path``, whose parent must exist."""
|
|
85
|
+
await self._files_call("virtx_client_create_dir", path=path)
|
|
86
|
+
|
|
87
|
+
async def create_dir_all(self, path: str) -> None:
|
|
88
|
+
"""Have the directory at ``path``, as ``mkdir -p``: its parents are created as needed,
|
|
89
|
+
and one there already is left as it is. Refused with a ``405`` when a file is at
|
|
90
|
+
``path``."""
|
|
91
|
+
await self._files_call("virtx_client_create_dir_all", path=path)
|
|
92
|
+
|
|
93
|
+
async def remove_file(self, path: str, missing_ok: bool = False) -> None:
|
|
94
|
+
"""Remove what is at ``path``: a directory with everything in it. With ``missing_ok``,
|
|
95
|
+
nothing being there is fine, as ``rm -f``; without it, a ``404``."""
|
|
96
|
+
await self._files_call("virtx_client_remove_file", path=path, missing_ok=missing_ok or None)
|
|
97
|
+
|
|
98
|
+
async def rename_file(self, from_path: str, to_path: str, overwrite: bool = False) -> None:
|
|
99
|
+
"""Move what is at ``from_path`` to ``to_path``, replacing what is at ``to_path`` if
|
|
100
|
+
``overwrite``, and refused if not and something is there."""
|
|
101
|
+
await self._files_call(
|
|
102
|
+
"virtx_client_rename_file", **{"from": from_path}, to=to_path, overwrite=overwrite
|
|
103
|
+
)
|
|
104
|
+
|
|
105
|
+
async def copy_file(self, from_path: str, to_path: str, overwrite: bool = False) -> None:
|
|
106
|
+
"""Copy what is at ``from_path`` to ``to_path``, a directory with everything in it, as
|
|
107
|
+
``rename_file`` replaces what is at ``to_path``."""
|
|
108
|
+
await self._files_call(
|
|
109
|
+
"virtx_client_copy_file", **{"from": from_path}, to=to_path, overwrite=overwrite
|
|
110
|
+
)
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
@dataclass(frozen=True)
|
|
114
|
+
class Metadata:
|
|
115
|
+
"""What a file or directory is."""
|
|
116
|
+
|
|
117
|
+
is_dir: bool
|
|
118
|
+
"""Whether it is a directory."""
|
|
119
|
+
|
|
120
|
+
size: int
|
|
121
|
+
"""Its size in bytes; ``0`` for a directory."""
|
|
122
|
+
|
|
123
|
+
modified: int | None = None
|
|
124
|
+
"""When it was last modified, in seconds since the Unix epoch, if the server says."""
|
|
125
|
+
|
|
126
|
+
etag: str | None = None
|
|
127
|
+
"""Its entity tag as an ``ETag`` header spells it, if the server gives one: what a write
|
|
128
|
+
names as ``if_match`` to go only over the file it read."""
|
|
129
|
+
|
|
130
|
+
@classmethod
|
|
131
|
+
def from_dict(cls, value: Mapping[str, Any]) -> Metadata:
|
|
132
|
+
return cls(value["is_dir"], value["size"], value.get("modified"), value.get("etag"))
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
@dataclass(frozen=True)
|
|
136
|
+
class DirEntry:
|
|
137
|
+
"""One entry of a directory."""
|
|
138
|
+
|
|
139
|
+
name: str
|
|
140
|
+
"""Its name in the directory: one path segment."""
|
|
141
|
+
|
|
142
|
+
metadata: Metadata
|
|
143
|
+
|
|
144
|
+
@classmethod
|
|
145
|
+
def from_dict(cls, value: Mapping[str, Any]) -> DirEntry:
|
|
146
|
+
return cls(value["name"], Metadata.from_dict(value["metadata"]))
|