litecrate 0.1.0__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.
litecrate/__init__.py ADDED
@@ -0,0 +1,14 @@
1
+ from importlib.metadata import PackageNotFoundError, version
2
+
3
+ from .database.db_class import Database
4
+
5
+ try:
6
+ __version__ = version("litecrate")
7
+
8
+ except PackageNotFoundError:
9
+ __version__ = "dev"
10
+
11
+ __all__ = [
12
+ "Database",
13
+ "__version__",
14
+ ]
@@ -0,0 +1,5 @@
1
+ from .db_class import Database
2
+
3
+ __all__ = [
4
+ "Database",
5
+ ]
@@ -0,0 +1,835 @@
1
+ import json
2
+ import re
3
+ import sqlite3
4
+ from functools import lru_cache
5
+ from itertools import batched
6
+ from pathlib import Path
7
+ from types import TracebackType
8
+ from typing import Literal, Self
9
+ from urllib.parse import quote, unquote
10
+
11
+ from ..utils import (
12
+ check_column_name,
13
+ check_table_name,
14
+ get_index_identifier,
15
+ normalize_identifier,
16
+ normalize_identifiers,
17
+ parse_colum_into_sql,
18
+ sanitize_identifier,
19
+ sanitize_identifiers,
20
+ )
21
+
22
+
23
+ class Database:
24
+ _QUERY_TOKENS = re.compile(
25
+ r"(?P<comment>--[^\n]*|/\*.*?(?:\*/|\Z))"
26
+ r"|(?P<literal>[xX]?'(?:''|[^'])*(?:'|\Z))"
27
+ r'|(?P<quoted>"(?:""|[^"])*"|`(?:``|[^`])*`|\[[^\]]*\])'
28
+ r'|(?P<unfinished>["`\[].*\Z)'
29
+ r"|(?P<param>\?[0-9]*|[:@$][\w$\x80-\U0010ffff]+"
30
+ r"(?:::[\w$\x80-\U0010ffff]*)*(?:\([^\s)]*\))?)"
31
+ r"|(?P<number>0[xX][0-9a-fA-F_]+|(?:[0-9][0-9_]*(?:\.[0-9_]*)?"
32
+ r"|\.[0-9][0-9_]*)(?:[eE][+-]?[0-9][0-9_]*)?)"
33
+ r"|(?P<word>[A-Za-z_\x80-\U0010ffff][\w$\x80-\U0010ffff]*)"
34
+ r"|(?P<other>\S)",
35
+ re.DOTALL,
36
+ )
37
+ _SPECIAL_BIND = re.compile(r"\?[0-9]|[:@$]")
38
+ _SQL_WORDS = frozenset(
39
+ [
40
+ "AND",
41
+ "OR",
42
+ "NOT",
43
+ "IS",
44
+ "NULL",
45
+ "TRUE",
46
+ "FALSE",
47
+ "BETWEEN",
48
+ "IN",
49
+ "LIKE",
50
+ "GLOB",
51
+ "REGEXP",
52
+ "MATCH",
53
+ "ESCAPE",
54
+ "EXISTS",
55
+ "CASE",
56
+ "WHEN",
57
+ "THEN",
58
+ "ELSE",
59
+ "END",
60
+ "CAST",
61
+ "AS",
62
+ "COLLATE",
63
+ "DISTINCT",
64
+ "ALL",
65
+ "SELECT",
66
+ "FROM",
67
+ "WHERE",
68
+ "GROUP",
69
+ "BY",
70
+ "HAVING",
71
+ "ORDER",
72
+ "LIMIT",
73
+ "OFFSET",
74
+ "ASC",
75
+ "DESC",
76
+ "UNION",
77
+ "INTERSECT",
78
+ "EXCEPT",
79
+ "JOIN",
80
+ "ON",
81
+ "USING",
82
+ "LEFT",
83
+ "RIGHT",
84
+ "INNER",
85
+ "OUTER",
86
+ "CROSS",
87
+ "NATURAL",
88
+ "WITH",
89
+ "RECURSIVE",
90
+ "VALUES",
91
+ "NULLS",
92
+ "CURRENT_DATE",
93
+ "CURRENT_TIME",
94
+ "CURRENT_TIMESTAMP",
95
+ "ISNULL",
96
+ "NOTNULL",
97
+ "FILTER",
98
+ "OVER",
99
+ "PARTITION",
100
+ "ROWS",
101
+ "RANGE",
102
+ "UNBOUNDED",
103
+ "PRECEDING",
104
+ "FOLLOWING",
105
+ "EXCLUDE",
106
+ "TIES",
107
+ "OTHERS",
108
+ "GROUPS",
109
+ "ROWID",
110
+ "OID",
111
+ "_ROWID_",
112
+ "RETURNING",
113
+ "INDEXED",
114
+ "INDEX",
115
+ "IF",
116
+ ]
117
+ )
118
+
119
+ _CACHE_TYPES: dict[str, type | None] = {
120
+ "None": None,
121
+ "int": int,
122
+ "float": float,
123
+ "str": str,
124
+ "bool": bool,
125
+ "bytes": bytes,
126
+ "dict": dict,
127
+ "list": list,
128
+ }
129
+
130
+ def __init__(
131
+ self,
132
+ db_path: Path | str | Literal[":memory:"],
133
+ timeout: float = 30.0,
134
+ ) -> None:
135
+ self._conn = sqlite3.connect(
136
+ str(db_path),
137
+ timeout=timeout,
138
+ isolation_level=None,
139
+ autocommit=sqlite3.LEGACY_TRANSACTION_CONTROL, # pyright: ignore[reportArgumentType]
140
+ check_same_thread=False,
141
+ )
142
+
143
+ self._cache: dict[str, dict[str, type | None]] = {}
144
+ self._rollback_cache: dict[str, dict[str, type | None]] | None = None
145
+
146
+ try:
147
+ with self:
148
+ self._conn.execute(
149
+ "CREATE TABLE IF NOT EXISTS _litecrate_meta ("
150
+ "table_name TEXT PRIMARY KEY, "
151
+ "cache_colums TEXT NOT NULL"
152
+ ")"
153
+ )
154
+ self._load_cache()
155
+
156
+ except BaseException:
157
+ self._conn.close()
158
+ raise
159
+
160
+ # region helpers
161
+ def _load_cache(self) -> None:
162
+ self._cache.clear()
163
+
164
+ rows = self._conn.execute(
165
+ "SELECT table_name, cache_colums FROM _litecrate_meta"
166
+ )
167
+
168
+ for table_name, cache_colums in rows:
169
+ columns: dict[str, type | None] = {}
170
+
171
+ for entry in filter(None, cache_colums.split(",")):
172
+ try:
173
+ name, type_name = entry.rsplit(":", 1)
174
+ columns[unquote(name)] = self._CACHE_TYPES[type_name]
175
+
176
+ except (ValueError, KeyError) as exc:
177
+ raise ValueError(
178
+ f"Invalid cache metadata for table {table_name!r}"
179
+ ) from exc
180
+
181
+ self._cache[table_name] = columns
182
+
183
+ def _save_cache(self, table_name: str) -> None:
184
+ columns: list[str] = []
185
+
186
+ for name, column_type in self._cache[table_name].items():
187
+ type_name = "None" if column_type is None else column_type.__name__
188
+
189
+ if (
190
+ type_name not in self._CACHE_TYPES
191
+ or self._CACHE_TYPES[type_name] is not column_type
192
+ ):
193
+ raise TypeError(f"Unsupported cache type: {column_type!r}")
194
+
195
+ columns.append(f"{quote(name, safe='')}:{type_name}")
196
+
197
+ self._conn.execute(
198
+ "INSERT INTO _litecrate_meta "
199
+ "(table_name, cache_colums) "
200
+ "VALUES (?, ?) "
201
+ "ON CONFLICT(table_name) DO UPDATE SET "
202
+ "cache_colums = excluded.cache_colums",
203
+ (
204
+ table_name,
205
+ ",".join(columns),
206
+ ),
207
+ )
208
+
209
+ @staticmethod
210
+ def _dump_json(value: object) -> str:
211
+ return json.dumps(
212
+ value,
213
+ ensure_ascii=False,
214
+ allow_nan=False,
215
+ separators=(",", ":"),
216
+ )
217
+
218
+ @staticmethod
219
+ def _json_path(name: str) -> str:
220
+ label = json.dumps(name, ensure_ascii=False)[1:-1].replace(r"\"", r"\u0022")
221
+ return f'$."{label}"'
222
+
223
+ @staticmethod
224
+ def _local_subqueries(tokens: list[re.Match[str]]) -> set[int]:
225
+ groups: list[int] = []
226
+ local: set[int] = set()
227
+ for i, token in enumerate(tokens):
228
+ raw = token[0]
229
+ if raw == "(":
230
+ groups.append(i)
231
+
232
+ elif raw == ")" and groups:
233
+ groups.pop()
234
+
235
+ elif groups and raw.upper() in ("FROM", "WITH", "AS"):
236
+ if raw.upper() == "FROM" and tokens[i - 1][0].upper() == "DISTINCT":
237
+ continue
238
+
239
+ opening = groups[-1]
240
+ if tokens[opening + 1][0].upper() in ("SELECT", "WITH"):
241
+ local.add(opening)
242
+
243
+ return local
244
+
245
+ @classmethod
246
+ @lru_cache(maxsize=128)
247
+ def _query_parts(cls, query: str) -> tuple[tuple[int, int, str | int], ...]:
248
+ tokens = [
249
+ token
250
+ for token in cls._QUERY_TOKENS.finditer(query)
251
+ if token.lastgroup != "comment"
252
+ ]
253
+ parts: list[tuple[int, int, str | int]] = []
254
+ last_slot = 0
255
+ named_slots: dict[str, int] = {}
256
+ skip_depth = 0
257
+ upper_query = query.upper()
258
+ local: set[int] = set()
259
+ if "SELECT" in upper_query or "WITH" in upper_query:
260
+ local = cls._local_subqueries(tokens)
261
+
262
+ for i, token in enumerate(tokens):
263
+ raw = token[0]
264
+ kind = token.lastgroup
265
+
266
+ if kind == "unfinished":
267
+ return () # Let SQLite report the malformed expression.
268
+
269
+ if kind == "param":
270
+ if raw == "?":
271
+ last_slot += 1
272
+ continue
273
+
274
+ if raw[0] == "?":
275
+ slot = int(raw[1:])
276
+ last_slot = max(last_slot, slot)
277
+
278
+ else:
279
+ if raw not in named_slots:
280
+ last_slot += 1
281
+ named_slots[raw] = last_slot
282
+
283
+ slot = named_slots[raw]
284
+
285
+ parts.append((*token.span(), slot))
286
+ continue
287
+
288
+ # Leave local SQL names and multi-word CAST type names intact.
289
+ if skip_depth:
290
+ if raw == "(":
291
+ skip_depth += 1
292
+
293
+ elif raw == ")":
294
+ skip_depth -= 1
295
+
296
+ continue
297
+
298
+ if i in local:
299
+ skip_depth = 1
300
+ continue
301
+
302
+ if kind == "word" and raw.upper() == "AS":
303
+ skip_depth = 1
304
+ continue
305
+
306
+ if kind not in ("word", "quoted"):
307
+ continue
308
+
309
+ previous = tokens[i - 1][0].upper() if i else ""
310
+ following = tokens[i + 1][0] if i + 1 < len(tokens) else ""
311
+ if previous in (".", "COLLATE", "IN") or following in (".", "("):
312
+ continue
313
+
314
+ if kind == "word":
315
+ if raw.upper() in cls._SQL_WORDS or previous == "NULLS":
316
+ continue
317
+
318
+ name = raw
319
+
320
+ elif raw[0] == "[":
321
+ name = raw[1:-1]
322
+
323
+ else:
324
+ name = raw[1:-1].replace(raw[0] * 2, raw[0])
325
+
326
+ if name.isascii() and "\0" not in name:
327
+ parts.append((*token.span(), normalize_identifier(name)))
328
+
329
+ return tuple(parts)
330
+
331
+ def _expand_query(self, table_name: str, query: str, bind_offset: int = 0) -> str:
332
+ columns = self._cache.get(table_name)
333
+ if columns is not None and "_data" not in columns:
334
+ columns = None
335
+
336
+ if columns is None and not self._SPECIAL_BIND.search(query):
337
+ return query
338
+
339
+ result: list[str] = []
340
+ end = 0
341
+ for start, stop, part in self._query_parts(query):
342
+ if isinstance(part, int):
343
+ if part == 0 or (bind_offset == 0 and query[start] == "?"):
344
+ continue
345
+
346
+ replacement = f"?{part + bind_offset}"
347
+
348
+ elif columns is not None and part not in columns:
349
+ path = self._json_path(part).replace("'", "''")
350
+ replacement = f"""json_extract("_data", '{path}')"""
351
+
352
+ else:
353
+ continue
354
+
355
+ result.append(query[end:start])
356
+ result.append(replacement)
357
+ end = stop
358
+
359
+ if not result:
360
+ return query
361
+
362
+ result.append(query[end:])
363
+ return "".join(result)
364
+
365
+ def _prepare_values(
366
+ self,
367
+ table_name: str,
368
+ values: dict[str, object],
369
+ ) -> tuple[dict[str, object], dict[str, object]]:
370
+ columns = self._cache.get(table_name)
371
+
372
+ if columns is None:
373
+ raise ValueError(f"Table {table_name!r} is not registered in cache")
374
+
375
+ known: dict[str, object] = {}
376
+ extra: dict[str, object] = {}
377
+ flexible = "_data" in columns
378
+
379
+ for original_name, value in values.items():
380
+ name = normalize_identifier(original_name)
381
+ check_column_name(name)
382
+
383
+ if name in known or name in extra:
384
+ raise ValueError(f"Duplicate column: {name!r}")
385
+
386
+ if name in columns:
387
+ column_type = columns[name]
388
+
389
+ if (column_type is dict or column_type is list) and value is not None:
390
+ if not isinstance(value, column_type):
391
+ raise TypeError(
392
+ f"Column {name!r} requires {column_type.__name__}, "
393
+ f"got {type(value).__name__}"
394
+ )
395
+
396
+ value = self._dump_json(value)
397
+
398
+ known[name] = value
399
+
400
+ elif flexible:
401
+ extra[name] = value
402
+
403
+ else:
404
+ raise KeyError(f"Unknown column {name!r} in table {table_name!r}")
405
+
406
+ return known, extra
407
+
408
+ def _decode_row(
409
+ self,
410
+ table_name: str,
411
+ row: dict[str, object],
412
+ ) -> dict[str, object]:
413
+ columns = self._cache.get(table_name)
414
+ if columns is None:
415
+ return row
416
+
417
+ for name, column_type in columns.items():
418
+ if name == "_data" or name not in row or row[name] is None:
419
+ continue
420
+
421
+ if column_type is dict or column_type is list:
422
+ raw_value = row[name]
423
+ if not isinstance(raw_value, (str, bytes, bytearray)):
424
+ raise TypeError(f"Invalid stored JSON for column {name!r}")
425
+
426
+ parsed = json.loads(raw_value)
427
+ if not isinstance(parsed, column_type):
428
+ raise ValueError(
429
+ f"Invalid JSON type for column {name!r} in table {table_name!r}"
430
+ )
431
+
432
+ row[name] = parsed
433
+
434
+ elif column_type is bool:
435
+ row[name] = bool(row[name])
436
+
437
+ if "_data" in columns and "_data" in row:
438
+ raw = row.pop("_data")
439
+ if raw is not None:
440
+ if not isinstance(raw, (str, bytes, bytearray)):
441
+ raise TypeError(f"Invalid stored _data in table {table_name!r}")
442
+
443
+ extra = json.loads(raw)
444
+ if not isinstance(extra, dict):
445
+ raise ValueError(f"Invalid _data JSON in table {table_name!r}")
446
+
447
+ for name, value in extra.items():
448
+ if name not in row and name not in columns:
449
+ row[name] = value
450
+
451
+ return row
452
+
453
+ # endregion
454
+
455
+ # region table control
456
+ def create_table(
457
+ self,
458
+ table_name: str,
459
+ *colums: tuple[str | int, str, type | None] | tuple[str | int, str],
460
+ flexible: bool = False,
461
+ ) -> None:
462
+ table_name = normalize_identifier(table_name)
463
+ check_table_name(table_name)
464
+
465
+ colum_sqls: list[str] = []
466
+ index_sqls: list[str] = []
467
+
468
+ if (
469
+ self._conn.execute(
470
+ "SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = ? COLLATE NOCASE",
471
+ (table_name,),
472
+ ).fetchone()
473
+ is not None
474
+ ):
475
+ return
476
+
477
+ column_cache: dict[str, type | None] = {}
478
+
479
+ for colum in colums:
480
+ if len(colum) == 2:
481
+ flags, name = colum
482
+ colum_type = None
483
+
484
+ else:
485
+ flags, name, colum_type = colum
486
+
487
+ check_column_name(name)
488
+ storage_type = (
489
+ str if colum_type is dict or colum_type is list else colum_type
490
+ )
491
+ colum_sql, index_sql = parse_colum_into_sql(
492
+ table_name, flags, name, storage_type
493
+ )
494
+
495
+ colum_sqls.append(colum_sql)
496
+ if index_sql:
497
+ index_sqls.append(index_sql)
498
+
499
+ column_cache[normalize_identifier(name)] = colum_type
500
+
501
+ if flexible:
502
+ colum_sql, _ = parse_colum_into_sql(table_name, 0, "_data", str)
503
+ colum_sqls.append(colum_sql)
504
+ column_cache["_data"] = str
505
+
506
+ self._conn.execute(
507
+ f"CREATE TABLE {sanitize_identifier(table_name)} ({', '.join(colum_sqls)})"
508
+ )
509
+
510
+ for sql in index_sqls:
511
+ self._conn.execute(sql)
512
+
513
+ self._cache[table_name] = column_cache
514
+ self._save_cache(table_name)
515
+
516
+ def rename_table(self, target: str, value: str) -> None:
517
+ target, value = normalize_identifiers(target, value)
518
+ check_table_name(target, value)
519
+ san_target, san_value = sanitize_identifiers(target, value)
520
+
521
+ indexed_columns = []
522
+
523
+ for index_name in self.get_table_indexes(target):
524
+ info = self._conn.execute(
525
+ f"PRAGMA index_info({sanitize_identifier(index_name)})"
526
+ ).fetchall()
527
+
528
+ if len(info) != 1:
529
+ continue
530
+
531
+ column_name = info[0][2]
532
+ if column_name is None or not column_name.isascii():
533
+ continue
534
+
535
+ column_name = normalize_identifier(column_name)
536
+ if index_name == get_index_identifier(target, column_name):
537
+ indexed_columns.append(column_name)
538
+
539
+ self._conn.execute(f"ALTER TABLE {san_target} RENAME TO {san_value}")
540
+
541
+ for column_name in indexed_columns:
542
+ old_index = get_index_identifier(target, column_name)
543
+ new_index = get_index_identifier(value, column_name)
544
+ san_column = sanitize_identifier(column_name)
545
+
546
+ self._conn.execute(f"DROP INDEX {old_index}")
547
+ self._conn.execute(
548
+ f"CREATE INDEX {new_index} ON {san_value} ({san_column})"
549
+ )
550
+
551
+ if target in self._cache:
552
+ self._cache[value] = self._cache.pop(target)
553
+
554
+ self._conn.execute(
555
+ "UPDATE _litecrate_meta SET table_name = ? WHERE table_name = ?",
556
+ (value, target),
557
+ )
558
+
559
+ def get_tables(self, include_internal: bool = False) -> list[str]:
560
+ query = "SELECT name FROM sqlite_schema WHERE type = 'table'"
561
+
562
+ if not include_internal:
563
+ query += " AND name NOT GLOB 'sqlite_*' AND name != '_litecrate_meta'"
564
+
565
+ query += " ORDER BY name"
566
+
567
+ return [row[0] for row in self._conn.execute(query)]
568
+
569
+ def delete_table(
570
+ self,
571
+ target: str,
572
+ ) -> None:
573
+ target = normalize_identifier(target)
574
+ check_table_name(target)
575
+ self._conn.execute(f"DROP TABLE IF EXISTS {sanitize_identifier(target)}")
576
+ self._cache.pop(target, None)
577
+ self._conn.execute(
578
+ "DELETE FROM _litecrate_meta WHERE table_name = ?", (target,)
579
+ )
580
+
581
+ # endregion
582
+
583
+ # region crud
584
+ def insert(
585
+ self,
586
+ table_name: str,
587
+ **values: object,
588
+ ) -> int | None:
589
+ table_name = normalize_identifier(table_name)
590
+ check_table_name(table_name)
591
+ san_table = sanitize_identifier(table_name)
592
+
593
+ known, extra = self._prepare_values(table_name, values)
594
+
595
+ if extra:
596
+ known["_data"] = self._dump_json(extra)
597
+
598
+ if not known:
599
+ cursor = self._conn.execute(f"INSERT INTO {san_table} DEFAULT VALUES")
600
+ return cursor.lastrowid
601
+
602
+ columns = ", ".join(sanitize_identifier(name) for name in known)
603
+ placeholders = ", ".join("?" for _ in known)
604
+
605
+ cursor = self._conn.execute(
606
+ f"INSERT INTO {san_table} ({columns}) VALUES ({placeholders})",
607
+ tuple(known.values()),
608
+ )
609
+ return cursor.lastrowid
610
+
611
+ def update(
612
+ self,
613
+ table_name: str,
614
+ query: str,
615
+ *args: object,
616
+ **values: object,
617
+ ) -> int:
618
+ table_name = normalize_identifier(table_name)
619
+ check_table_name(table_name)
620
+ san_table = sanitize_identifier(table_name)
621
+
622
+ if not query.strip():
623
+ raise ValueError("UPDATE requires a WHERE condition")
624
+
625
+ if not values:
626
+ raise ValueError("UPDATE requires at least one value")
627
+
628
+ known, extra = self._prepare_values(table_name, values)
629
+ assignments: list[str] = []
630
+ params: list[object] = []
631
+
632
+ for name, value in known.items():
633
+ assignments.append(f"{sanitize_identifier(name)} = ?")
634
+ params.append(value)
635
+
636
+ if extra:
637
+ data_sql = """COALESCE("_data", '{}')"""
638
+ # json_set takes one document and two arguments per key.
639
+ limit = self._conn.getlimit(sqlite3.SQLITE_LIMIT_FUNCTION_ARG)
640
+ for batch in batched(extra.items(), max(1, (limit - 1) // 2)):
641
+ json_args = ", ".join(["?, json(?)"] * len(batch))
642
+ data_sql = f"json_set({data_sql}, {json_args})"
643
+ for name, value in batch:
644
+ params.extend((self._json_path(name), self._dump_json(value)))
645
+
646
+ assignments.append(f'"_data" = {data_sql}')
647
+
648
+ condition = self._expand_query(table_name, query, bind_offset=len(params))
649
+ cursor = self._conn.execute(
650
+ f"UPDATE {san_table} SET {', '.join(assignments)} WHERE {condition}",
651
+ (*params, *args),
652
+ )
653
+ return cursor.rowcount
654
+
655
+ def delete(
656
+ self,
657
+ table_name: str,
658
+ query: str,
659
+ *args: object,
660
+ ) -> int:
661
+ table_name = normalize_identifier(table_name)
662
+ check_table_name(table_name)
663
+ san_table = sanitize_identifier(table_name)
664
+
665
+ if not query.strip():
666
+ raise ValueError("DELETE requires a WHERE condition")
667
+
668
+ cursor = self._conn.execute(
669
+ f"DELETE FROM {san_table} WHERE {self._expand_query(table_name, query)}",
670
+ args,
671
+ )
672
+ return cursor.rowcount
673
+
674
+ def select(
675
+ self,
676
+ table_name: str,
677
+ query: str = "",
678
+ *args: object,
679
+ ) -> list[dict[str, object]]:
680
+ table_name = normalize_identifier(table_name)
681
+ check_table_name(table_name)
682
+ san_table = sanitize_identifier(table_name)
683
+
684
+ sql = f"SELECT * FROM {san_table}"
685
+ if query.strip():
686
+ sql += f" WHERE {self._expand_query(table_name, query)}"
687
+
688
+ cursor = self._conn.execute(sql, args)
689
+ columns = [column[0] for column in cursor.description]
690
+ return [self._decode_row(table_name, dict(zip(columns, row))) for row in cursor]
691
+
692
+ def select_one(
693
+ self,
694
+ table_name: str,
695
+ query: str = "",
696
+ *args: object,
697
+ ) -> dict[str, object] | None:
698
+ table_name = normalize_identifier(table_name)
699
+ check_table_name(table_name)
700
+ san_table = sanitize_identifier(table_name)
701
+
702
+ sql = f"SELECT * FROM {san_table}"
703
+ if query.strip():
704
+ sql += f" WHERE {self._expand_query(table_name, query)}"
705
+
706
+ cursor = self._conn.execute(sql + "\nLIMIT 1", args)
707
+ row = cursor.fetchone()
708
+ if row is None:
709
+ return None
710
+
711
+ columns = [column[0] for column in cursor.description]
712
+ return self._decode_row(table_name, dict(zip(columns, row)))
713
+
714
+ def count(
715
+ self,
716
+ table_name: str,
717
+ query: str = "",
718
+ *args: object,
719
+ ) -> int:
720
+ table_name = normalize_identifier(table_name)
721
+ check_table_name(table_name)
722
+ san_table = sanitize_identifier(table_name)
723
+
724
+ sql = f"SELECT COUNT(*) FROM {san_table}"
725
+ if query.strip():
726
+ sql += f" WHERE {self._expand_query(table_name, query)}"
727
+
728
+ return self._conn.execute(sql, args).fetchone()[0]
729
+
730
+ # endregion
731
+
732
+ # region index control
733
+ def get_table_indexes(self, table_name: str) -> list[str]:
734
+ table_name = normalize_identifier(table_name)
735
+ return [
736
+ row[0]
737
+ for row in self._conn.execute(
738
+ "SELECT name FROM sqlite_schema "
739
+ "WHERE type = 'index' AND tbl_name = ? COLLATE NOCASE "
740
+ "AND name NOT GLOB 'sqlite_autoindex_*' "
741
+ "ORDER BY name",
742
+ (table_name,),
743
+ )
744
+ ]
745
+
746
+ def create_index(self, table_name: str, column_name: str) -> None:
747
+ table_name, column_name = normalize_identifiers(table_name, column_name)
748
+ san_table, san_column = sanitize_identifiers(table_name, column_name)
749
+ # SQLite builds can interpret a double-quoted missing column as text
750
+ # and silently create an index on a constant expression.
751
+ if not any(
752
+ row[1].lower() == column_name
753
+ for row in self._conn.execute(f"PRAGMA table_xinfo({san_table})")
754
+ ):
755
+ raise sqlite3.OperationalError(
756
+ f"No such column {column_name!r} in table {table_name!r}"
757
+ )
758
+
759
+ self._conn.execute(
760
+ f"CREATE INDEX {get_index_identifier(table_name, column_name)} ON {san_table} ({san_column})"
761
+ )
762
+
763
+ def remove_index(self, table_name: str, column_name: str) -> None:
764
+ table_name, column_name = normalize_identifiers(table_name, column_name)
765
+ self._conn.execute(
766
+ f"DROP INDEX IF EXISTS {get_index_identifier(table_name, column_name)}"
767
+ )
768
+
769
+ # endregion
770
+
771
+ # region PRAGMA
772
+ def set_auto_vacuum(
773
+ self,
774
+ value: Literal["NONE", "FULL", "INCREMENTAL"],
775
+ ) -> None:
776
+ if value not in ("NONE", "FULL", "INCREMENTAL"):
777
+ raise ValueError(f"Invalid auto_vacuum value: {value!r}")
778
+
779
+ self._conn.execute(f"PRAGMA auto_vacuum={value}")
780
+
781
+ def set_journal_mode(
782
+ self,
783
+ value: Literal["DELETE", "TRUNCATE", "PERSIST", "MEMORY", "WAL", "OFF"],
784
+ ) -> None:
785
+ if value not in ("DELETE", "TRUNCATE", "PERSIST", "MEMORY", "WAL", "OFF"):
786
+ raise ValueError(f"Invalid journal_mode value: {value!r}")
787
+
788
+ result = self._conn.execute(f"PRAGMA journal_mode={value}").fetchone()[0]
789
+
790
+ if result.upper() != value:
791
+ raise RuntimeError(
792
+ f"Failed to set journal mode to {value!r}, got {result!r}"
793
+ )
794
+
795
+ # endregion
796
+
797
+ def vacuum(self) -> None:
798
+ self._conn.execute("VACUUM")
799
+
800
+ def close(self) -> None:
801
+ self._conn.close()
802
+
803
+ # region context funcs
804
+ def __enter__(self) -> Self:
805
+ if self._rollback_cache is not None:
806
+ raise RuntimeError("Nested transactions are not supported")
807
+
808
+ snapshot = self._cache.copy()
809
+ self._conn.execute("BEGIN")
810
+ self._rollback_cache = snapshot
811
+ return self
812
+
813
+ def __exit__(
814
+ self,
815
+ exc_type: type[BaseException] | None,
816
+ exc: BaseException | None,
817
+ tb: TracebackType | None,
818
+ ) -> None:
819
+ snapshot = self._rollback_cache
820
+ if snapshot is None:
821
+ raise RuntimeError("No active transaction")
822
+
823
+ committed = False
824
+ try:
825
+ if exc_type is None:
826
+ self._conn.execute("COMMIT")
827
+ committed = True
828
+
829
+ finally:
830
+ self._rollback_cache = None
831
+ if not committed:
832
+ self._cache = snapshot
833
+ self._conn.rollback()
834
+
835
+ # endregion
@@ -0,0 +1,22 @@
1
+ from .colum_work import ColumBitEnum, parse_colum_into_sql
2
+ from .identifier import (
3
+ check_column_name,
4
+ check_table_name,
5
+ get_index_identifier,
6
+ normalize_identifier,
7
+ normalize_identifiers,
8
+ sanitize_identifier,
9
+ sanitize_identifiers,
10
+ )
11
+
12
+ __all__ = [
13
+ "ColumBitEnum",
14
+ "check_column_name",
15
+ "check_table_name",
16
+ "get_index_identifier",
17
+ "normalize_identifier",
18
+ "normalize_identifiers",
19
+ "parse_colum_into_sql",
20
+ "sanitize_identifier",
21
+ "sanitize_identifiers",
22
+ ]
@@ -0,0 +1,116 @@
1
+ from enum import IntFlag
2
+
3
+ from .identifier import (
4
+ get_index_identifier,
5
+ normalize_identifiers,
6
+ sanitize_identifiers,
7
+ )
8
+
9
+
10
+ class ColumBitEnum(IntFlag):
11
+ INDEX = 1 << 0
12
+ NOT_NULL = 1 << 1
13
+ PRIMARY = 1 << 2
14
+ UNIQUE = 1 << 3
15
+
16
+ @staticmethod
17
+ def all_flags() -> int:
18
+ return sum(flag.value for flag in ColumBitEnum)
19
+
20
+
21
+ _SQL_TYPES = {
22
+ int: "INTEGER",
23
+ bool: "INTEGER",
24
+ float: "REAL",
25
+ str: "TEXT",
26
+ bytes: "BLOB",
27
+ None: "",
28
+ }
29
+
30
+
31
+ def _get_colum_type(colum_type: type | None) -> str:
32
+ if colum_type not in _SQL_TYPES:
33
+ raise TypeError(f"Unsupported column type: {colum_type!r}")
34
+
35
+ return _SQL_TYPES[colum_type]
36
+
37
+
38
+ def _sanitize_flags(flags: str | int) -> int:
39
+ match flags:
40
+ case int():
41
+ bit_mask = flags
42
+
43
+ case str():
44
+ bit_mask = 0
45
+ for char in flags.lower():
46
+ if char == "p":
47
+ bit_mask |= ColumBitEnum.PRIMARY
48
+ continue
49
+
50
+ elif char == "i":
51
+ bit_mask |= ColumBitEnum.INDEX
52
+ continue
53
+
54
+ elif char == "n":
55
+ bit_mask |= ColumBitEnum.NOT_NULL
56
+ continue
57
+
58
+ elif char == "u":
59
+ bit_mask |= ColumBitEnum.UNIQUE
60
+ continue
61
+
62
+ else:
63
+ raise ValueError(f"Unknown column flag {char!r} in {flags!r}")
64
+
65
+ case _:
66
+ raise TypeError(f"Flags must be str or int, got {type(flags).__name__}")
67
+
68
+ if bit_mask & ~ColumBitEnum.all_flags():
69
+ raise ValueError(f"Invalid column flag mask: {flags!r}")
70
+
71
+ if bit_mask & ColumBitEnum.PRIMARY:
72
+ bit_mask &= ~(ColumBitEnum.INDEX | ColumBitEnum.UNIQUE)
73
+
74
+ elif bit_mask & ColumBitEnum.UNIQUE:
75
+ bit_mask &= ~ColumBitEnum.INDEX
76
+
77
+ return bit_mask
78
+
79
+
80
+ def parse_colum_into_sql(
81
+ table_name: str,
82
+ flags: str | int,
83
+ colum_name: str,
84
+ colum_type: type | None = None,
85
+ ) -> tuple[str, str | None]:
86
+ table_name, colum_name = normalize_identifiers(table_name, colum_name)
87
+ san_table_name, san_colum_name = sanitize_identifiers(table_name, colum_name)
88
+
89
+ flags = _sanitize_flags(flags)
90
+ type_sql = _get_colum_type(colum_type)
91
+
92
+ # region index sql create
93
+ index_sql = None
94
+ if flags & ColumBitEnum.INDEX:
95
+ index_sql = f"CREATE INDEX {get_index_identifier(table_name, colum_name)} ON {san_table_name} ({san_colum_name})"
96
+ # endregion
97
+
98
+ # region colum_sql_create
99
+ colum_sql = f"{san_colum_name} {type_sql}".rstrip()
100
+ if flags & ColumBitEnum.PRIMARY:
101
+ colum_sql += " PRIMARY KEY"
102
+
103
+ if flags & ColumBitEnum.NOT_NULL:
104
+ colum_sql += " NOT NULL"
105
+
106
+ if flags & ColumBitEnum.UNIQUE:
107
+ colum_sql += " UNIQUE"
108
+ # endregion
109
+
110
+ return colum_sql, index_sql
111
+
112
+
113
+ __all__ = [
114
+ "ColumBitEnum",
115
+ "parse_colum_into_sql",
116
+ ]
@@ -0,0 +1,69 @@
1
+ from hashlib import blake2s
2
+
3
+
4
+ # region normalize
5
+ def normalize_identifier(identifier: str) -> str:
6
+ if not identifier.isascii() or "\0" in identifier:
7
+ raise ValueError(f"Invalid SQL {identifier=}")
8
+
9
+ return identifier.lower()
10
+
11
+
12
+ def normalize_identifiers(*identifiers: str) -> tuple[str, ...]:
13
+ result = []
14
+
15
+ for identifier in identifiers:
16
+ if not identifier.isascii() or "\0" in identifier:
17
+ raise ValueError(f"Invalid SQL {identifier=}")
18
+
19
+ result.append(identifier.lower())
20
+
21
+ return tuple(result)
22
+
23
+
24
+ # endregion
25
+
26
+
27
+ # region sanitize
28
+ def sanitize_identifier(identifier: str) -> str:
29
+ return '"' + identifier.replace('"', '""') + '"'
30
+
31
+
32
+ def sanitize_identifiers(*identifiers: str) -> tuple[str, ...]:
33
+ return tuple(
34
+ '"' + identifier.replace('"', '""') + '"' for identifier in identifiers
35
+ )
36
+
37
+
38
+ # endregion
39
+
40
+
41
+ # region check
42
+ def check_table_name(*names: str) -> None:
43
+ for name in names:
44
+ if name.lower() == "_litecrate_meta":
45
+ raise ValueError("Table name '_litecrate_meta' is reserved")
46
+
47
+
48
+ def check_column_name(*names: str) -> None:
49
+ for name in names:
50
+ if name.lower() == "_data":
51
+ raise ValueError("Column name '_data' is reserved")
52
+
53
+
54
+ # endregion
55
+
56
+
57
+ def get_index_identifier(table: str, colum: str) -> str:
58
+ return f"idx_{blake2s(f'{table}\0{colum}'.encode(), digest_size=16).hexdigest()}"
59
+
60
+
61
+ __all__ = [
62
+ "check_column_name",
63
+ "check_table_name",
64
+ "get_index_identifier",
65
+ "normalize_identifier",
66
+ "normalize_identifiers",
67
+ "sanitize_identifier",
68
+ "sanitize_identifiers",
69
+ ]
@@ -0,0 +1,14 @@
1
+ Metadata-Version: 2.4
2
+ Name: litecrate
3
+ Version: 0.1.0
4
+ Summary: A lightweight SQLite wrapper with flexible JSON storage
5
+ Requires-Python: >=3.13
6
+ Description-Content-Type: text/markdown
7
+ Provides-Extra: dev
8
+ Requires-Dist: pytest>=8.0; extra == "dev"
9
+ Requires-Dist: build; extra == "dev"
10
+ Requires-Dist: twine; extra == "dev"
11
+
12
+ # LiteCrate
13
+
14
+ [docs page](https://themanyfaceddemon.github.io/LiteCrate/)
@@ -0,0 +1,10 @@
1
+ litecrate/__init__.py,sha256=X-F96YuBMnaQXQZrLOswWB7K_VAH77Y3riyOIO-hxQg,251
2
+ litecrate/database/__init__.py,sha256=IdGz42Hu-1bYuj2J1JEuwcOcxZp5GBj6GwNVMKWO4vU,62
3
+ litecrate/database/db_class.py,sha256=-C98LK84_Fr5tvTcR7XJlm3a14-iEzYVOIeLhVhwAQw,25835
4
+ litecrate/utils/__init__.py,sha256=4bsckJahEkv1fLefT50_PfNa52ErAfQvndq8ItlhIfc,514
5
+ litecrate/utils/colum_work.py,sha256=SMBlwlJm3szMX7CIDiKBI6aYrY9XfjspNx7RIAQ2bm0,2893
6
+ litecrate/utils/identifier.py,sha256=DgR0BVufmfCcogbYbWZRy7-grTkDwNCwccvbwJ4Nv68,1601
7
+ litecrate-0.1.0.dist-info/METADATA,sha256=TQY-9aabPUQcogxHt_qhVdPo-slv-m3AKY9vinNpcfg,393
8
+ litecrate-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
9
+ litecrate-0.1.0.dist-info/top_level.txt,sha256=p5UKyiFn2pfvSsjqarXFQ-ES8OgwJSICeY_FDmp_umM,10
10
+ litecrate-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1 @@
1
+ litecrate