nyansqlite 1.0.0.dev1__py3-none-any.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.
nyansqlite/core.py ADDED
@@ -0,0 +1,502 @@
1
+ from __future__ import annotations
2
+
3
+ import threading
4
+ from typing import Any, Optional, TypeVar
5
+
6
+ from pydantic import BaseModel
7
+
8
+ from ._connection import NyanConnection
9
+ from ._schema import (
10
+ get_primary_key,
11
+ model_hints,
12
+ model_to_ddl,
13
+ model_to_fts5,
14
+ model_to_indexes,
15
+ model_to_table_name,
16
+ )
17
+ from ._types import deserialize_value, serialize_value
18
+ from .exceptions import (
19
+ FieldNotFoundError,
20
+ ModelNotRegisteredError,
21
+ SearchNotEnabledError,
22
+ )
23
+
24
+ M = TypeVar("M", bound=BaseModel)
25
+
26
+
27
+ # ── WHERE clause builder ──────────────────────────────────────────────── #
28
+
29
+ def _build_where(kwargs: dict[str, Any]) -> tuple[str, list[Any]]:
30
+ """Build a parameterised WHERE clause from keyword filter arguments.
31
+
32
+ Supported operator suffixes (double-underscore):
33
+
34
+ == ``field=value`` → ``field = ?``
35
+ == ``field__ne=value`` → ``field != ?``
36
+ == ``field__gt=value`` → ``field > ?``
37
+ == ``field__gte=value`` → ``field >= ?``
38
+ == ``field__lt=value`` → ``field < ?``
39
+ == ``field__lte=value`` → ``field <= ?``
40
+ == ``field__like=value`` → ``field LIKE ?``
41
+ == ``field__in=[…]`` → ``field IN (?,?,?)``
42
+ == ``field__is_null=True`` → ``field IS NULL``
43
+ == ``field__is_null=False`` → ``field IS NOT NULL``
44
+ """
45
+ if not kwargs:
46
+ return "", []
47
+
48
+ clauses: list[str] = []
49
+ values: list[Any] = []
50
+
51
+ for key, value in kwargs.items():
52
+ if "__" in key:
53
+ field, op = key.rsplit("__", 1)
54
+ q = f'"{field}"'
55
+ if op == "ne":
56
+ clauses.append(f"{q} != ?")
57
+ values.append(value)
58
+ elif op == "gt":
59
+ clauses.append(f"{q} > ?")
60
+ values.append(value)
61
+ elif op == "gte":
62
+ clauses.append(f"{q} >= ?")
63
+ values.append(value)
64
+ elif op == "lt":
65
+ clauses.append(f"{q} < ?")
66
+ values.append(value)
67
+ elif op == "lte":
68
+ clauses.append(f"{q} <= ?")
69
+ values.append(value)
70
+ elif op == "like":
71
+ clauses.append(f"{q} LIKE ?")
72
+ values.append(value)
73
+ elif op == "in":
74
+ ph = ", ".join("?" * len(value))
75
+ clauses.append(f"{q} IN ({ph})")
76
+ values.extend(value)
77
+ elif op == "is_null":
78
+ clauses.append(f"{q} IS {'NULL' if value else 'NOT NULL'}")
79
+ else:
80
+ raise ValueError(f"Unknown filter operator: __{op}")
81
+ elif value is None:
82
+ clauses.append(f'"{key}" IS NULL')
83
+ else:
84
+ clauses.append(f'"{key}" = ?')
85
+ values.append(value)
86
+
87
+ return "WHERE " + " AND ".join(clauses), values
88
+
89
+
90
+ def _order_sql(order_by: Optional[str], desc: bool) -> str:
91
+ if not order_by:
92
+ return ""
93
+ return f' ORDER BY "{order_by}" {"DESC" if desc else "ASC"}'
94
+
95
+
96
+ def _limit_sql(limit: Optional[int], offset: Optional[int]) -> str:
97
+ sql = ""
98
+ if limit is not None:
99
+ sql += f" LIMIT {int(limit)}"
100
+ if offset is not None:
101
+ sql += f" OFFSET {int(offset)}"
102
+ return sql
103
+
104
+
105
+ # ── internal model metadata ───────────────────────────────────────────── #
106
+
107
+ class _Meta:
108
+ __slots__ = ("table", "pk", "hints", "fts_table", "fts_fields")
109
+
110
+ def __init__(
111
+ self,
112
+ table: str,
113
+ pk: Optional[str],
114
+ hints: dict[str, Any],
115
+ fts_table: Optional[str],
116
+ fts_fields: list[str],
117
+ ):
118
+ self.table = table
119
+ self.pk = pk
120
+ self.hints = hints
121
+ self.fts_table = fts_table
122
+ self.fts_fields = fts_fields
123
+
124
+ def check_fields(self, fields: list[str], model_name: str) -> None:
125
+ bad = [f for f in fields if f not in self.hints]
126
+ if bad:
127
+ raise FieldNotFoundError(
128
+ f"Fields not found on {model_name}: {bad}. "
129
+ f"Available: {list(self.hints)}"
130
+ )
131
+
132
+
133
+ # ── main class ────────────────────────────────────────────────────────── #
134
+
135
+ class NyanSQLite:
136
+ """Pydantic-native SQLite wrapper.
137
+
138
+ Automatic schema creation, B-tree indexes, FTS5 full-text search,
139
+ partial reads/writes, and query operators — powered by apsw.
140
+
141
+ Quick start::
142
+
143
+ from nyansqlite import NyanSQLite, Indexed, Searchable
144
+ from pydantic import BaseModel
145
+
146
+ class Article(BaseModel):
147
+ id: int
148
+ author: Indexed[str]
149
+ title: Searchable[str]
150
+ body: Searchable[str]
151
+ views: int = 0
152
+
153
+ db = NyanSQLite("blog.sqlite")
154
+ db.register(Article)
155
+
156
+ db.insert(Article(id=1, author="neko", title="Hello SQLite", body="…"))
157
+ db.search(Article, "SQLite")
158
+ db.update(Article, where={"id": 1}, views=42)
159
+ db.select(Article, fields=["title", "views"], author="neko")
160
+ """
161
+
162
+ def __init__(self, path: str = ":memory:", wal: bool = True):
163
+ self._conn = NyanConnection(path, wal=wal)
164
+ self._registry: dict[type[BaseModel], _Meta] = {}
165
+ self._lock = threading.Lock()
166
+
167
+ # ── registration ─────────────────────────────────────────────────── #
168
+
169
+ def register(self, model: type[BaseModel]) -> None:
170
+ """Introspect *model* and create table + indexes + FTS5 virtual table."""
171
+ table = model_to_table_name(model)
172
+ pk = get_primary_key(model)
173
+ hints = model_hints(model)
174
+
175
+ with self._lock:
176
+ with self._conn.transaction():
177
+ self._conn.execute(model_to_ddl(model))
178
+ for idx_sql in model_to_indexes(model):
179
+ self._conn.execute(idx_sql)
180
+
181
+ fts_create, fts_triggers = model_to_fts5(model)
182
+ fts_table: str | None = None
183
+ fts_fields: list[str] = []
184
+ if fts_create:
185
+ self._conn.execute(fts_create)
186
+ for trig in fts_triggers:
187
+ self._conn.execute(trig)
188
+ from ._types import is_searchable
189
+ fts_table = f"{table}_fts"
190
+ fts_fields = [f for f, ann in hints.items() if is_searchable(ann)]
191
+
192
+ self._registry[model] = _Meta(
193
+ table=table, pk=pk, hints=hints,
194
+ fts_table=fts_table, fts_fields=fts_fields,
195
+ )
196
+
197
+ def _meta(self, model: type[BaseModel]) -> _Meta:
198
+ meta = self._registry.get(model)
199
+ if meta is None:
200
+ raise ModelNotRegisteredError(
201
+ f"{model.__name__} is not registered. "
202
+ f"Call db.register({model.__name__}) first."
203
+ )
204
+ return meta
205
+
206
+ # ── helpers ───────────────────────────────────────────────────────── #
207
+
208
+ def _to_row(self, obj: BaseModel, meta: _Meta) -> dict[str, Any]:
209
+ """Pydantic model → serialised dict for SQLite."""
210
+ dump = obj.model_dump() if hasattr(obj, "model_dump") else obj.dict()
211
+ return {k: serialize_value(v, meta.hints[k]) for k, v in dump.items() if k in meta.hints}
212
+
213
+ def _from_row(self, model: type[M], meta: _Meta, row: dict[str, Any]) -> M:
214
+ """SQLite row dict → Pydantic model."""
215
+ data = {k: deserialize_value(v, meta.hints[k]) for k, v in row.items() if k in meta.hints}
216
+ return model(**data)
217
+
218
+ # ── INSERT ───────────────────────────────────────────────────────── #
219
+
220
+ def insert(self, obj: M) -> M:
221
+ """Validate via Pydantic then INSERT. Returns the object unchanged."""
222
+ meta = self._meta(type(obj))
223
+ row = self._to_row(obj, meta)
224
+ cols = ", ".join(f'"{k}"' for k in row)
225
+ ph = ", ".join("?" * len(row))
226
+ sql = f'INSERT INTO "{meta.table}" ({cols}) VALUES ({ph})'
227
+ with self._lock:
228
+ with self._conn.transaction():
229
+ self._conn.execute(sql, tuple(row.values()))
230
+ return obj
231
+
232
+ def insert_many(self, objs: list[M]) -> int:
233
+ """Bulk-insert in a single transaction. Returns the number inserted."""
234
+ if not objs:
235
+ return 0
236
+ meta = self._meta(type(objs[0]))
237
+ rows = [self._to_row(o, meta) for o in objs]
238
+ cols = ", ".join(f'"{k}"' for k in rows[0])
239
+ ph = ", ".join("?" * len(rows[0]))
240
+ sql = f'INSERT INTO "{meta.table}" ({cols}) VALUES ({ph})'
241
+ with self._lock:
242
+ with self._conn.transaction():
243
+ self._conn.executemany(sql, [tuple(r.values()) for r in rows])
244
+ return len(objs)
245
+
246
+ # ── UPDATE ───────────────────────────────────────────────────────── #
247
+
248
+ def update(self, model: type[BaseModel], where: dict[str, Any], **fields: Any) -> int:
249
+ """Partial update — only the specified *fields* are written.
250
+
251
+ Args:
252
+ where: Exact-match conditions that identify the row(s).
253
+ **fields: ``field=new_value`` pairs to update.
254
+
255
+ Returns:
256
+ Number of rows updated.
257
+
258
+ Example::
259
+
260
+ db.update(User, where={"id": 1}, age=26, bio="updated")
261
+ """
262
+ if not fields:
263
+ return 0
264
+ meta = self._meta(model)
265
+ meta.check_fields(list(fields), model.__name__)
266
+
267
+ set_parts: list[str] = []
268
+ set_vals: list[Any] = []
269
+ for fname, value in fields.items():
270
+ set_parts.append(f'"{fname}" = ?')
271
+ set_vals.append(serialize_value(value, meta.hints[fname]))
272
+
273
+ where_clause, where_vals = _build_where(where)
274
+ sql = f'UPDATE "{meta.table}" SET {", ".join(set_parts)} {where_clause}'
275
+
276
+ with self._lock:
277
+ with self._conn.transaction():
278
+ self._conn.execute(sql, tuple(set_vals + where_vals))
279
+ return self._conn.changes()
280
+
281
+ # ── DELETE ───────────────────────────────────────────────────────── #
282
+
283
+ def delete(self, model: type[BaseModel], **kwargs: Any) -> int:
284
+ """Delete all rows matching *kwargs*. Returns rows deleted.
285
+
286
+ Example::
287
+
288
+ db.delete(User, id=42)
289
+ db.delete(Session, user_id=1, active=True)
290
+ """
291
+ meta = self._meta(model)
292
+ where_clause, values = _build_where(kwargs)
293
+ sql = f'DELETE FROM "{meta.table}" {where_clause}'
294
+ with self._lock:
295
+ with self._conn.transaction():
296
+ self._conn.execute(sql, tuple(values))
297
+ return self._conn.changes()
298
+
299
+ # ── GET / QUERY ───────────────────────────────────────────────────── #
300
+
301
+ def get(self, model: type[M], **kwargs: Any) -> Optional[M]:
302
+ """Fetch the first matching row as a Pydantic model, or ``None``.
303
+
304
+ Example::
305
+
306
+ user = db.get(User, id=1)
307
+ user = db.get(User, email="taro@example.com")
308
+ """
309
+ results = self.query(model, limit=1, **kwargs)
310
+ return results[0] if results else None
311
+
312
+ def query(
313
+ self,
314
+ model: type[M],
315
+ *,
316
+ limit: Optional[int] = None,
317
+ offset: Optional[int] = None,
318
+ order_by: Optional[str] = None,
319
+ desc: bool = False,
320
+ **kwargs: Any,
321
+ ) -> list[M]:
322
+ """Query rows with optional filtering, ordering, and pagination.
323
+
324
+ Supports all filter operators (``__gt``, ``__like``, ``__in``, …).
325
+
326
+ Examples::
327
+
328
+ db.query(User) # all rows
329
+ db.query(User, age=25) # exact match
330
+ db.query(User, age__gte=20, limit=10) # operators
331
+ db.query(User, order_by="name", desc=True) # ordering
332
+ db.query(User, order_by="id", limit=20, offset=40) # pagination
333
+ """
334
+ meta = self._meta(model)
335
+ where_clause, values = _build_where(kwargs)
336
+
337
+ if order_by:
338
+ meta.check_fields([order_by], model.__name__)
339
+
340
+ sql = (
341
+ f'SELECT * FROM "{meta.table}" {where_clause}'
342
+ + _order_sql(order_by, desc)
343
+ + _limit_sql(limit, offset)
344
+ )
345
+ rows = self._conn.execute(sql, tuple(values))
346
+ return [self._from_row(model, meta, r) for r in rows]
347
+
348
+ # ── SELECT (partial read) ─────────────────────────────────────────── #
349
+
350
+ def select(
351
+ self,
352
+ model: type[BaseModel],
353
+ fields: list[str],
354
+ *,
355
+ limit: Optional[int] = None,
356
+ offset: Optional[int] = None,
357
+ order_by: Optional[str] = None,
358
+ desc: bool = False,
359
+ **kwargs: Any,
360
+ ) -> list[dict[str, Any]]:
361
+ """Partial read — fetch only *fields*, returned as plain dicts.
362
+
363
+ Avoids loading unused columns for large rows.
364
+
365
+ Example::
366
+
367
+ db.select(Article, ["title", "views"], author="neko", order_by="views", desc=True)
368
+ """
369
+ meta = self._meta(model)
370
+ meta.check_fields(fields, model.__name__)
371
+ if order_by:
372
+ meta.check_fields([order_by], model.__name__)
373
+
374
+ col_sql = ", ".join(f'"{f}"' for f in fields)
375
+ where_clause, values = _build_where(kwargs)
376
+ sql = (
377
+ f'SELECT {col_sql} FROM "{meta.table}" {where_clause}'
378
+ + _order_sql(order_by, desc)
379
+ + _limit_sql(limit, offset)
380
+ )
381
+ rows = self._conn.execute(sql, tuple(values))
382
+ return [
383
+ {f: deserialize_value(row.get(f), meta.hints[f]) for f in fields}
384
+ for row in rows
385
+ ]
386
+
387
+ # ── FTS5 SEARCH ───────────────────────────────────────────────────── #
388
+
389
+ def search(
390
+ self,
391
+ model: type[M],
392
+ query: str,
393
+ *,
394
+ limit: Optional[int] = None,
395
+ ) -> list[M]:
396
+ """Full-text search on all ``Searchable[str]`` fields.
397
+
398
+ Uses FTS5 ``MATCH`` with BM25 ranking (``ORDER BY rank``).
399
+
400
+ Example::
401
+
402
+ db.search(Article, "python sqlite")
403
+ db.search(Article, "python sqlite", limit=5)
404
+
405
+ For field-scoped search, use FTS5 column filter syntax::
406
+
407
+ db.search(Article, "title:python")
408
+ """
409
+ meta = self._meta(model)
410
+ if not meta.fts_table:
411
+ raise SearchNotEnabledError(
412
+ f"{model.__name__} has no Searchable[str] fields. "
413
+ "Annotate at least one str field with Searchable[str] to enable FTS5."
414
+ )
415
+
416
+ table = meta.table
417
+ fts = meta.fts_table
418
+ sql = (
419
+ f'SELECT t.* FROM "{table}" t '
420
+ f'JOIN "{fts}" f ON t.rowid = f.rowid '
421
+ f'WHERE "{fts}" MATCH ? '
422
+ f'ORDER BY rank'
423
+ + _limit_sql(limit, None)
424
+ )
425
+ rows = self._conn.execute(sql, (query,))
426
+ return [self._from_row(model, meta, r) for r in rows]
427
+
428
+ # ── COUNT / EXISTS ────────────────────────────────────────────────── #
429
+
430
+ def count(self, model: type[BaseModel], **kwargs: Any) -> int:
431
+ """Return the number of rows matching *kwargs*.
432
+
433
+ Example::
434
+
435
+ total = db.count(User)
436
+ adults = db.count(User, age__gte=18)
437
+ """
438
+ meta = self._meta(model)
439
+ where_clause, values = _build_where(kwargs)
440
+ sql = f'SELECT COUNT(*) AS n FROM "{meta.table}" {where_clause}'
441
+ rows = self._conn.execute(sql, tuple(values))
442
+ return rows[0]["n"] if rows else 0
443
+
444
+ def exists(self, model: type[BaseModel], **kwargs: Any) -> bool:
445
+ """Return ``True`` if at least one row matches *kwargs*.
446
+
447
+ Example::
448
+
449
+ if db.exists(User, email="taro@example.com"):
450
+ ...
451
+ """
452
+ meta = self._meta(model)
453
+ where_clause, values = _build_where(kwargs)
454
+ sql = f'SELECT 1 FROM "{meta.table}" {where_clause} LIMIT 1'
455
+ return bool(self._conn.execute(sql, tuple(values)))
456
+
457
+ # ── MAINTENANCE ───────────────────────────────────────────────────── #
458
+
459
+ def rebuild_fts(self, model: type[BaseModel]) -> None:
460
+ """Rebuild the FTS5 index for *model* (useful after bulk imports)."""
461
+ meta = self._meta(model)
462
+ if not meta.fts_table:
463
+ return
464
+ self._conn.execute(
465
+ f'INSERT INTO "{meta.fts_table}"("{meta.fts_table}") VALUES(\'rebuild\')'
466
+ )
467
+
468
+ def vacuum(self) -> None:
469
+ """VACUUM the database to reclaim disk space."""
470
+ self._conn.execute("VACUUM")
471
+
472
+ # ── RAW SQL ───────────────────────────────────────────────────────── #
473
+
474
+ def execute_raw(self, sql: str, params: tuple = ()) -> list[dict[str, Any]]:
475
+ """Execute arbitrary SQL and return rows as dicts.
476
+
477
+ Example::
478
+
479
+ db.execute_raw("SELECT count(*) AS n FROM user WHERE age > ?", (18,))
480
+ """
481
+ return self._conn.execute(sql, params)
482
+
483
+ # ── context manager + info ────────────────────────────────────────── #
484
+
485
+ def __enter__(self) -> NyanSQLite:
486
+ return self
487
+
488
+ def __exit__(self, *_: Any) -> None:
489
+ self.close()
490
+
491
+ def close(self) -> None:
492
+ """Close the underlying database connection."""
493
+ self._conn.close()
494
+
495
+ @property
496
+ def backend(self) -> str:
497
+ """``'apsw'`` or ``'sqlite3'`` depending on what was found at import time."""
498
+ return self._conn.backend
499
+
500
+ def registered_models(self) -> list[str]:
501
+ """Names of all registered models."""
502
+ return [m.__name__ for m in self._registry]
@@ -0,0 +1,15 @@
1
+ class NyanSQLiteError(Exception):
2
+ """NyanSQLiteのベース例外クラス"""
3
+ pass
4
+
5
+ class FieldNotFoundError(NyanSQLiteError):
6
+ """モデルに存在しないフィールドが指定された場合にスローされます"""
7
+ pass
8
+
9
+ class ModelNotRegisteredError(NyanSQLiteError):
10
+ """db.register() されていないモデルを操作しようとした場合にスローされます"""
11
+ pass
12
+
13
+ class SearchNotEnabledError(NyanSQLiteError):
14
+ """Searchable[str] が定義されていないモデルで search() を実行した場合にスローされます"""
15
+ pass
nyansqlite/py.typed ADDED
File without changes