zumen 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.
zumen/__init__.py ADDED
@@ -0,0 +1,236 @@
1
+ """zumen の C ABI を、標準ライブラリの ctypes で呼ぶ薄いラッパー(決定 0011・0195)。
2
+
3
+ ネイティブのライブラリ(zumen_abi1.dll・libzumen_abi1.so・libzumen_abi1.dylib)を読み込み、API の関数
4
+ (schema/boundary.toml)を、セッションのメソッドにして出す。要求と応答の型は messages.py にある。
5
+ ctypes は、ネイティブの関数を呼ぶ間 GIL を手放すので、ほかのスレッドから cancel を呼べる。
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import ctypes
11
+ import json
12
+ import os
13
+ import struct
14
+ import sys
15
+ from typing import Any, Mapping, Optional, Union
16
+
17
+ from .constants import (
18
+ ABI_VERSION,
19
+ FUNCTIONS,
20
+ SCENE_MAJOR,
21
+ SCENE_MINOR,
22
+ SCENE_SECTIONS,
23
+ SCENE_VALUES,
24
+ SCHEMA_MAJOR,
25
+ SCHEMA_MINOR,
26
+ STATUS,
27
+ VERSION,
28
+ Buf,
29
+ )
30
+ from .scene import Scene, read_scene
31
+
32
+ __all__ = [
33
+ "ABI_VERSION",
34
+ "SCENE_MAJOR",
35
+ "SCENE_MINOR",
36
+ "SCENE_SECTIONS",
37
+ "SCENE_VALUES",
38
+ "SCHEMA_MAJOR",
39
+ "SCHEMA_MINOR",
40
+ "STATUS",
41
+ "VERSION",
42
+ "Scene",
43
+ "Session",
44
+ "Zumen",
45
+ "ZumenError",
46
+ "load",
47
+ "read_scene",
48
+ ]
49
+
50
+ BytesLike = Union[str, bytes, bytearray, memoryview, None]
51
+
52
+
53
+ class ZumenError(Exception):
54
+ """API の関数が ok でない状態を返した"""
55
+
56
+ def __init__(self, operation: str, code: int, data: Optional[bytes]) -> None:
57
+ self.operation = operation
58
+ """呼んだ API の関数"""
59
+ self.code = code
60
+ """状態コード"""
61
+ self.status = STATUS.get(code, f"unknown({code})")
62
+ """状態コードの名前"""
63
+ self.data = data
64
+ """応答の JSON。書かれなかったときは None"""
65
+ super().__init__(f"{operation} が {self.status} を返した")
66
+
67
+ @property
68
+ def response(self) -> Optional[Any]:
69
+ """応答。書かれなかったときは None"""
70
+ return None if self.data is None else json.loads(self.data)
71
+
72
+
73
+ def _to_bytes(value: BytesLike) -> bytes:
74
+ if value is None:
75
+ return b""
76
+ if isinstance(value, str):
77
+ return value.encode("utf-8")
78
+ if isinstance(value, bytes):
79
+ return value
80
+ if isinstance(value, (bytearray, memoryview)):
81
+ return bytes(value)
82
+ raise TypeError("バイト列か文字列を渡す")
83
+
84
+
85
+ def _dumps(value: Any) -> bytes:
86
+ return json.dumps(value, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
87
+
88
+
89
+ class _Core:
90
+ """読み込んだライブラリと、API の関数"""
91
+
92
+ def __init__(self, library: ctypes.CDLL) -> None:
93
+ missing = []
94
+ for name, (restype, argtypes) in FUNCTIONS.items():
95
+ try:
96
+ function = getattr(library, name)
97
+ except AttributeError:
98
+ missing.append(name)
99
+ continue
100
+ function.restype = restype
101
+ function.argtypes = argtypes
102
+ if missing:
103
+ raise OSError(f"zumen のライブラリでない(ない関数: {', '.join(missing)})")
104
+ version = library.zm_abi_version()
105
+ if version != ABI_VERSION:
106
+ raise OSError(f"ABI のメジャーバージョンが {version}(このラッパーは {ABI_VERSION})")
107
+ self.lib = library
108
+
109
+ def with_buf(self, fn: Any) -> tuple:
110
+ """zm_buf を用意して fn に渡し、書かれたバイト列を写して返す"""
111
+ buf = Buf()
112
+ code = fn(ctypes.byref(buf))
113
+ try:
114
+ if buf.ptr:
115
+ data: Optional[bytes] = ctypes.string_at(buf.ptr, buf.len)
116
+ else:
117
+ data = b"" if code == 0 else None
118
+ finally:
119
+ self.lib.zm_free(ctypes.byref(buf))
120
+ return code, data
121
+
122
+
123
+ class Session:
124
+ """セッション。入力と、直前の呼び出しのバイナリの結果を持つ。使い終わったら close で閉じる。
125
+
126
+ with の文で使うと、抜けるときに閉じる。1 つのセッションは、一度に 1 つのスレッドだけが使う。cancel だけは、
127
+ どのスレッドからも呼べる。
128
+ """
129
+
130
+ def __init__(self, core: _Core, handle: Optional[int]) -> None:
131
+ self._core = core
132
+ self._handle = handle
133
+
134
+ @property
135
+ def closed(self) -> bool:
136
+ """閉じたか"""
137
+ return self._handle is None
138
+
139
+ def push(self, name: BytesLike, data: BytesLike) -> None:
140
+ """名前のついた入力に、バイト列を足す。同じ名前で何回か呼ぶと、後ろに足していく"""
141
+ name = _to_bytes(name)
142
+ data = _to_bytes(data)
143
+ code = self._core.lib.zm_push(self._handle, name, len(name), data, len(data))
144
+ if code != 0:
145
+ raise ZumenError("zm_push", code, None)
146
+
147
+ def call_bytes(self, request: BytesLike) -> bytes:
148
+ """要求の JSON(文字列かバイト列)を渡し、応答の JSON のバイト列を受け取る"""
149
+ request = _to_bytes(request)
150
+ lib = self._core.lib
151
+ code, data = self._core.with_buf(lambda buf: lib.zm_call(self._handle, request, len(request), buf))
152
+ if code != 0:
153
+ raise ZumenError("zm_call", code, data)
154
+ return data
155
+
156
+ def call(self, request: Mapping[str, Any]) -> Any:
157
+ """要求を渡し、応答(messages.Response の形の dict)を受け取る。失敗した応答は、ZumenError の response にある"""
158
+ return json.loads(self.call_bytes(_dumps(request)))
159
+
160
+ def take(self, blob: int) -> bytes:
161
+ """直前の call が作ったバイナリの結果を、応答の blobs にある番号で取り出す"""
162
+ lib = self._core.lib
163
+ code, data = self._core.with_buf(lambda buf: lib.zm_take(self._handle, blob, buf))
164
+ if code != 0:
165
+ raise ZumenError("zm_take", code, None)
166
+ return data
167
+
168
+ def cancel(self) -> None:
169
+ """動いている呼び出しを止める。動いている呼び出しがなければ、何もしない"""
170
+ self._core.lib.zm_cancel(self._handle)
171
+
172
+ def close(self) -> None:
173
+ """セッションを閉じる。閉じたあとの呼び出しは、invalid の ZumenError になる"""
174
+ handle, self._handle = self._handle, None
175
+ if handle is not None:
176
+ self._core.lib.zm_session_close(handle)
177
+
178
+ def __enter__(self) -> Session:
179
+ return self
180
+
181
+ def __exit__(self, *_: object) -> None:
182
+ self.close()
183
+
184
+ def __del__(self) -> None:
185
+ try:
186
+ self.close()
187
+ except Exception:
188
+ # 終了の途中で、ライブラリが先に消えていることがある
189
+ pass
190
+
191
+
192
+ class Zumen:
193
+ """読み込んだネイティブのライブラリ"""
194
+
195
+ def __init__(self, library: ctypes.CDLL) -> None:
196
+ self._core = _Core(library)
197
+
198
+ def abi_version(self) -> int:
199
+ """ABI のメジャーバージョン"""
200
+ return self._core.lib.zm_abi_version()
201
+
202
+ def open(self, options: Union[Mapping[str, Any], BytesLike] = None) -> Session:
203
+ """セッションを作る。設定(session_options)は、値か JSON の文字列かバイト列で渡す。渡さなければ既定の設定"""
204
+ data = _dumps(options) if isinstance(options, Mapping) else _to_bytes(options)
205
+ handle = ctypes.c_void_p()
206
+ code = self._core.lib.zm_session_new(data, len(data), ctypes.byref(handle))
207
+ if code != 0:
208
+ raise ZumenError("zm_session_new", code, None)
209
+ return Session(self._core, handle.value)
210
+
211
+
212
+ def _bundled() -> str:
213
+ """wheel に入れたネイティブのライブラリの道筋(決定 0205)"""
214
+ if sys.platform == "win32":
215
+ name = "zumen_abi1.dll"
216
+ elif sys.platform == "darwin":
217
+ name = "libzumen_abi1.dylib"
218
+ else:
219
+ name = "libzumen_abi1.so"
220
+ return os.path.join(os.path.dirname(os.path.abspath(__file__)), "_native", name)
221
+
222
+
223
+ def load(path: Union[str, os.PathLike, None] = None) -> Zumen:
224
+ """ネイティブのライブラリを、ファイルの道筋から読み込み、ABI のメジャーバージョンを確かめる。
225
+
226
+ 道筋を渡さなければ、wheel に入れたライブラリ(zumen/_native)を読む(決定 0205)。
227
+ 32 bit の Windows では、関数を stdcall で呼ぶ(決定 0011)。
228
+ """
229
+ path = os.path.abspath(os.fspath(path)) if path is not None else _bundled()
230
+ if not os.path.isfile(path):
231
+ raise OSError(f"zumen のネイティブのライブラリがない: {path}")
232
+ if sys.platform == "win32" and struct.calcsize("P") == 4:
233
+ library: ctypes.CDLL = ctypes.WinDLL(path)
234
+ else:
235
+ library = ctypes.CDLL(path)
236
+ return Zumen(library)
Binary file