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 ADDED
@@ -0,0 +1,136 @@
1
+ """A virtx client for Python, over the C ABI of ``libvirtx_core``.
2
+
3
+ The client is not compiled into this package: ``libvirtx_core`` is opened at run time, from the
4
+ path given to ``load``, or ``$VIRTX_CORE_LIB``, or the copy a wheel carries beside these files,
5
+ or the system loader's search for its file name. So every module in a process can make its
6
+ requests through the one library, and hand a ``Client`` between them as the ``VirtxClient*`` it
7
+ is, with ``Client.as_raw``, ``Client.into_raw`` and ``Client.from_raw``.
8
+
9
+ Requests take and answer the types of ``virtx.image``, ``virtx.volume``, ``virtx.project``,
10
+ ``virtx.sandbox`` and ``virtx.files``, and plain values elsewhere: what the wire calls a map is
11
+ a ``dict``.
12
+
13
+ A build, pull or push of an image, and a process in a sandbox, is a job the server runs apart from
14
+ the request that started it. The method that starts one answers a ``StartedJob``, sent when first
15
+ awaited or iterated: awaited, it is the job, an ``ImageJob`` or a ``SandboxJob``; iterated, it
16
+ yields the job's log, as ``ImageJob.log`` or ``SandboxJob.log`` does, each a ``LogEntry``
17
+ numbered for ``after`` to resume from, until its end entry. A download or upload of an image yields its
18
+ ``Progress``, each with a line of its log as its ``content``, then its ``Output``.
19
+
20
+ A sandbox, a volume, a sandbox job and an image job are answered as a ``Sandbox``, a ``Volume``,
21
+ a ``SandboxJob`` and an ``ImageJob``, each carrying the client its requests go through: what acts
22
+ on one is the handle, so it is all a caller hands on. The client lists, makes and gets them; one
23
+ known by its id or name is had with ``get_sandbox``, ``get_volume``, ``get_image_job`` or
24
+ ``Sandbox.job``. The two with files read and write them as ``Files``:
25
+ ``await volume.read_file("a.txt")``.
26
+
27
+ A project is answered as a ``Project``, carrying its client the same way: its members, and its
28
+ removal. What is in it, a client reaches in the project ``Client.set_project`` names.
29
+
30
+ A sandbox's port is reached through a ``PortForwarder``, opened over a client with the ``url``
31
+ ``create_sandbox`` answered for it: an address on this machine's loopback.
32
+ """
33
+
34
+ from ._library import LIBRARY_ENV, Source, VirtxError, library_path, load
35
+ from .client import Auth, Client, CommandAuth, Event, Output, Progress, ensure_virtx
36
+ from .files import DirEntry, Files, Metadata
37
+ from .image import (
38
+ BasicAuth,
39
+ BearerAuth,
40
+ ImageDigest,
41
+ ImageDownloadOutput,
42
+ ImageJob,
43
+ ImageJobEnd,
44
+ ImageJobEntry,
45
+ ImageJobKind,
46
+ ImageListOutputItem,
47
+ ImageName,
48
+ ImagePruneOutput,
49
+ ImageTag,
50
+ ImageUploadOutput,
51
+ Log,
52
+ Recipe,
53
+ RegistryAuth,
54
+ image_name,
55
+ )
56
+ from .job import LogEntry, StartedJob, Truncated
57
+ from .portforward import PortForwarder
58
+ from .project import Project, ProjectMemberListOutputItem, Role
59
+ from .sandbox import (
60
+ Sandbox,
61
+ SandboxJob,
62
+ SandboxJobEnd,
63
+ SandboxJobEntry,
64
+ SandboxJobKind,
65
+ SandboxPort,
66
+ SandboxVolume,
67
+ Stderr,
68
+ Stdout,
69
+ )
70
+ from .volume import (
71
+ GdriveSource,
72
+ MountSource,
73
+ MountType,
74
+ NotionSource,
75
+ OnedriveSource,
76
+ Volume,
77
+ VolumeMountListOutputItem,
78
+ )
79
+
80
+ __all__ = [
81
+ "LIBRARY_ENV",
82
+ "Auth",
83
+ "BasicAuth",
84
+ "BearerAuth",
85
+ "Client",
86
+ "CommandAuth",
87
+ "DirEntry",
88
+ "Event",
89
+ "Files",
90
+ "GdriveSource",
91
+ "ImageDigest",
92
+ "ImageDownloadOutput",
93
+ "ImageJob",
94
+ "ImageJobEnd",
95
+ "ImageJobEntry",
96
+ "ImageJobKind",
97
+ "ImageListOutputItem",
98
+ "ImageName",
99
+ "ImagePruneOutput",
100
+ "ImageTag",
101
+ "ImageUploadOutput",
102
+ "Log",
103
+ "LogEntry",
104
+ "Metadata",
105
+ "MountSource",
106
+ "MountType",
107
+ "NotionSource",
108
+ "OnedriveSource",
109
+ "Output",
110
+ "PortForwarder",
111
+ "Progress",
112
+ "Project",
113
+ "ProjectMemberListOutputItem",
114
+ "Recipe",
115
+ "RegistryAuth",
116
+ "Role",
117
+ "Sandbox",
118
+ "SandboxJob",
119
+ "SandboxJobEnd",
120
+ "SandboxJobEntry",
121
+ "SandboxJobKind",
122
+ "SandboxPort",
123
+ "SandboxVolume",
124
+ "Source",
125
+ "StartedJob",
126
+ "Stderr",
127
+ "Stdout",
128
+ "Truncated",
129
+ "VirtxError",
130
+ "Volume",
131
+ "VolumeMountListOutputItem",
132
+ "ensure_virtx",
133
+ "image_name",
134
+ "library_path",
135
+ "load",
136
+ ]
virtx/_cli.py ADDED
@@ -0,0 +1,21 @@
1
+ """The ``virtx`` command: the one ``libvirtx_core`` carries, run with this process's arguments."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import ctypes
6
+ import os
7
+ import sys
8
+
9
+ from ._library import VirtxError, library
10
+
11
+
12
+ def main() -> None:
13
+ try:
14
+ dll = library()._dll
15
+ except VirtxError as e:
16
+ sys.exit(f"virtx: {e}")
17
+ run = dll.virtx_cli_main
18
+ run.argtypes = [ctypes.POINTER(ctypes.c_char_p), ctypes.c_size_t]
19
+ run.restype = ctypes.c_int
20
+ argv = [b"virtx", *(os.fsencode(arg) for arg in sys.argv[1:])]
21
+ sys.exit(run((ctypes.c_char_p * len(argv))(*argv), len(argv)))
virtx/_library.py ADDED
@@ -0,0 +1,337 @@
1
+ """``libvirtx_core``, opened with ctypes, and its requests driven from asyncio.
2
+
3
+ One library per process: every client is made by the one first opened, which stays open until
4
+ the process ends. A client handed to another module is only good in the same library, so a
5
+ module that shares one opens the path ``library_path()`` answers.
6
+
7
+ A request is polled with a waker the library wakes from its own threads: the wake schedules
8
+ the asyncio future the poll is waiting on, on that future's loop, and the next poll takes what
9
+ woke it.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import asyncio
15
+ import ctypes
16
+ import itertools
17
+ import json
18
+ import os
19
+ import sys
20
+ import threading
21
+ from collections.abc import AsyncIterator, Callable
22
+ from pathlib import Path
23
+ from typing import Any, Literal
24
+
25
+ OK, ERROR, PENDING, END = 0, -1, 1, 2
26
+
27
+ #: The variable naming the library to open when ``load`` was not called first.
28
+ LIBRARY_ENV = "VIRTX_CORE_LIB"
29
+
30
+ if sys.platform == "win32":
31
+ FILE_NAME = "virtx_core.dll"
32
+ elif sys.platform == "darwin":
33
+ FILE_NAME = "libvirtx_core.dylib"
34
+ else:
35
+ FILE_NAME = "libvirtx_core.so"
36
+
37
+
38
+ def args(**args: Any) -> bytes:
39
+ """``args`` without the ones left out, as JSON."""
40
+ return json.dumps({key: value for key, value in args.items() if value is not None}).encode()
41
+
42
+
43
+ Source = Literal["server", "job", "transport", "client"]
44
+ """Where a request failed: the server answered it with an error, the job it started failed,
45
+ the connection failed, or this side did."""
46
+
47
+
48
+ class VirtxError(Exception):
49
+ """A request failed: where, as ``source``, and with ``status`` the HTTP status the server
50
+ answered with."""
51
+
52
+ source: Source
53
+ """Where it failed. Tell errors apart by it and ``status``, not by the message."""
54
+
55
+ status: int | None
56
+ """The HTTP status the server refused the request with, if it did: ``404`` for what does
57
+ not exist, ``409`` for what is in use or has ended, and the like."""
58
+
59
+ body: str | None
60
+ """The server's response body, where it was not a JSON error."""
61
+
62
+ def __init__(
63
+ self,
64
+ message: str,
65
+ status: int | None = None,
66
+ body: str | None = None,
67
+ source: Source = "client",
68
+ ) -> None:
69
+ super().__init__(message)
70
+ self.source = source
71
+ self.status = status
72
+ self.body = body
73
+
74
+
75
+ class _Bytes(ctypes.Structure):
76
+ _fields_ = [("data", ctypes.c_void_p), ("len", ctypes.c_size_t)]
77
+
78
+
79
+ _CALLBACK = ctypes.CFUNCTYPE(None, ctypes.c_void_p)
80
+
81
+
82
+ class _Waker(ctypes.Structure):
83
+ _fields_ = [("data", ctypes.c_void_p), ("wake", _CALLBACK), ("release", _CALLBACK)]
84
+
85
+
86
+ # The pending polls, by the key their waker carries as its `data`: the loop and the future to
87
+ # settle on it.
88
+ _pending: dict[int, tuple[asyncio.AbstractEventLoop, asyncio.Future[None]]] = {}
89
+ _keys = itertools.count(1)
90
+
91
+
92
+ def _settle(future: asyncio.Future[None]) -> None:
93
+ if not future.done():
94
+ future.set_result(None)
95
+
96
+
97
+ @_CALLBACK
98
+ def _wake(key: int | None) -> None:
99
+ entry = _pending.get(key or 0)
100
+ if entry is None:
101
+ return
102
+ loop, future = entry
103
+ try:
104
+ loop.call_soon_threadsafe(_settle, future)
105
+ except RuntimeError:
106
+ # The loop has closed; nothing is waiting on it.
107
+ pass
108
+
109
+
110
+ @_CALLBACK
111
+ def _release(key: int | None) -> None:
112
+ _pending.pop(key or 0, None)
113
+
114
+
115
+ _HANDLE = ctypes.c_void_p
116
+ _OUT = ctypes.POINTER(_Bytes)
117
+
118
+ # Each function's argument and result types, as `virtx.h` declares them. A request takes the
119
+ # client and, unless it is a list, its arguments as `(bytes, len)`.
120
+ _PLAIN = ([_HANDLE], _HANDLE)
121
+ _WITH_ARGS = ([_HANDLE, ctypes.c_char_p, ctypes.c_size_t], _HANDLE)
122
+ # A request with a body of bytes beside its args.
123
+ _WITH_DATA = (
124
+ [_HANDLE, ctypes.c_char_p, ctypes.c_size_t, ctypes.c_char_p, ctypes.c_size_t],
125
+ _HANDLE,
126
+ )
127
+ _SIGNATURES: dict[str, tuple[list[Any], Any]] = {
128
+ "virtx_ensure_virtx": ([], _HANDLE),
129
+ "virtx_client_spawn": (
130
+ [
131
+ ctypes.c_char_p,
132
+ ctypes.POINTER(ctypes.c_char_p),
133
+ ctypes.c_size_t,
134
+ ctypes.POINTER(_HANDLE),
135
+ _OUT,
136
+ ],
137
+ ctypes.c_int,
138
+ ),
139
+ "virtx_client_connect": (
140
+ [
141
+ ctypes.c_char_p,
142
+ ctypes.c_char_p,
143
+ ctypes.c_size_t,
144
+ ctypes.POINTER(ctypes.c_char_p),
145
+ ctypes.c_size_t,
146
+ ctypes.POINTER(_HANDLE),
147
+ _OUT,
148
+ ],
149
+ ctypes.c_int,
150
+ ),
151
+ "virtx_client_set_auth": ([_HANDLE, ctypes.c_char_p, ctypes.c_size_t, _OUT], ctypes.c_int),
152
+ "virtx_client_set_headers": (
153
+ [_HANDLE, ctypes.POINTER(ctypes.c_char_p), ctypes.c_size_t, _OUT],
154
+ ctypes.c_int,
155
+ ),
156
+ "virtx_client_set_project": ([_HANDLE, ctypes.c_char_p, _OUT], ctypes.c_int),
157
+ "virtx_client_retain": ([_HANDLE], None),
158
+ "virtx_client_release": ([_HANDLE], _HANDLE),
159
+ "virtx_client_build_image": _WITH_ARGS,
160
+ "virtx_client_pull_image": _WITH_ARGS,
161
+ "virtx_client_push_image": _WITH_ARGS,
162
+ "virtx_client_list_image_job": _PLAIN,
163
+ "virtx_client_get_image_job": _WITH_ARGS,
164
+ "virtx_client_remove_image_job": _WITH_ARGS,
165
+ "virtx_client_image_job_log": _WITH_ARGS,
166
+ "virtx_client_list_image": _PLAIN,
167
+ "virtx_client_tag_image": _WITH_ARGS,
168
+ "virtx_client_untag_image": _WITH_ARGS,
169
+ "virtx_client_remove_image": _WITH_ARGS,
170
+ "virtx_client_download_image": _WITH_ARGS,
171
+ "virtx_client_upload_image": _WITH_ARGS,
172
+ "virtx_client_prune_image": _PLAIN,
173
+ "virtx_client_list_project": _PLAIN,
174
+ "virtx_client_create_project": _WITH_ARGS,
175
+ "virtx_client_get_project": _WITH_ARGS,
176
+ "virtx_client_remove_project": _WITH_ARGS,
177
+ "virtx_client_list_project_member": _WITH_ARGS,
178
+ "virtx_client_set_project_member": _WITH_ARGS,
179
+ "virtx_client_remove_project_member": _WITH_ARGS,
180
+ "virtx_client_list_volume": _PLAIN,
181
+ "virtx_client_create_volume": _WITH_ARGS,
182
+ "virtx_client_get_volume": _WITH_ARGS,
183
+ "virtx_client_remove_volume": _WITH_ARGS,
184
+ "virtx_client_list_volume_mount": _WITH_ARGS,
185
+ "virtx_client_create_volume_mount": _WITH_ARGS,
186
+ "virtx_client_remove_volume_mount": _WITH_ARGS,
187
+ "virtx_client_stat_file": _WITH_ARGS,
188
+ "virtx_client_read_dir": _WITH_ARGS,
189
+ "virtx_client_file_exists": _WITH_ARGS,
190
+ "virtx_client_is_file": _WITH_ARGS,
191
+ "virtx_client_is_dir": _WITH_ARGS,
192
+ "virtx_client_read_file": _WITH_ARGS,
193
+ "virtx_client_read_text": _WITH_ARGS,
194
+ "virtx_client_write_file": _WITH_DATA,
195
+ "virtx_client_create_dir": _WITH_ARGS,
196
+ "virtx_client_create_dir_all": _WITH_ARGS,
197
+ "virtx_client_remove_file": _WITH_ARGS,
198
+ "virtx_client_rename_file": _WITH_ARGS,
199
+ "virtx_client_copy_file": _WITH_ARGS,
200
+ "virtx_client_list_sandbox": _PLAIN,
201
+ "virtx_client_create_sandbox": _WITH_ARGS,
202
+ "virtx_client_get_sandbox": _WITH_ARGS,
203
+ "virtx_client_remove_sandbox": _WITH_ARGS,
204
+ "virtx_client_list_sandbox_job": _WITH_ARGS,
205
+ "virtx_client_exec_sandbox": _WITH_ARGS,
206
+ "virtx_client_get_sandbox_job": _WITH_ARGS,
207
+ "virtx_client_remove_sandbox_job": _WITH_ARGS,
208
+ "virtx_client_signal_sandbox_job": _WITH_ARGS,
209
+ "virtx_client_write_sandbox_job_stdin": _WITH_ARGS,
210
+ "virtx_client_sandbox_job_log": _WITH_ARGS,
211
+ "virtx_port_forwarder_open": (
212
+ [_HANDLE, ctypes.c_char_p, ctypes.c_size_t, ctypes.POINTER(_HANDLE), _OUT],
213
+ ctypes.c_int,
214
+ ),
215
+ "virtx_port_forwarder_free": ([_HANDLE], None),
216
+ "virtx_bytes_free": ([_Bytes], None),
217
+ "virtx_future_poll": ([_HANDLE, _Waker, _OUT], ctypes.c_int),
218
+ "virtx_future_wait": ([_HANDLE, _OUT], ctypes.c_int),
219
+ "virtx_future_free": ([_HANDLE], None),
220
+ "virtx_stream_poll_next": ([_HANDLE, _Waker, _OUT], ctypes.c_int),
221
+ "virtx_stream_free": ([_HANDLE], None),
222
+ }
223
+
224
+
225
+ class Library:
226
+ """The functions of ``virtx.h``, found in the library at ``path``."""
227
+
228
+ def __init__(self, path: str) -> None:
229
+ self.path = path
230
+ # `CDLL` lets go of the GIL for each call, so a call that blocks (opening a client, or
231
+ # releasing the last hold) leaves the waker's callbacks free to take it.
232
+ self._dll = ctypes.CDLL(path)
233
+ for name, (argtypes, restype) in _SIGNATURES.items():
234
+ function = getattr(self._dll, name)
235
+ function.argtypes = argtypes
236
+ function.restype = restype
237
+ setattr(self, name, function)
238
+
239
+ def take(self, status: int, out: _Bytes, raw: bool = False) -> Any:
240
+ """What the library wrote for ``status``, read and freed: the output, as JSON unless
241
+ ``raw``, or raised."""
242
+ data = ctypes.string_at(out.data, out.len) if out.data else b""
243
+ if out.data:
244
+ self.virtx_bytes_free(out)
245
+ if status == OK:
246
+ return data if raw else json.loads(data)
247
+ if status == ERROR:
248
+ if not data:
249
+ raise VirtxError("the call failed")
250
+ failure = json.loads(data)
251
+ raise VirtxError(
252
+ failure["message"], failure.get("status"), failure.get("body"), failure["source"]
253
+ )
254
+ raise VirtxError(f"unknown status {status}")
255
+
256
+ def _poll(
257
+ self, poll: Callable[..., int], handle: int
258
+ ) -> tuple[int, _Bytes, asyncio.Future[None]]:
259
+ loop = asyncio.get_running_loop()
260
+ future = loop.create_future()
261
+ key = next(_keys)
262
+ _pending[key] = (loop, future)
263
+ out = _Bytes()
264
+ status = poll(handle, _Waker(key, _wake, _release), ctypes.byref(out))
265
+ return status, out, future
266
+
267
+ def wait(self, handle: int, raw: bool = False) -> Any:
268
+ """Block until the future ``handle`` answers, freeing it after, for a caller off the
269
+ event loop. Its answer is as ``answer``'s."""
270
+ try:
271
+ out = _Bytes()
272
+ status = self.virtx_future_wait(handle, ctypes.byref(out))
273
+ return self.take(status, out, raw)
274
+ finally:
275
+ self.virtx_future_free(handle)
276
+
277
+ async def answer(self, handle: int, raw: bool = False) -> Any:
278
+ """Await the future ``handle``, freeing it after, or on cancelling, which cancels it.
279
+ Its answer is JSON, or bytes as they are if ``raw``."""
280
+ try:
281
+ while True:
282
+ status, out, woken = self._poll(self.virtx_future_poll, handle)
283
+ if status != PENDING:
284
+ return self.take(status, out, raw)
285
+ await woken
286
+ finally:
287
+ self.virtx_future_free(handle)
288
+
289
+ async def items(self, handle: int) -> AsyncIterator[Any]:
290
+ """Each item of the stream ``handle``, freeing it after, or on closing, which cancels
291
+ it."""
292
+ try:
293
+ while True:
294
+ status, out, woken = self._poll(self.virtx_stream_poll_next, handle)
295
+ if status == END:
296
+ return
297
+ if status != PENDING:
298
+ yield self.take(status, out)
299
+ continue
300
+ await woken
301
+ finally:
302
+ self.virtx_stream_free(handle)
303
+
304
+
305
+ _library: Library | None = None
306
+ _lock = threading.Lock()
307
+
308
+
309
+ def load(path: str | os.PathLike[str]) -> None:
310
+ """Open the library at ``path`` for this process's clients. Opening the one already open does
311
+ nothing; another is refused, since a process has one."""
312
+ global _library
313
+ path = os.fspath(path)
314
+ with _lock:
315
+ if _library is None:
316
+ try:
317
+ _library = Library(path)
318
+ except OSError as e:
319
+ raise VirtxError(f"opening {path}: {e}") from e
320
+ elif _library.path != path:
321
+ raise VirtxError(f"{_library.path} is open already, so {path} is not opened")
322
+
323
+
324
+ def library_path() -> str | None:
325
+ """The path the open library was opened by; ``None`` before the first client or ``load``."""
326
+ return _library.path if _library is not None else None
327
+
328
+
329
+ def library() -> Library:
330
+ """The open library, opening it first if none is: ``$VIRTX_CORE_LIB``, else the one in this
331
+ package, else the platform's file name for the system's loader to look up."""
332
+ if _library is None:
333
+ bundled = Path(__file__).with_name(FILE_NAME)
334
+ path = os.environ.get(LIBRARY_ENV) or (str(bundled) if bundled.exists() else FILE_NAME)
335
+ load(path)
336
+ assert _library is not None
337
+ return _library