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/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,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: false
4
+ Tag: py3-none-win_amd64
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ virtx = virtx._cli:main