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/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"]))