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/image.py
ADDED
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
"""The images the server keeps, and the names it keeps them under.
|
|
2
|
+
|
|
3
|
+
- Digest: the name of an image, the hash of its manifest, as ``algorithm:hex`` (such as
|
|
4
|
+
``sha256:0123abcd...``). It identifies one image's content and never changes.
|
|
5
|
+
- Reference: a name a person gives an image, as ``name:tag`` (such as ``alpine:3.20``). It points
|
|
6
|
+
at one image, and can be moved to another. Any number of references may point at one image.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import builtins
|
|
12
|
+
import re
|
|
13
|
+
import sys
|
|
14
|
+
from collections.abc import AsyncIterator, Iterable, Mapping
|
|
15
|
+
from contextlib import aclosing
|
|
16
|
+
from dataclasses import dataclass, field
|
|
17
|
+
from enum import Enum
|
|
18
|
+
from typing import TYPE_CHECKING, Any
|
|
19
|
+
|
|
20
|
+
from ._library import VirtxError, args
|
|
21
|
+
from .job import LogEntry, Truncated
|
|
22
|
+
|
|
23
|
+
if TYPE_CHECKING:
|
|
24
|
+
from .client import Client
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
@dataclass(frozen=True)
|
|
28
|
+
class ImageTag:
|
|
29
|
+
"""An image by a tag on it, as ``name:tag``."""
|
|
30
|
+
|
|
31
|
+
tag: str
|
|
32
|
+
|
|
33
|
+
def to_dict(self) -> dict[str, Any]:
|
|
34
|
+
"""As the wire has it."""
|
|
35
|
+
return {"type": "tag", "tag": self.tag}
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
@dataclass(frozen=True)
|
|
39
|
+
class ImageDigest:
|
|
40
|
+
"""An image by the digest of its manifest, as ``algorithm:hex``."""
|
|
41
|
+
|
|
42
|
+
digest: str
|
|
43
|
+
|
|
44
|
+
def to_dict(self) -> dict[str, Any]:
|
|
45
|
+
"""As the wire has it."""
|
|
46
|
+
return {"type": "digest", "digest": self.digest}
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
ImageName = ImageTag | ImageDigest
|
|
50
|
+
"""An image, by a tag on it or by its digest."""
|
|
51
|
+
|
|
52
|
+
_DIGEST = re.compile(r"(sha256:[0-9a-f]{64}|sha512:[0-9a-f]{128})")
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def image_name(image: str | ImageName) -> ImageName:
|
|
56
|
+
"""``image`` as the wire names one: a full ``sha256:`` or ``sha512:`` digest is a digest, any
|
|
57
|
+
other string a tag. An ``ImageName`` is taken as it is."""
|
|
58
|
+
if not isinstance(image, str):
|
|
59
|
+
return image
|
|
60
|
+
if _DIGEST.fullmatch(image):
|
|
61
|
+
return ImageDigest(image)
|
|
62
|
+
return ImageTag(image)
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
class Recipe:
|
|
66
|
+
"""A base and the steps over it, which the server builds: ``Recipe("alpine:3.20").run("apk
|
|
67
|
+
add jq")``. Each step returns the recipe, so they chain."""
|
|
68
|
+
|
|
69
|
+
def __init__(self, base: str, steps: Iterable[Mapping[str, Any]] = ()) -> None:
|
|
70
|
+
self.base = base
|
|
71
|
+
self.steps: list[Mapping[str, Any]] = list(steps)
|
|
72
|
+
|
|
73
|
+
def run(self, command: str) -> Recipe:
|
|
74
|
+
"""A command, run through ``sh -c`` with every earlier ``env``."""
|
|
75
|
+
self.steps.append({"run": command})
|
|
76
|
+
return self
|
|
77
|
+
|
|
78
|
+
def env(self, key: str, value: str) -> Recipe:
|
|
79
|
+
"""A variable for every later ``run`` and the built image's config."""
|
|
80
|
+
self.steps.append({"env": {"key": key, "value": value}})
|
|
81
|
+
return self
|
|
82
|
+
|
|
83
|
+
def workdir(self, directory: str) -> Recipe:
|
|
84
|
+
"""Where later steps run, and the built image's working directory."""
|
|
85
|
+
self.steps.append({"workdir": directory})
|
|
86
|
+
return self
|
|
87
|
+
|
|
88
|
+
def to_dict(self) -> dict[str, Any]:
|
|
89
|
+
"""As the wire has it."""
|
|
90
|
+
return {"v": 1, "base": self.base, "steps": list(self.steps)}
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
@dataclass(frozen=True)
|
|
94
|
+
class BasicAuth:
|
|
95
|
+
"""A username, and a password or an access token the registry takes in its place."""
|
|
96
|
+
|
|
97
|
+
username: str
|
|
98
|
+
password: str = field(repr=False)
|
|
99
|
+
|
|
100
|
+
def to_dict(self) -> dict[str, Any]:
|
|
101
|
+
"""As the wire has it."""
|
|
102
|
+
return {"type": "basic", "username": self.username, "password": self.password}
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
@dataclass(frozen=True)
|
|
106
|
+
class BearerAuth:
|
|
107
|
+
"""A token taken as it is, sent as ``Authorization: Bearer <token>``: a registry's, or the
|
|
108
|
+
server's own, as :meth:`Client.connect` takes it."""
|
|
109
|
+
|
|
110
|
+
token: str = field(repr=False)
|
|
111
|
+
|
|
112
|
+
def to_dict(self) -> dict[str, Any]:
|
|
113
|
+
"""As the wire has it."""
|
|
114
|
+
return {"type": "bearer", "token": self.token}
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
RegistryAuth = BasicAuth | BearerAuth
|
|
118
|
+
"""Credentials for a remote image registry."""
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
class ImageJobKind(str, Enum):
|
|
122
|
+
"""What an image job does."""
|
|
123
|
+
|
|
124
|
+
PULL = "pull"
|
|
125
|
+
PUSH = "push"
|
|
126
|
+
BUILD = "build"
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
@dataclass(frozen=True)
|
|
130
|
+
class ImageJob:
|
|
131
|
+
"""A build, pull or push the server runs, as ``build_image``, ``pull_image``,
|
|
132
|
+
``push_image`` and ``get_image_job`` answer it, and the client that reaches it: what reads
|
|
133
|
+
its log. Dropping it leaves the job; ``remove`` removes it."""
|
|
134
|
+
|
|
135
|
+
client: Client = field(repr=False, compare=False)
|
|
136
|
+
"""The client its requests go through."""
|
|
137
|
+
|
|
138
|
+
id: str
|
|
139
|
+
"""The job's id, which every request about it names it by."""
|
|
140
|
+
|
|
141
|
+
kind: ImageJobKind
|
|
142
|
+
|
|
143
|
+
reference: str
|
|
144
|
+
"""The reference it was started with."""
|
|
145
|
+
|
|
146
|
+
running: bool
|
|
147
|
+
"""Whether it runs still."""
|
|
148
|
+
|
|
149
|
+
digest: str | None = None
|
|
150
|
+
"""Once it has succeeded, as ``algorithm:hex``: the digest of the image a pull or build
|
|
151
|
+
left here, or of the manifest a push put on the registry."""
|
|
152
|
+
|
|
153
|
+
error: str | None = None
|
|
154
|
+
"""Once it has failed, why, for a person."""
|
|
155
|
+
|
|
156
|
+
@classmethod
|
|
157
|
+
def from_dict(cls, client: Client, value: Mapping[str, Any]) -> ImageJob:
|
|
158
|
+
return cls(
|
|
159
|
+
client,
|
|
160
|
+
value["id"],
|
|
161
|
+
ImageJobKind(value["kind"]),
|
|
162
|
+
value["reference"],
|
|
163
|
+
value["running"],
|
|
164
|
+
value.get("digest"),
|
|
165
|
+
value.get("error"),
|
|
166
|
+
)
|
|
167
|
+
|
|
168
|
+
async def get(self) -> ImageJob:
|
|
169
|
+
"""It as the server has it now."""
|
|
170
|
+
output = await self.client._call("virtx_client_get_image_job", args(id=self.id))
|
|
171
|
+
return ImageJob.from_dict(self.client, output)
|
|
172
|
+
|
|
173
|
+
async def log(self, after: int | None = None) -> AsyncIterator[LogEntry[ImageJobEntry]]:
|
|
174
|
+
"""Its log, from its start or after its ``after``th entry, until its ``ImageJobEnd``,
|
|
175
|
+
or the ``VirtxError`` in its place if the job failed. Closing it leaves the job as it
|
|
176
|
+
is."""
|
|
177
|
+
async for item in self.client._items(
|
|
178
|
+
"virtx_client_image_job_log", args(id=self.id, after=after)
|
|
179
|
+
):
|
|
180
|
+
yield image_job_entry(item)
|
|
181
|
+
|
|
182
|
+
async def complete(self, print: bool = False) -> str:
|
|
183
|
+
"""Follow it to its end, printing each line of its log if ``print``: the digest it ended
|
|
184
|
+
with. Raises ``VirtxError`` with why it failed."""
|
|
185
|
+
async with aclosing(self.log()) as log:
|
|
186
|
+
async for item in log:
|
|
187
|
+
match item.entry:
|
|
188
|
+
case Log(line) if print:
|
|
189
|
+
builtins.print(line)
|
|
190
|
+
case Truncated() if print:
|
|
191
|
+
builtins.print(
|
|
192
|
+
"(the log reached the server's limit; the rest is not kept)",
|
|
193
|
+
file=sys.stderr,
|
|
194
|
+
)
|
|
195
|
+
case ImageJobEnd(digest):
|
|
196
|
+
return digest
|
|
197
|
+
raise VirtxError("the job was removed before it ended", source="job")
|
|
198
|
+
|
|
199
|
+
async def remove(self) -> None:
|
|
200
|
+
"""Cancel it if it runs, and forget it."""
|
|
201
|
+
await self.client._call("virtx_client_remove_image_job", args(id=self.id))
|
|
202
|
+
|
|
203
|
+
|
|
204
|
+
@dataclass(frozen=True)
|
|
205
|
+
class Log:
|
|
206
|
+
"""A line of an image job's log."""
|
|
207
|
+
|
|
208
|
+
line: str
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
@dataclass(frozen=True)
|
|
212
|
+
class ImageJobEnd:
|
|
213
|
+
"""How an image job that succeeded ended, last in its log. One that failed ends its log
|
|
214
|
+
with the ``VirtxError`` it failed with instead."""
|
|
215
|
+
|
|
216
|
+
digest: str
|
|
217
|
+
"""The digest of the image a pull or build left here, or of the manifest a push put on
|
|
218
|
+
the registry, as ``algorithm:hex``."""
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
ImageJobEntry = Log | Truncated | ImageJobEnd
|
|
222
|
+
"""An entry of an image job's log."""
|
|
223
|
+
|
|
224
|
+
|
|
225
|
+
def image_job_entry(item: Mapping[str, Any]) -> LogEntry[ImageJobEntry]:
|
|
226
|
+
"""An item of ``ImageJob.log``'s stream, as ``{"id": n, "log": "..."}`` and the like."""
|
|
227
|
+
entry: ImageJobEntry
|
|
228
|
+
if "log" in item:
|
|
229
|
+
entry = Log(item["log"])
|
|
230
|
+
elif "truncated" in item:
|
|
231
|
+
entry = Truncated()
|
|
232
|
+
else:
|
|
233
|
+
entry = ImageJobEnd(item["end"]["digest"])
|
|
234
|
+
return LogEntry(item["id"], entry)
|
|
235
|
+
|
|
236
|
+
|
|
237
|
+
@dataclass(frozen=True)
|
|
238
|
+
class ImageListOutputItem:
|
|
239
|
+
"""One tag on the server's images."""
|
|
240
|
+
|
|
241
|
+
reference: str
|
|
242
|
+
"""The tag, as ``name:tag``."""
|
|
243
|
+
|
|
244
|
+
digest: str
|
|
245
|
+
"""The digest of the manifest it points at, as ``algorithm:hex``."""
|
|
246
|
+
|
|
247
|
+
@classmethod
|
|
248
|
+
def from_dict(cls, value: Mapping[str, Any]) -> ImageListOutputItem:
|
|
249
|
+
return cls(value["reference"], value["digest"])
|
|
250
|
+
|
|
251
|
+
|
|
252
|
+
@dataclass(frozen=True)
|
|
253
|
+
class ImageDownloadOutput:
|
|
254
|
+
"""What ``download_image`` wrote."""
|
|
255
|
+
|
|
256
|
+
digest: str
|
|
257
|
+
"""The digest of the manifest written, as ``algorithm:hex``."""
|
|
258
|
+
|
|
259
|
+
@classmethod
|
|
260
|
+
def from_dict(cls, value: Mapping[str, Any]) -> ImageDownloadOutput:
|
|
261
|
+
return cls(value["digest"])
|
|
262
|
+
|
|
263
|
+
|
|
264
|
+
@dataclass(frozen=True)
|
|
265
|
+
class ImageUploadOutput:
|
|
266
|
+
"""What ``upload_image`` uploaded."""
|
|
267
|
+
|
|
268
|
+
digest: str
|
|
269
|
+
"""The digest of the manifest uploaded, as ``algorithm:hex``."""
|
|
270
|
+
|
|
271
|
+
@classmethod
|
|
272
|
+
def from_dict(cls, value: Mapping[str, Any]) -> ImageUploadOutput:
|
|
273
|
+
return cls(value["digest"])
|
|
274
|
+
|
|
275
|
+
|
|
276
|
+
@dataclass(frozen=True)
|
|
277
|
+
class ImagePruneOutput:
|
|
278
|
+
"""What ``prune_image`` deleted."""
|
|
279
|
+
|
|
280
|
+
images: list[str]
|
|
281
|
+
"""The digest of each image deleted, as ``algorithm:hex``."""
|
|
282
|
+
|
|
283
|
+
reclaimed: int
|
|
284
|
+
"""How many bytes the server freed."""
|
|
285
|
+
|
|
286
|
+
@classmethod
|
|
287
|
+
def from_dict(cls, value: Mapping[str, Any]) -> ImagePruneOutput:
|
|
288
|
+
return cls(list(value["images"]), value["reclaimed"])
|
virtx/job.py
ADDED
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
"""What every job's log shares: each entry numbered, and the mark of a log cut short.
|
|
2
|
+
|
|
3
|
+
A job, an image's build, pull or push or a process in a sandbox, runs on the server apart from
|
|
4
|
+
the request that started it. Its log is read with the client's ``*_job_log``, from its start or
|
|
5
|
+
after an entry's ``id``, until its end entry, or the ``VirtxError`` it failed with. A request
|
|
6
|
+
that starts one answers a ``StartedJob``: awaited, the job; iterated, its log; or followed to its
|
|
7
|
+
end with ``complete``.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import asyncio
|
|
13
|
+
from collections.abc import AsyncGenerator, AsyncIterator, Awaitable, Callable, Generator
|
|
14
|
+
from dataclasses import dataclass
|
|
15
|
+
from typing import Any, Generic, Protocol, TypeVar
|
|
16
|
+
|
|
17
|
+
J = TypeVar("J")
|
|
18
|
+
E = TypeVar("E")
|
|
19
|
+
T = TypeVar("T")
|
|
20
|
+
T_co = TypeVar("T_co", covariant=True)
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
class _Completes(Protocol[T_co]):
|
|
24
|
+
"""A job, which ``complete`` follows to its end."""
|
|
25
|
+
|
|
26
|
+
def complete(self, print: bool = False) -> Awaitable[T_co]: ...
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
@dataclass(frozen=True)
|
|
30
|
+
class LogEntry(Generic[E]):
|
|
31
|
+
"""One entry of a job's log, and its number in it, ``1`` for the first: what ``after``
|
|
32
|
+
resumes after."""
|
|
33
|
+
|
|
34
|
+
id: int
|
|
35
|
+
entry: E
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
@dataclass(frozen=True)
|
|
39
|
+
class Truncated:
|
|
40
|
+
"""The log reached the server's limit: nothing after it is kept or sent, but the end."""
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
class StartedJob(Generic[J, E]):
|
|
44
|
+
"""A request that starts a job, sent the first time this is awaited or iterated, and only
|
|
45
|
+
then: awaited, it answers the job; iterated, it yields the job's log, each a ``LogEntry``,
|
|
46
|
+
until its end entry; ``complete``, the job's own ``complete`` once started. Each way reads
|
|
47
|
+
the one job it started. Closing the iteration leaves the job running; cancelling it is the
|
|
48
|
+
client's ``remove_*_job``."""
|
|
49
|
+
|
|
50
|
+
def __init__(
|
|
51
|
+
self,
|
|
52
|
+
start: Callable[[], Awaitable[J]],
|
|
53
|
+
log: Callable[[J], AsyncIterator[LogEntry[E]]],
|
|
54
|
+
) -> None:
|
|
55
|
+
self._start = start
|
|
56
|
+
self._log = log
|
|
57
|
+
self._job: asyncio.Future[J] | None = None
|
|
58
|
+
|
|
59
|
+
def __await__(self) -> Generator[Any, None, J]:
|
|
60
|
+
if self._job is None:
|
|
61
|
+
self._job = asyncio.ensure_future(self._start())
|
|
62
|
+
return self._job.__await__()
|
|
63
|
+
|
|
64
|
+
async def complete(self: StartedJob[_Completes[T], E], print: bool = False) -> T:
|
|
65
|
+
"""Start the job and follow it to its end, as its ``complete`` does."""
|
|
66
|
+
return await (await self).complete(print=print)
|
|
67
|
+
|
|
68
|
+
async def __aiter__(self) -> AsyncIterator[LogEntry[E]]:
|
|
69
|
+
log = self._log(await self)
|
|
70
|
+
try:
|
|
71
|
+
async for entry in log:
|
|
72
|
+
yield entry
|
|
73
|
+
finally:
|
|
74
|
+
if isinstance(log, AsyncGenerator):
|
|
75
|
+
await log.aclose()
|
virtx/portforward.py
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
"""A sandbox's port, forwarded to this machine's loopback: a ``VirtxPortForwarder*`` held."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import ctypes
|
|
6
|
+
import json
|
|
7
|
+
from typing import TYPE_CHECKING, Self
|
|
8
|
+
|
|
9
|
+
from ._library import Library, _Bytes
|
|
10
|
+
|
|
11
|
+
if TYPE_CHECKING:
|
|
12
|
+
from .client import Client
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
class PortForwarder:
|
|
16
|
+
"""A sandbox's port at an address on this machine's loopback, until it is closed.
|
|
17
|
+
|
|
18
|
+
It runs on its client's session, so the client's last close stops it. Over stdio the server
|
|
19
|
+
is on this machine and its own address is the forwarder's; over HTTP each connection to the
|
|
20
|
+
forwarder is carried to the port in a WebSocket.
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
def __init__(self, raw: int, lib: Library, address: str) -> None:
|
|
24
|
+
self._raw: int | None = raw
|
|
25
|
+
self._lib = lib
|
|
26
|
+
self.address = address
|
|
27
|
+
"""Where the port is reached, as ``host:port``."""
|
|
28
|
+
|
|
29
|
+
@classmethod
|
|
30
|
+
def open(cls, client: Client, url: str) -> PortForwarder:
|
|
31
|
+
"""Forward the port a sandbox answered ``url`` for, as ``create_sandbox`` answers one in
|
|
32
|
+
``ports``, over ``client``'s session. Blocks until it is open."""
|
|
33
|
+
lib = client._lib
|
|
34
|
+
args = json.dumps({"url": url}).encode()
|
|
35
|
+
raw = ctypes.c_void_p()
|
|
36
|
+
out = _Bytes()
|
|
37
|
+
status = lib.virtx_port_forwarder_open(
|
|
38
|
+
client._held(), args, len(args), ctypes.byref(raw), ctypes.byref(out)
|
|
39
|
+
)
|
|
40
|
+
output = lib.take(status, out)
|
|
41
|
+
return cls(raw.value or 0, lib, output["address"])
|
|
42
|
+
|
|
43
|
+
@property
|
|
44
|
+
def host(self) -> str:
|
|
45
|
+
"""The address's host: a loopback IP."""
|
|
46
|
+
return self.address.rsplit(":", 1)[0].strip("[]")
|
|
47
|
+
|
|
48
|
+
@property
|
|
49
|
+
def port(self) -> int:
|
|
50
|
+
"""The address's port."""
|
|
51
|
+
return int(self.address.rsplit(":", 1)[1])
|
|
52
|
+
|
|
53
|
+
def close(self) -> None:
|
|
54
|
+
"""Stop forwarding. Closing twice does nothing."""
|
|
55
|
+
raw, self._raw = self._raw, None
|
|
56
|
+
if raw is not None:
|
|
57
|
+
self._lib.virtx_port_forwarder_free(raw)
|
|
58
|
+
|
|
59
|
+
def __enter__(self) -> Self:
|
|
60
|
+
return self
|
|
61
|
+
|
|
62
|
+
def __exit__(self, *exc: object) -> None:
|
|
63
|
+
self.close()
|
|
64
|
+
|
|
65
|
+
def __del__(self) -> None:
|
|
66
|
+
if getattr(self, "_raw", None) is not None:
|
|
67
|
+
self.close()
|
virtx/project.py
ADDED
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
"""Projects: what everything a server keeps belongs to, and the members of each, in a role.
|
|
2
|
+
|
|
3
|
+
A client's requests are in the project ``Client.set_project`` names, or the user's own project
|
|
4
|
+
without one.
|
|
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
|
|
13
|
+
|
|
14
|
+
from ._library import args
|
|
15
|
+
|
|
16
|
+
if TYPE_CHECKING:
|
|
17
|
+
from .client import Client
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class Role(str, Enum):
|
|
21
|
+
"""What a member of a project may do there."""
|
|
22
|
+
|
|
23
|
+
MEMBER = "member"
|
|
24
|
+
"""Reaches everything in the project, reads it and its members, and leaves it."""
|
|
25
|
+
|
|
26
|
+
OWNER = "owner"
|
|
27
|
+
"""Also adds, removes and changes members, and deletes the project."""
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
@dataclass(frozen=True)
|
|
31
|
+
class Project:
|
|
32
|
+
"""One project the client has a role in, as ``list_project``, ``get_project`` and
|
|
33
|
+
``create_project`` answer it, and the client that reaches it: its members, and its removal.
|
|
34
|
+
What is in it, a client reaches with the project set (``Client.set_project``). Dropping it
|
|
35
|
+
leaves the project; ``remove`` removes it."""
|
|
36
|
+
|
|
37
|
+
client: Client = field(repr=False, compare=False)
|
|
38
|
+
"""The client its requests go through."""
|
|
39
|
+
|
|
40
|
+
id: str
|
|
41
|
+
"""What names it on any server, given it once."""
|
|
42
|
+
|
|
43
|
+
name: str
|
|
44
|
+
"""What its owner names it, among their projects."""
|
|
45
|
+
|
|
46
|
+
owner: str | None
|
|
47
|
+
"""The user whose project it is: ``None`` for one of no user's, such as one made over stdio."""
|
|
48
|
+
|
|
49
|
+
role: Role
|
|
50
|
+
"""The client's role in it, as the server answered it."""
|
|
51
|
+
|
|
52
|
+
@classmethod
|
|
53
|
+
def from_dict(cls, client: Client, value: Mapping[str, Any]) -> Project:
|
|
54
|
+
return cls(client, value["id"], value["name"], value.get("owner"), Role(value["role"]))
|
|
55
|
+
|
|
56
|
+
async def members(self) -> list[ProjectMemberListOutputItem]:
|
|
57
|
+
"""Its members, with their roles."""
|
|
58
|
+
items = await self.client._call("virtx_client_list_project_member", args(project=self.id))
|
|
59
|
+
return [ProjectMemberListOutputItem.from_dict(item) for item in items]
|
|
60
|
+
|
|
61
|
+
async def set_member(self, user: str, role: Role) -> ProjectMemberListOutputItem:
|
|
62
|
+
"""Give ``user`` ``role`` in it, adding them if they are no member."""
|
|
63
|
+
output = await self.client._call(
|
|
64
|
+
"virtx_client_set_project_member",
|
|
65
|
+
args(project=self.id, user=user, role=role),
|
|
66
|
+
)
|
|
67
|
+
return ProjectMemberListOutputItem.from_dict(output)
|
|
68
|
+
|
|
69
|
+
async def remove_member(self, user: str) -> None:
|
|
70
|
+
"""Take ``user``'s role in it away: theirs to do, leaving it, or an owner's."""
|
|
71
|
+
await self.client._call(
|
|
72
|
+
"virtx_client_remove_project_member", args(project=self.id, user=user)
|
|
73
|
+
)
|
|
74
|
+
|
|
75
|
+
async def remove(self) -> None:
|
|
76
|
+
"""Delete it and everything in it."""
|
|
77
|
+
await self.client._call("virtx_client_remove_project", args(name=self.id))
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
@dataclass(frozen=True)
|
|
81
|
+
class ProjectMemberListOutputItem:
|
|
82
|
+
"""One member of a project, as ``Project.members`` and ``Project.set_member`` answer it."""
|
|
83
|
+
|
|
84
|
+
user: str
|
|
85
|
+
"""The user as the server names them, such as an email address."""
|
|
86
|
+
|
|
87
|
+
role: Role
|
|
88
|
+
|
|
89
|
+
@classmethod
|
|
90
|
+
def from_dict(cls, value: Mapping[str, Any]) -> ProjectMemberListOutputItem:
|
|
91
|
+
return cls(value["user"], Role(value["role"]))
|
virtx/py.typed
ADDED
|
File without changes
|