1
"""kilat — Python (ctypes) binding for our own storage engine.
3
No SQLite: a single append-only log with checksums, an in-memory key map and an
4
inverted index for text search. All access is serialised with an RLock.
6
from __future__ import annotations
12
from pathlib import Path
14
_HERE = Path(__file__).resolve().parent
16
os.environ.get("KILAT_LIB") or "",
17
str(_HERE / "libkilat.so"),
18
str(_HERE.parent / "libkilat.so"),
19
"/opt/kilat/libkilat.so",
23
for _p in _LIB_CANDIDATES:
24
if _p and Path(_p).exists():
27
if _lib is None: # pragma: no cover
28
raise RuntimeError("libkilat.so not found; set KILAT_LIB or run make")
30
_lib.kg_open.restype = C.c_void_p
31
_lib.kg_open.argtypes = [C.c_char_p, C.c_char_p, C.c_size_t]
32
_lib.kg_close.argtypes = [C.c_void_p]
33
_lib.kg_put.restype = C.c_int
34
_lib.kg_put.argtypes = [C.c_void_p, C.c_char_p, C.c_char_p, C.c_char_p, C.c_size_t]
35
_lib.kg_get.restype = C.c_void_p
36
_lib.kg_get.argtypes = [C.c_void_p, C.c_char_p, C.c_char_p, C.POINTER(C.c_size_t)]
37
_lib.kg_del.restype = C.c_int
38
_lib.kg_del.argtypes = [C.c_void_p, C.c_char_p, C.c_char_p]
39
_lib.kg_index_coll.restype = C.c_int
40
_lib.kg_index_coll.argtypes = [C.c_void_p, C.c_char_p]
41
_lib.kg_put_indexed.restype = C.c_int
42
_lib.kg_put_indexed.argtypes = [C.c_void_p, C.c_char_p, C.c_char_p, C.c_char_p]
43
_lib.kg_search.restype = C.c_void_p
44
_lib.kg_search.argtypes = [C.c_void_p, C.c_char_p, C.c_char_p, C.c_int]
45
_lib.kg_stats.restype = C.c_void_p
46
_lib.kg_stats.argtypes = [C.c_void_p]
47
_lib.kg_compact.restype = C.c_int
48
_lib.kg_compact.argtypes = [C.c_void_p]
49
_lib.kg_set_sync.restype = C.c_int
50
_lib.kg_set_sync.argtypes = [C.c_void_p, C.c_int]
51
_lib.kg_sync.restype = C.c_int
52
_lib.kg_sync.argtypes = [C.c_void_p]
53
_lib.kg_last_error.restype = C.c_char_p
54
_lib.kg_last_error.argtypes = [C.c_void_p]
55
_lib.kg_free.argtypes = [C.c_void_p]
57
SCAN_CB = C.CFUNCTYPE(None, C.c_char_p, C.c_char_p, C.c_void_p, C.c_size_t, C.c_void_p)
58
_lib.kg_scan.restype = C.c_int
59
_lib.kg_scan.argtypes = [C.c_void_p, C.c_char_p, SCAN_CB, C.c_void_p]
60
_lib.kg_scan_prefix.restype = C.c_int
61
_lib.kg_scan_prefix.argtypes = [C.c_void_p, C.c_char_p, C.c_char_p, SCAN_CB, C.c_void_p]
62
_lib.kg_count.restype = C.c_long
63
_lib.kg_count.argtypes = [C.c_void_p, C.c_char_p, C.c_char_p]
66
def _json_free(val: int | None) -> dict:
70
return json.loads(C.string_at(val).decode())
72
_lib.kg_free(C.c_void_p(val))
76
def __init__(self, path: str | Path):
77
err = C.create_string_buffer(256)
78
self._h = _lib.kg_open(str(path).encode(), err, 256)
80
raise RuntimeError(f"kilat: {err.value.decode()}")
81
self._lk = threading.RLock()
84
# ---------- basics ----------
85
def put(self, coll: str, key: str, value: str | bytes) -> None:
86
b = value.encode() if isinstance(value, str) else value
88
if _lib.kg_put(self._h, coll.encode(), key.encode(), b, len(b)) != 0:
89
raise RuntimeError(self.error())
91
def get(self, coll: str, key: str) -> bytes | None:
94
p = _lib.kg_get(self._h, coll.encode(), key.encode(), C.byref(n))
98
return C.string_at(p, n.value)
100
_lib.kg_free(C.c_void_p(p))
102
def get_str(self, coll: str, key: str) -> str | None:
103
v = self.get(coll, key)
104
return v.decode() if v is not None else None
106
def delete(self, coll: str, key: str) -> None:
108
if _lib.kg_del(self._h, coll.encode(), key.encode()) != 0:
109
raise RuntimeError(self.error())
111
def scan(self, coll: str) -> list[tuple[str, bytes]]:
112
out: list[tuple[str, bytes]] = []
114
def cb(_coll, key, val, vlen, _ud):
115
out.append((C.string_at(key).decode(), C.string_at(val, vlen)))
118
if _lib.kg_scan(self._h, coll.encode(), SCAN_CB(cb), None) != 0:
119
raise RuntimeError(self.error())
122
def scan_prefix(self, coll: str, prefix: str = "") -> list[tuple[str, bytes]]:
123
out: list[tuple[str, bytes]] = []
125
def cb(_coll, key, val, vlen, _ud):
126
out.append((C.string_at(key).decode(), C.string_at(val, vlen)))
129
if _lib.kg_scan_prefix(self._h, coll.encode(), prefix.encode(), SCAN_CB(cb), None) != 0:
130
raise RuntimeError(self.error())
133
def count(self, coll: str, prefix: str = "") -> int:
135
return int(_lib.kg_count(self._h, coll.encode(), prefix.encode()))
137
# ---------- text ----------
138
def index_coll(self, coll: str) -> None:
140
if _lib.kg_index_coll(self._h, coll.encode()) != 0:
141
raise RuntimeError(self.error())
143
def put_indexed(self, coll: str, key: str, text: str) -> None:
145
if _lib.kg_put_indexed(self._h, coll.encode(), key.encode(), text.encode()) != 0:
146
raise RuntimeError(self.error())
148
def search(self, coll: str, query: str, limit: int = 8) -> dict:
150
p = _lib.kg_search(self._h, coll.encode(), query.encode(), limit)
152
raise RuntimeError(self.error())
155
# ---------- misc ----------
156
def stats(self) -> dict:
158
p = _lib.kg_stats(self._h)
161
def set_sync(self, on: bool) -> bool:
163
return bool(_lib.kg_set_sync(self._h, 1 if on else 0))
165
def sync(self) -> None:
167
if _lib.kg_sync(self._h) != 0:
168
raise RuntimeError(self.error())
170
def compact(self) -> None:
172
if _lib.kg_compact(self._h) != 0:
173
raise RuntimeError(self.error())
175
def error(self) -> str:
176
return (_lib.kg_last_error(self._h) or b"error").decode()
178
def close(self) -> None:
181
_lib.kg_close(self._h)
187
def __exit__(self, *exc):