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/sandbox.py
ADDED
|
@@ -0,0 +1,254 @@
|
|
|
1
|
+
"""Sandboxes: a VM booted from an image, with volumes mounted into it; and the processes run in
|
|
2
|
+
one, each a job whose log is its output."""
|
|
3
|
+
|
|
4
|
+
from __future__ import annotations
|
|
5
|
+
|
|
6
|
+
import builtins
|
|
7
|
+
import sys
|
|
8
|
+
from collections.abc import AsyncIterator, Iterable, Mapping
|
|
9
|
+
from contextlib import aclosing
|
|
10
|
+
from dataclasses import dataclass, field
|
|
11
|
+
from enum import Enum
|
|
12
|
+
from typing import TYPE_CHECKING, Any
|
|
13
|
+
|
|
14
|
+
from ._library import VirtxError, args
|
|
15
|
+
from .files import Files
|
|
16
|
+
from .job import LogEntry, StartedJob, Truncated
|
|
17
|
+
from .volume import Volume
|
|
18
|
+
|
|
19
|
+
if TYPE_CHECKING:
|
|
20
|
+
from .client import Client
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
@dataclass(frozen=True)
|
|
24
|
+
class SandboxPort:
|
|
25
|
+
"""A TCP port in a sandbox, opened as it was made, and the ``url`` a ``PortForwarder``
|
|
26
|
+
reaches it by."""
|
|
27
|
+
|
|
28
|
+
port: int
|
|
29
|
+
url: str
|
|
30
|
+
|
|
31
|
+
@classmethod
|
|
32
|
+
def from_dict(cls, value: Mapping[str, Any]) -> SandboxPort:
|
|
33
|
+
return cls(value["port"], value["url"])
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
@dataclass(frozen=True)
|
|
37
|
+
class SandboxVolume:
|
|
38
|
+
"""A volume, a ``Volume`` or its name, mounted at ``path`` in a sandbox."""
|
|
39
|
+
|
|
40
|
+
volume: str | Volume
|
|
41
|
+
path: str
|
|
42
|
+
readonly: bool = False
|
|
43
|
+
|
|
44
|
+
def to_dict(self) -> dict[str, Any]:
|
|
45
|
+
"""As the wire has it."""
|
|
46
|
+
volume = self.volume.name if isinstance(self.volume, Volume) else self.volume
|
|
47
|
+
return {"volume": volume, "path": self.path, "readonly": self.readonly}
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
@dataclass(frozen=True)
|
|
51
|
+
class Sandbox(Files):
|
|
52
|
+
"""One sandbox the server holds, and the client that reaches it: what runs processes in it
|
|
53
|
+
and reads and writes its files. Dropping it leaves the sandbox; ``remove`` removes it."""
|
|
54
|
+
|
|
55
|
+
client: Client = field(repr=False, compare=False)
|
|
56
|
+
"""The client its requests go through."""
|
|
57
|
+
|
|
58
|
+
id: str
|
|
59
|
+
|
|
60
|
+
image: str
|
|
61
|
+
"""The digest of the image it booted, as ``algorithm:hex``."""
|
|
62
|
+
|
|
63
|
+
running: bool
|
|
64
|
+
|
|
65
|
+
ports: list[SandboxPort] = field(default_factory=list)
|
|
66
|
+
"""Its opened ports: answered by ``create_sandbox`` only."""
|
|
67
|
+
|
|
68
|
+
abins: list[str] = field(default_factory=list)
|
|
69
|
+
"""virtx's own programs it has at ``/abin``."""
|
|
70
|
+
|
|
71
|
+
@classmethod
|
|
72
|
+
def from_dict(cls, client: Client, value: Mapping[str, Any]) -> Sandbox:
|
|
73
|
+
return cls(
|
|
74
|
+
client,
|
|
75
|
+
value["id"],
|
|
76
|
+
value["image"],
|
|
77
|
+
value["running"],
|
|
78
|
+
[SandboxPort.from_dict(port) for port in value.get("ports", ())],
|
|
79
|
+
list(value.get("abins", ())),
|
|
80
|
+
)
|
|
81
|
+
|
|
82
|
+
@property
|
|
83
|
+
def _root(self) -> dict[str, str]:
|
|
84
|
+
return {"sandbox": self.id}
|
|
85
|
+
|
|
86
|
+
def exec(
|
|
87
|
+
self, cmd: Iterable[str], *, stdin: bool = False, timeout_ms: int | None = None
|
|
88
|
+
) -> StartedJob[SandboxJob, SandboxJobEntry]:
|
|
89
|
+
"""Run ``cmd`` in it, its stdin open for ``SandboxJob.write_stdin`` if ``stdin``, killed
|
|
90
|
+
after ``timeout_ms`` if one is given. Awaited, the job; iterated, its output and how it
|
|
91
|
+
ended, as ``SandboxJob.log``'s; ``complete``, its exit code, as
|
|
92
|
+
``SandboxJob.complete``'s. Sent when first awaited, iterated or completed."""
|
|
93
|
+
request = args(sandbox=self.id, cmd=list(cmd), stdin=stdin or None, timeout_ms=timeout_ms)
|
|
94
|
+
|
|
95
|
+
async def start() -> SandboxJob:
|
|
96
|
+
output = await self.client._call("virtx_client_exec_sandbox", request)
|
|
97
|
+
return SandboxJob.from_dict(self.client, self.id, output)
|
|
98
|
+
|
|
99
|
+
return StartedJob(start, lambda job: job.log())
|
|
100
|
+
|
|
101
|
+
async def jobs(self) -> list[SandboxJob]:
|
|
102
|
+
"""Every job in it."""
|
|
103
|
+
items = await self.client._call("virtx_client_list_sandbox_job", args(sandbox=self.id))
|
|
104
|
+
return [SandboxJob.from_dict(self.client, self.id, item) for item in items]
|
|
105
|
+
|
|
106
|
+
async def job(self, id: str) -> SandboxJob:
|
|
107
|
+
"""The job ``id`` in it."""
|
|
108
|
+
output = await self.client._call(
|
|
109
|
+
"virtx_client_get_sandbox_job", args(sandbox=self.id, job=id)
|
|
110
|
+
)
|
|
111
|
+
return SandboxJob.from_dict(self.client, self.id, output)
|
|
112
|
+
|
|
113
|
+
async def remove(self) -> None:
|
|
114
|
+
"""Stop it, end its jobs, and forget it, with everything it wrote outside its volumes."""
|
|
115
|
+
await self.client._call("virtx_client_remove_sandbox", args(id=self.id))
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
class SandboxJobKind(str, Enum):
|
|
119
|
+
"""What a sandbox job does."""
|
|
120
|
+
|
|
121
|
+
EXEC = "exec"
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
@dataclass(frozen=True)
|
|
125
|
+
class SandboxJob:
|
|
126
|
+
"""A process run in a sandbox, as ``Sandbox.exec``, ``Sandbox.jobs`` and ``Sandbox.job``
|
|
127
|
+
answer it, and the client and sandbox that reach it: what signals it, writes to its stdin
|
|
128
|
+
and reads its log. Dropping it leaves the job; ``remove`` removes it."""
|
|
129
|
+
|
|
130
|
+
client: Client = field(repr=False, compare=False)
|
|
131
|
+
"""The client its requests go through."""
|
|
132
|
+
|
|
133
|
+
sandbox_id: str
|
|
134
|
+
"""The id of the sandbox it runs in."""
|
|
135
|
+
|
|
136
|
+
id: str
|
|
137
|
+
"""The job's id, which every request about it names it by, beside its sandbox's."""
|
|
138
|
+
|
|
139
|
+
kind: SandboxJobKind
|
|
140
|
+
|
|
141
|
+
pid: int
|
|
142
|
+
"""Its process's id in the sandbox."""
|
|
143
|
+
|
|
144
|
+
cmd: list[str]
|
|
145
|
+
|
|
146
|
+
running: bool
|
|
147
|
+
"""Whether its process runs still."""
|
|
148
|
+
|
|
149
|
+
code: int | None = None
|
|
150
|
+
"""Once it has ended, its exit code."""
|
|
151
|
+
|
|
152
|
+
@classmethod
|
|
153
|
+
def from_dict(cls, client: Client, sandbox_id: str, value: Mapping[str, Any]) -> SandboxJob:
|
|
154
|
+
return cls(
|
|
155
|
+
client,
|
|
156
|
+
sandbox_id,
|
|
157
|
+
value["id"],
|
|
158
|
+
SandboxJobKind(value["kind"]),
|
|
159
|
+
value["pid"],
|
|
160
|
+
list(value["cmd"]),
|
|
161
|
+
value["running"],
|
|
162
|
+
value.get("code"),
|
|
163
|
+
)
|
|
164
|
+
|
|
165
|
+
def _args(self, **fields: Any) -> bytes:
|
|
166
|
+
return args(sandbox=self.sandbox_id, job=self.id, **fields)
|
|
167
|
+
|
|
168
|
+
async def get(self) -> SandboxJob:
|
|
169
|
+
"""It as the server has it now."""
|
|
170
|
+
output = await self.client._call("virtx_client_get_sandbox_job", self._args())
|
|
171
|
+
return SandboxJob.from_dict(self.client, self.sandbox_id, output)
|
|
172
|
+
|
|
173
|
+
async def signal(self, signal: str) -> None:
|
|
174
|
+
"""Send ``signal``, such as ``"SIGTERM"``, to its process and every process it
|
|
175
|
+
started."""
|
|
176
|
+
await self.client._call("virtx_client_signal_sandbox_job", self._args(signal=signal))
|
|
177
|
+
|
|
178
|
+
async def write_stdin(self, data: str | None = None, eof: bool = False) -> None:
|
|
179
|
+
"""Write ``data`` to its process's stdin, then close it if ``eof``. Returns once it is
|
|
180
|
+
written: await it before the next write, so the writes land in order."""
|
|
181
|
+
await self.client._call(
|
|
182
|
+
"virtx_client_write_sandbox_job_stdin", self._args(data=data, eof=eof or None)
|
|
183
|
+
)
|
|
184
|
+
|
|
185
|
+
async def log(self, after: int | None = None) -> AsyncIterator[LogEntry[SandboxJobEntry]]:
|
|
186
|
+
"""Its log, its process's output, from its start or after its ``after``th entry, until
|
|
187
|
+
its ``SandboxJobEnd``. Closing it leaves the job as it is."""
|
|
188
|
+
async for item in self.client._items(
|
|
189
|
+
"virtx_client_sandbox_job_log", self._args(after=after)
|
|
190
|
+
):
|
|
191
|
+
yield sandbox_job_entry(item)
|
|
192
|
+
|
|
193
|
+
async def complete(self, print: bool = False) -> int:
|
|
194
|
+
"""Follow it to its end, printing what its process writes to stdout and stderr as it
|
|
195
|
+
wrote them if ``print``: its exit code, ``128 + signal`` for one a signal ended."""
|
|
196
|
+
async with aclosing(self.log()) as log:
|
|
197
|
+
async for item in log:
|
|
198
|
+
match item.entry:
|
|
199
|
+
case Stdout(line) if print:
|
|
200
|
+
builtins.print(line)
|
|
201
|
+
case Stderr(line) if print:
|
|
202
|
+
builtins.print(line, file=sys.stderr)
|
|
203
|
+
case Truncated() if print:
|
|
204
|
+
builtins.print(
|
|
205
|
+
"(the log reached the server's limit; the rest is not kept)",
|
|
206
|
+
file=sys.stderr,
|
|
207
|
+
)
|
|
208
|
+
case SandboxJobEnd(code):
|
|
209
|
+
return code
|
|
210
|
+
raise VirtxError("the job was removed before it ended", source="job")
|
|
211
|
+
|
|
212
|
+
async def remove(self) -> None:
|
|
213
|
+
"""Cancel it if it runs, killing its process, and forget it."""
|
|
214
|
+
await self.client._call("virtx_client_remove_sandbox_job", self._args())
|
|
215
|
+
|
|
216
|
+
|
|
217
|
+
@dataclass(frozen=True)
|
|
218
|
+
class Stdout:
|
|
219
|
+
"""A line the process wrote to stdout."""
|
|
220
|
+
|
|
221
|
+
line: str
|
|
222
|
+
|
|
223
|
+
|
|
224
|
+
@dataclass(frozen=True)
|
|
225
|
+
class Stderr:
|
|
226
|
+
"""A line the process wrote to stderr."""
|
|
227
|
+
|
|
228
|
+
line: str
|
|
229
|
+
|
|
230
|
+
|
|
231
|
+
@dataclass(frozen=True)
|
|
232
|
+
class SandboxJobEnd:
|
|
233
|
+
"""How the process ended, last in its log."""
|
|
234
|
+
|
|
235
|
+
code: int
|
|
236
|
+
|
|
237
|
+
|
|
238
|
+
SandboxJobEntry = Stdout | Stderr | Truncated | SandboxJobEnd
|
|
239
|
+
"""An entry of a sandbox job's log."""
|
|
240
|
+
|
|
241
|
+
|
|
242
|
+
def sandbox_job_entry(item: Mapping[str, Any]) -> LogEntry[SandboxJobEntry]:
|
|
243
|
+
"""An item of ``SandboxJob.log``'s stream, as ``{"id": n, "stdout": "..."}`` and the
|
|
244
|
+
like."""
|
|
245
|
+
entry: SandboxJobEntry
|
|
246
|
+
if "stdout" in item:
|
|
247
|
+
entry = Stdout(item["stdout"])
|
|
248
|
+
elif "stderr" in item:
|
|
249
|
+
entry = Stderr(item["stderr"])
|
|
250
|
+
elif "truncated" in item:
|
|
251
|
+
entry = Truncated()
|
|
252
|
+
else:
|
|
253
|
+
entry = SandboxJobEnd(item["end"]["code"])
|
|
254
|
+
return LogEntry(item["id"], entry)
|
virtx/virtx_core.dll
ADDED
|
Binary file
|
virtx/volume.py
ADDED
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
"""Volumes: storage the server keeps under a name, apart from any VM, and the mounts in one.
|
|
2
|
+
|
|
3
|
+
A path in a volume is relative to its root, ``/``-separated, as ``dir/file.txt``; the empty path
|
|
4
|
+
is the root. The server refuses one that leads outside the volume.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
from collections.abc import Mapping
|
|
10
|
+
from dataclasses import dataclass, field
|
|
11
|
+
from enum import Enum
|
|
12
|
+
from typing import TYPE_CHECKING, Any, ClassVar
|
|
13
|
+
|
|
14
|
+
from ._library import args
|
|
15
|
+
from .files import Files
|
|
16
|
+
|
|
17
|
+
if TYPE_CHECKING:
|
|
18
|
+
from .client import Client
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class MountType(str, Enum):
|
|
22
|
+
"""A mount source's type, without its credentials."""
|
|
23
|
+
|
|
24
|
+
NOTION = "notion"
|
|
25
|
+
GDRIVE = "gdrive"
|
|
26
|
+
ONEDRIVE = "onedrive"
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
@dataclass(frozen=True)
|
|
30
|
+
class NotionSource:
|
|
31
|
+
"""The pages a Notion integration can reach."""
|
|
32
|
+
|
|
33
|
+
mount_type: ClassVar[MountType] = MountType.NOTION
|
|
34
|
+
|
|
35
|
+
api_key: str = field(repr=False)
|
|
36
|
+
|
|
37
|
+
def to_dict(self) -> dict[str, Any]:
|
|
38
|
+
"""As the wire has it."""
|
|
39
|
+
return {"type": "notion", "api_key": self.api_key}
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
@dataclass(frozen=True)
|
|
43
|
+
class GdriveSource:
|
|
44
|
+
"""A Google Drive."""
|
|
45
|
+
|
|
46
|
+
mount_type: ClassVar[MountType] = MountType.GDRIVE
|
|
47
|
+
|
|
48
|
+
client_id: str
|
|
49
|
+
client_secret: str = field(repr=False)
|
|
50
|
+
refresh_token: str = field(repr=False)
|
|
51
|
+
|
|
52
|
+
def to_dict(self) -> dict[str, Any]:
|
|
53
|
+
"""As the wire has it."""
|
|
54
|
+
return {
|
|
55
|
+
"type": "gdrive",
|
|
56
|
+
"client_id": self.client_id,
|
|
57
|
+
"client_secret": self.client_secret,
|
|
58
|
+
"refresh_token": self.refresh_token,
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
@dataclass(frozen=True)
|
|
63
|
+
class OnedriveSource:
|
|
64
|
+
"""A OneDrive. ``client_secret`` is for a confidential app; a public one, as a personal
|
|
65
|
+
account's usually is, has none."""
|
|
66
|
+
|
|
67
|
+
mount_type: ClassVar[MountType] = MountType.ONEDRIVE
|
|
68
|
+
|
|
69
|
+
client_id: str
|
|
70
|
+
refresh_token: str = field(repr=False)
|
|
71
|
+
client_secret: str | None = field(default=None, repr=False)
|
|
72
|
+
|
|
73
|
+
def to_dict(self) -> dict[str, Any]:
|
|
74
|
+
"""As the wire has it."""
|
|
75
|
+
value = {
|
|
76
|
+
"type": "onedrive",
|
|
77
|
+
"client_id": self.client_id,
|
|
78
|
+
"refresh_token": self.refresh_token,
|
|
79
|
+
}
|
|
80
|
+
if self.client_secret is not None:
|
|
81
|
+
value["client_secret"] = self.client_secret
|
|
82
|
+
return value
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
MountSource = NotionSource | GdriveSource | OnedriveSource
|
|
86
|
+
"""What a mount shows, and the credentials to reach it."""
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
@dataclass(frozen=True)
|
|
90
|
+
class Volume(Files):
|
|
91
|
+
"""One volume the server holds, as ``list_volume``, ``get_volume`` and ``create_volume``
|
|
92
|
+
answer it, and the client that reaches it: its files, and the mounts in it. Dropping it
|
|
93
|
+
leaves the volume; ``remove`` removes it."""
|
|
94
|
+
|
|
95
|
+
client: Client = field(repr=False, compare=False)
|
|
96
|
+
"""The client its requests go through."""
|
|
97
|
+
|
|
98
|
+
name: str
|
|
99
|
+
|
|
100
|
+
size: int
|
|
101
|
+
"""The bytes the volume's files took on the server when it was answered."""
|
|
102
|
+
|
|
103
|
+
@classmethod
|
|
104
|
+
def from_dict(cls, client: Client, value: Mapping[str, Any]) -> Volume:
|
|
105
|
+
return cls(client, value["name"], value["size"])
|
|
106
|
+
|
|
107
|
+
@property
|
|
108
|
+
def _root(self) -> dict[str, str]:
|
|
109
|
+
return {"volume": self.name}
|
|
110
|
+
|
|
111
|
+
async def mounts(self) -> list[VolumeMountListOutputItem]:
|
|
112
|
+
"""The mounts in it, without their credentials."""
|
|
113
|
+
items = await self.client._call("virtx_client_list_volume_mount", args(volume=self.name))
|
|
114
|
+
return [VolumeMountListOutputItem.from_dict(item) for item in items]
|
|
115
|
+
|
|
116
|
+
async def mount(self, path: str, source: MountSource) -> VolumeMountListOutputItem:
|
|
117
|
+
"""Mount ``source`` at ``path`` in it, a directory the mount creates."""
|
|
118
|
+
output = await self.client._call(
|
|
119
|
+
"virtx_client_create_volume_mount",
|
|
120
|
+
args(volume=self.name, path=path, source=source.to_dict()),
|
|
121
|
+
)
|
|
122
|
+
return VolumeMountListOutputItem.from_dict(output)
|
|
123
|
+
|
|
124
|
+
async def unmount(self, path: str) -> None:
|
|
125
|
+
"""Take away the mount at ``path``, leaving its source as it is."""
|
|
126
|
+
await self.client._call(
|
|
127
|
+
"virtx_client_remove_volume_mount", args(volume=self.name, path=path)
|
|
128
|
+
)
|
|
129
|
+
|
|
130
|
+
async def remove(self) -> None:
|
|
131
|
+
"""Delete it and everything in it."""
|
|
132
|
+
await self.client._call("virtx_client_remove_volume", args(name=self.name))
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
@dataclass(frozen=True)
|
|
136
|
+
class VolumeMountListOutputItem:
|
|
137
|
+
"""One mount in a volume, as ``Volume.mounts`` and ``Volume.mount`` answer it. Its
|
|
138
|
+
credentials are not answered."""
|
|
139
|
+
|
|
140
|
+
path: str
|
|
141
|
+
"""Where it is mounted."""
|
|
142
|
+
|
|
143
|
+
mount_type: MountType
|
|
144
|
+
|
|
145
|
+
@classmethod
|
|
146
|
+
def from_dict(cls, value: Mapping[str, Any]) -> VolumeMountListOutputItem:
|
|
147
|
+
return cls(value["path"], MountType(value["mount_type"]))
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: virtx
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: A virtx client for Python, over libvirtx_core's C ABI.
|
|
5
|
+
License-Expression: Apache-2.0
|
|
6
|
+
Requires-Python: >=3.11
|
|
7
|
+
Description-Content-Type: text/markdown
|
|
8
|
+
|
|
9
|
+
# virtx for Python
|
|
10
|
+
|
|
11
|
+
A virtx client over the C ABI of `libvirtx_core` (`virtx-core/include/virtx.h`), reached with `ctypes`: the package has no extension module of its own, and a wheel carries the library for its platform beside its Python files.
|
|
12
|
+
|
|
13
|
+
The package also installs the `virtx` command, the one in `libvirtx_core`: `uvx virtx images`.
|
|
14
|
+
|
|
15
|
+
A build, pull or push of an image, and a process in a sandbox, is a job the server runs apart from the request that started it.
|
|
16
|
+
The method that starts one answers a `StartedJob`, sent when it is first awaited, iterated or completed: `complete` follows the job to its end and answers what it ended with; iterated, it yields the job's log, each entry numbered so a reader can resume `after` one, until its end entry; awaited, it is the job.
|
|
17
|
+
Stopping early leaves the job running; `ImageJob.remove` or `SandboxJob.remove` cancels it.
|
|
18
|
+
|
|
19
|
+
```python
|
|
20
|
+
import asyncio
|
|
21
|
+
from virtx import Client, Recipe, VirtxError
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
async def main():
|
|
25
|
+
with Client.spawn() as client:
|
|
26
|
+
recipe = Recipe("alpine:3.20").run("apk add jq")
|
|
27
|
+
try:
|
|
28
|
+
digest = await client.build_image(recipe, "jq:latest").complete(print=True)
|
|
29
|
+
print("built", digest)
|
|
30
|
+
except VirtxError as failed:
|
|
31
|
+
print("failed", failed)
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
asyncio.run(main())
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`complete(print=True)` prints each line of the log as it is read.
|
|
38
|
+
An image job that fails raises its `VirtxError`, from `complete` and from its log alike, in place of an `ImageJobEnd`.
|
|
39
|
+
|
|
40
|
+
Awaited, the same call answers the job, an `ImageJob` that carries its client, and its log is read after with its `log`, from its start or `after` an entry: by another reader, or after a reconnect.
|
|
41
|
+
|
|
42
|
+
```python
|
|
43
|
+
job = await client.pull_image("alpine:3.20")
|
|
44
|
+
async for entry in job.log(after=1): # from its second entry
|
|
45
|
+
...
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
A sandbox runs commands as jobs the same way: `create_sandbox` answers a `Sandbox` that carries its client, and its `exec` starts one: completed, it answers the exit code; iterated, it yields its output, a line as it is written, then how it ended.
|
|
49
|
+
Awaited, it is a `SandboxJob` that carries its client too: what signals the process, writes to its stdin and reads its log again.
|
|
50
|
+
One value awaited and then iterated reads the log of the one job it started.
|
|
51
|
+
|
|
52
|
+
```python
|
|
53
|
+
from virtx import SandboxJobEnd, Stderr, Stdout
|
|
54
|
+
|
|
55
|
+
sandbox = await client.create_sandbox("alpine:3.20")
|
|
56
|
+
print("exited", await sandbox.exec(["uname", "-a"]).complete(print=True))
|
|
57
|
+
run = sandbox.exec(["echo", "hi"])
|
|
58
|
+
job = await run
|
|
59
|
+
print("started", job.id)
|
|
60
|
+
async for entry in run:
|
|
61
|
+
match entry.entry:
|
|
62
|
+
case Stdout(line) | Stderr(line):
|
|
63
|
+
print(line)
|
|
64
|
+
case SandboxJobEnd(code):
|
|
65
|
+
print("exited", code)
|
|
66
|
+
await sandbox.remove()
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
```python
|
|
70
|
+
cat = await sandbox.exec(["cat"], stdin=True)
|
|
71
|
+
await cat.write_stdin("hello\n", eof=True)
|
|
72
|
+
async for entry in cat.log():
|
|
73
|
+
...
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
A sandbox's port is reached through a `PortForwarder`, opened over the client with the `url` `create_sandbox` answered for it: an address on this machine's loopback, for any TCP client, until it is closed.
|
|
77
|
+
|
|
78
|
+
```python
|
|
79
|
+
from virtx import PortForwarder
|
|
80
|
+
|
|
81
|
+
sandbox = await client.create_sandbox("alpine:3.20", ports=[8000])
|
|
82
|
+
with PortForwarder.open(client, sandbox.ports[0].url) as forwarder:
|
|
83
|
+
print("reach it at", forwarder.address)
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
A volume is answered the same way, as a `Volume` that carries its client. It and a `Sandbox` read and write their files, with a path relative to their root. A sandbox's are its root as its processes see it, while its VM runs. A file is written and read whole, or read in part; a directory lists its entries and goes with everything in it.
|
|
87
|
+
|
|
88
|
+
```python
|
|
89
|
+
volume = await client.create_volume("data")
|
|
90
|
+
await volume.create_dir("in")
|
|
91
|
+
await volume.write_file("in/notes.txt", b"hello")
|
|
92
|
+
for entry in await volume.read_dir("in"):
|
|
93
|
+
print(entry.name, entry.metadata.size)
|
|
94
|
+
print(await volume.read_file("in/notes.txt"))
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
What acts on a sandbox, a volume or a sandbox job is its handle. One known only by its id or name is had again with `get_sandbox`, `get_volume` or a sandbox's `job`: `await (await client.get_volume("data")).read_file("in/notes.txt")`.
|
|
98
|
+
|
|
99
|
+
The library is the one given to `virtx.load(path)`, or `$VIRTX_CORE_LIB`, or the copy in the package, or the system loader's search for `libvirtx_core`. One process opens one, so another module sharing a client opens `virtx.library_path()` and takes the pointer from `client.clone().into_raw()`.
|
|
100
|
+
|
|
101
|
+
## Tests
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
uv run pytest
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
The tests build `libvirtx_core` with cargo first, and run against the real servers, which `cargo xtask fixture` builds and serves over a home of the run's own for them.
|
|
108
|
+
They boot machines, so they need `cargo xtask init` and `cargo xtask build kernel` first.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
virtx/__init__.py,sha256=z3SqcNWVK9gAw94-PeOkaGf-4eu3VpIbe3YasZ_vDpE,4168
|
|
2
|
+
virtx/_cli.py,sha256=HaZs_EkN84NRv_fv-iqlPxb-hDAxN2OjyLecyImCAX0,598
|
|
3
|
+
virtx/_library.py,sha256=VuhTwQJmaXopsQIHmrqI_qkH6Ws33U5zB-7LZFEOn3g,12249
|
|
4
|
+
virtx/client.py,sha256=L_XjzzEGTXN_YXryMlYvvcLF--XY18ZOvLXIbJbo7Q4,20214
|
|
5
|
+
virtx/files.py,sha256=8VajL-eDvbqLpQb_eAdGLeRY3tawqPvfWEKO3CcedEI,6043
|
|
6
|
+
virtx/image.py,sha256=SJcOUQz8GclkeNQWD_zNFTeLIc3Uii40n6H9yYHV0us,9083
|
|
7
|
+
virtx/job.py,sha256=_-wtZb0tfeu4D2JIQq7e6iw_eR2EYByazGKk9STWvsY,2682
|
|
8
|
+
virtx/portforward.py,sha256=i_kOVHm51TcD8VDnryzDvNH2a_ELIBvQIPr1C4b5HmU,2206
|
|
9
|
+
virtx/project.py,sha256=iO_6nx89f5uYAHIcHvlHZ2oQ16kwK4T2R7qey-buv-A,3259
|
|
10
|
+
virtx/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
11
|
+
virtx/sandbox.py,sha256=80Qk-5XvKIko8WYq9WZPRy0blJ2YE4R6ckZ0E3nbqJw,8853
|
|
12
|
+
virtx/virtx_core.dll,sha256=zZCLBvL8VSQfg8cCVf80A4KqUqcD9JE1v36d2ppokp4,10959872
|
|
13
|
+
virtx/volume.py,sha256=8E3VhO_5nYTTUOoJsii0Y1VeZ0ytyPXRmAXrrQ4Kgjk,4640
|
|
14
|
+
virtx-0.2.0.dist-info/METADATA,sha256=p7G2TOtdOMtM-fe8iUet433OO_Kfx9oWr5TehyV4rzI,4959
|
|
15
|
+
virtx-0.2.0.dist-info/WHEEL,sha256=lpoBGaIUIidvvdZ4qRAP61bBKYJdt4FI3WXFL50Gzyo,94
|
|
16
|
+
virtx-0.2.0.dist-info/entry_points.txt,sha256=F6-EImgbHmDn3zTsVkJiAf580otuYv2H6RACEVJfCQM,42
|
|
17
|
+
virtx-0.2.0.dist-info/RECORD,,
|