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/__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
|