nyansqlite 1.0.0__tar.gz

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.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024 Disnana
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,383 @@
1
+ Metadata-Version: 2.4
2
+ Name: nyansqlite
3
+ Version: 1.0.0
4
+ Summary: A dict-like SQLite wrapper with APSW for instant persistence and memory caching
5
+ Author-email: Disnana <support@disnana.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/disnana/nyansqlite
8
+ Project-URL: Documentation, https://nyansqlite.disnana.com/
9
+ Project-URL: Repository, https://github.com/disnana/nyansqlite
10
+ Project-URL: Issues, https://github.com/disnana/nyansqlite/issues
11
+ Keywords: sqlite,apsw,dict,database,persistence,cache,key-value,nosql
12
+ Classifier: Development Status :: 5 - Production/Stable
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.9
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Programming Language :: Python :: 3.14
22
+ Classifier: Topic :: Database
23
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
24
+ Classifier: Typing :: Typed
25
+ Requires-Python: >=3.9
26
+ Description-Content-Type: text/markdown
27
+ License-File: LICENSE
28
+ Requires-Dist: apsw>=3.40.0.0
29
+ Requires-Dist: pydantic>2.0.0
30
+ Provides-Extra: speed
31
+ Requires-Dist: lru-dict>=1.3.0; extra == "speed"
32
+ Requires-Dist: orjson>=3.9.10; extra == "speed"
33
+ Requires-Dist: nanalib>=0.1.0; extra == "speed"
34
+ Provides-Extra: encryption
35
+ Requires-Dist: cryptography>=42.0.0; extra == "encryption"
36
+ Provides-Extra: validation
37
+ Requires-Dist: validkit-py>=1.0.0; extra == "validation"
38
+ Provides-Extra: re2
39
+ Requires-Dist: google-re2>=1.1; extra == "re2"
40
+ Provides-Extra: dev
41
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
42
+ Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
43
+ Requires-Dist: pytest-asyncio<2.0.0,>=0.21.0; extra == "dev"
44
+ Requires-Dist: pydantic>=2.0.0; extra == "dev"
45
+ Requires-Dist: tox>=4.0.0; extra == "dev"
46
+ Requires-Dist: ruff>=0.8.0; extra == "dev"
47
+ Requires-Dist: mypy>=1.13.0; extra == "dev"
48
+ Requires-Dist: pytest-xdist>=3.0.0; extra == "dev"
49
+ Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
50
+ Requires-Dist: cryptography>=42.0.0; extra == "dev"
51
+ Requires-Dist: validkit-py>=1.0.0; extra == "dev"
52
+ Requires-Dist: lru-dict>=1.3.0; extra == "dev"
53
+ Requires-Dist: orjson>=3.9.10; extra == "dev"
54
+ Requires-Dist: nanalib>=0.1.0; extra == "dev"
55
+ Requires-Dist: google-re2>=1.1; extra == "dev"
56
+ Requires-Dist: google-re2==1.1.20240702; python_version <= "3.9" and extra == "dev"
57
+ Provides-Extra: all
58
+ Requires-Dist: lru-dict>=1.3.0; extra == "all"
59
+ Requires-Dist: orjson>=3.9.10; extra == "all"
60
+ Requires-Dist: cryptography>=42.0.0; extra == "all"
61
+ Requires-Dist: validkit-py>=1.0.0; extra == "all"
62
+ Requires-Dist: pydantic>=2.0.0; extra == "all"
63
+ Requires-Dist: google-re2>=1.1; extra == "all"
64
+ Dynamic: license-file
65
+
66
+ # NyanSQLite
67
+
68
+ [![PyPI version](https://img.shields.io/pypi/v/nyansqlite.svg)](https://pypi.org/project/nyansqlite/)
69
+ [![Python versions](https://img.shields.io/pypi/pyversions/nyansqlite.svg)](https://pypi.org/project/nyansqlite/)
70
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
71
+ [![Downloads](https://static.pepy.tech/badge/nyansqlite)](https://pepy.tech/project/nyansqlite)
72
+ [![Tests](https://github.com/disnana/nyansqlite/actions/workflows/ci.yml/badge.svg)](https://github.com/disnana/nyansqlite/actions/workflows/ci.yml)
73
+
74
+ **Pythonic SQLite with Pydantic models, Django-like queries, and FTS5 full-text search.**
75
+
76
+ [English](#english) | [日本語](#日本語)
77
+
78
+ ---
79
+
80
+ ## 日本語
81
+
82
+ NyanSQLiteは、Pydanticモデルをそのままデータベーススキーマとして利用できる、型安全で高性能なSQLiteラッパーです。
83
+ 複雑なSQLを書くことなく、Pythonの型ヒントと直感的なクエリでデータを管理できます。
84
+
85
+ ### 🚀 主な特徴
86
+
87
+ | 機能 | 説明 |
88
+ |-----|------|
89
+ | **Pydanticベースのスキーマ** | 型ヒントで自動バリデーション、JSON変換も透過的 |
90
+ | **Djangoライクなクエリ** | `__gte`, `__in`, `__like` など直感的なフィルタリング |
91
+ | **FTS5全文検索** | テキストデータから高速に検索結果を取得 |
92
+ | **自動インデックス管理** | `Indexed[T]` アノテーションで B-tree インデックスを自動構築 |
93
+ | **複雑な型を透過的に処理** | dict や list を JSON で保存、自動で Python オブジェクトに戻す |
94
+ | **パフォーマンス最適化** | WAL モード、バッチ処理による高速化 |
95
+
96
+ ### 📦 インストール
97
+
98
+ ```bash
99
+ pip install nyansqlite
100
+ ```
101
+
102
+ Pydantic v2が必須です:
103
+
104
+ ```bash
105
+ pip install "pydantic>=2.0"
106
+ ```
107
+
108
+ ### ⚡ 5分クイックスタート
109
+
110
+ ```python
111
+ from pydantic import BaseModel
112
+ from nyansqlite import NyanSQLite, Indexed, Searchable
113
+
114
+ # 1️⃣ スキーマ定義(型ヒント+Pydantic)
115
+ class Article(BaseModel):
116
+ id: int # idフィールドが自動的に主キーになる
117
+ author: Indexed[str] # インデックス付きカラム
118
+ title: Searchable[str] # 全文検索対象
119
+ body: Searchable[str] # 全文検索対象
120
+ views: int = 0
121
+
122
+ # 2️⃣ DB初期化&テーブル作成
123
+ db = NyanSQLite("blog.db")
124
+ db.register(Article)
125
+
126
+ # 3️⃣ データ挿入
127
+ db.insert(Article(
128
+ id=1,
129
+ author="neko",
130
+ title="SQLiteを使いこなそう",
131
+ body="NyanSQLiteで簡単にデータ管理ができます。"
132
+ ))
133
+
134
+ # 4️⃣ クエリ実行(Django風)
135
+ articles = db.query(Article, author="neko", views__gte=0, order_by="id", desc=True)
136
+
137
+ # 5️⃣ 全文検索(FTS5)
138
+ results = db.search(Article, "SQLite")
139
+ for hit in results:
140
+ print(f"✨ {hit.title}")
141
+
142
+ db.close()
143
+ ```
144
+
145
+ ### 🔍 クエリ演算子リファレンス
146
+
147
+ ```python
148
+ # 完全一致
149
+ db.query(Article, author="neko")
150
+
151
+ # 演算子フィルタ
152
+ db.query(Article,
153
+ views__gt=10, # >
154
+ views__gte=10, # >=
155
+ views__lt=100, # <
156
+ views__lte=100, # <=
157
+ views__ne=50, # !=
158
+ )
159
+
160
+ # 文字列フィルタ
161
+ db.query(Article,
162
+ title__like="%Python%", # LIKE検索
163
+ )
164
+
165
+ # IN句
166
+ db.query(Article,
167
+ id__in=[1, 2, 3],
168
+ )
169
+
170
+ # NULL チェック
171
+ db.query(Article,
172
+ author__is_null=False,
173
+ )
174
+ ```
175
+
176
+ ### 🎯 実装例:ゲームのプレイヤーシステム
177
+
178
+ ```python
179
+ from datetime import datetime
180
+ from pydantic import BaseModel
181
+
182
+ class Player(BaseModel):
183
+ player_id: int # 主キー
184
+ username: Indexed[str] # ユーザー名でインデックス
185
+ level: Indexed[int] # レベルでインデックス
186
+ score: int = 0
187
+ created_at: datetime
188
+
189
+ db = NyanSQLite("game.db")
190
+ db.register(Player)
191
+
192
+ # バッチ登録(大量データが高速)
193
+ players = [
194
+ Player(player_id=i, username=f"player_{i}", level=i%50, created_at=datetime.now())
195
+ for i in range(1, 1001)
196
+ ]
197
+ db.insert_many(players)
198
+
199
+ # ランキング取得
200
+ top_players = db.query(Player, order_by="score", desc=True, limit=10)
201
+
202
+ # 条件付き検索&更新
203
+ high_level = db.query(Player, level__gte=40, limit=100)
204
+ mid_level = db.query(Player, "level > 10", "level < 40") # 文字列形式のフィルタ
205
+ db.update(Player, where={"player_id": 1}, score=9999)
206
+
207
+ # 数を数える
208
+ player_count = db.count(Player)
209
+ active_count = db.count(Player, level__gte=30)
210
+ pro_count = db.count(Player, "level > 40") # 文字列形式
211
+ ```
212
+
213
+ ### 📊 パフォーマンス
214
+
215
+ NyanSQLiteは以下の最適化を実装しています:
216
+
217
+ - **WAL モード**: 読み書き同時実行性の向上
218
+ - **トランザクション**: `insert_many()` はデフォルトでトランザクション内で実行
219
+ - **パラメータ化クエリ**: SQL インジェクション対策も兼ねた安全性
220
+
221
+ ```python
222
+ # 10万件をわずか0秒台で挿入(バッチ処理)
223
+ import time
224
+ players = [Player(player_id=i, ...) for i in range(100000)]
225
+ start = time.time()
226
+ db.insert_many(players)
227
+ print(f"Inserted in {time.time() - start:.4f}s") # 例: 0.3456s
228
+ ```
229
+
230
+ ### 🛠️ 高度な機能
231
+
232
+ #### 複合インデックス
233
+
234
+ ```python
235
+ from nyansqlite import CompositeIndex
236
+
237
+ class Order(BaseModel):
238
+ __nyan_indexes__ = [
239
+ CompositeIndex("user_id", "created_at"),
240
+ CompositeIndex("product_id", "status", unique=True),
241
+ ]
242
+ id: int
243
+ user_id: int
244
+ product_id: int
245
+ created_at: datetime
246
+ status: str
247
+ ```
248
+
249
+ #### 主キーのカスタマイズ
250
+
251
+ フィールド名が `id` でない場合:
252
+
253
+ ```python
254
+ class User(BaseModel):
255
+ __nyan_primary_key__ = "user_id"
256
+ user_id: int
257
+ email: str
258
+ name: str
259
+ ```
260
+
261
+ #### コンテキストマネージャー
262
+
263
+ ```python
264
+ with NyanSQLite("app.db") as db:
265
+ db.register(Article)
266
+ db.insert(Article(...))
267
+ # 自動的にcloseされる
268
+ ```
269
+
270
+ ### 🧹 メンテナンス
271
+
272
+ ```python
273
+ # インデックスの再構築
274
+ db.rebuild_fts(Article)
275
+
276
+ # データベース最適化(ファイルサイズを縮小)
277
+ db.vacuum()
278
+
279
+ # 存在確認
280
+ if db.exists(Article, id=1):
281
+ print("Found!")
282
+
283
+ # 部分取得(カラムを指定)
284
+ titles = db.select(Article, ["title", "author"], views__gte=100)
285
+ recent_titles = db.select(Article, ["title"], "views > 10", "id > 100")
286
+ ```
287
+
288
+ ### 🚨 型モデルのベストプラクティス
289
+
290
+ ```python
291
+ from pydantic import ConfigDict
292
+
293
+ class Article(BaseModel):
294
+ # Pydantic v2の設定
295
+ model_config = ConfigDict(
296
+ arbitrary_types_allowed=True, # 複雑な型をサポート
297
+ validate_assignment=True,
298
+ )
299
+
300
+ id: int
301
+ # ... その他フィールド
302
+ ```
303
+
304
+ ---
305
+
306
+ ## English
307
+
308
+ NyanSQLite is a type-safe, high-performance SQLite wrapper that transforms Pydantic models directly into database schemas. Write minimal SQL while leveraging the power of FTS5 full-text search and Django-inspired query syntax.
309
+
310
+ ### 🚀 Features
311
+
312
+ | Feature | Benefit |
313
+ |---------|---------|
314
+ | **Pydantic Integration** | Type-safe validation and automatic JSON serialization |
315
+ | **Django-like Queries** | `__gte`, `__in`, `__like` and more—no SQL needed |
316
+ | **FTS5 Search** | Lightning-fast full-text search on `Searchable[str]` fields |
317
+ | **Auto-Indexing** | Create B-tree indexes with `Indexed[T]` annotations |
318
+ | **Complex Types** | Transparent handling of dict, list, and custom types |
319
+ | **Performance Optimized** | WAL mode, batch inserts, parameterized queries |
320
+
321
+ ### 📦 Installation
322
+
323
+ ```bash
324
+ pip install nyansqlite
325
+ ```
326
+
327
+ Requires Python 3.9+ and Pydantic 2.0+.
328
+
329
+ ### ⚡ Quick Start
330
+
331
+ ```python
332
+ from pydantic import BaseModel
333
+ from nyansqlite import NyanSQLite, Indexed, Searchable
334
+
335
+ class Post(BaseModel):
336
+ id: int
337
+ title: Searchable[str]
338
+ author: Indexed[str]
339
+ views: int = 0
340
+
341
+ db = NyanSQLite(":memory:")
342
+ db.register(Post)
343
+
344
+ # Insert
345
+ db.insert(Post(id=1, title="Hello SQLite", author="neko"))
346
+
347
+ # Query
348
+ posts = db.query(Post, author="neko", views__gte=0)
349
+
350
+ # Full-text search
351
+ results = db.search(Post, "SQLite")
352
+
353
+ db.close()
354
+ ```
355
+
356
+ ### 📚 API Reference
357
+
358
+ **Core Methods:**
359
+
360
+ - `register(model)` – Introspect model and create table
361
+ - `insert(obj)` – Insert a single record
362
+ - `insert_many(objs)` – Bulk insert with transaction
363
+ - `query(**kwargs)` – SELECT with filters, ordering, pagination
364
+ - `search(query, limit)` – FTS5 full-text search
365
+ - `get(**kwargs)` – Fetch one record or None
366
+ - `update(where, **fields)` – Partial UPDATE
367
+ - `delete(**kwargs)` – Conditional DELETE
368
+ - `count(**kwargs)` – COUNT rows matching condition
369
+ - `exists(**kwargs)` – Check if any row matches
370
+ - `select(fields, **kwargs)` – Fetch specific columns as dicts
371
+ - `vacuum()` – Optimize database file
372
+ - `close()` – Close connection
373
+
374
+ ### 🔗 Resources
375
+
376
+ - **Repository**: [github.com/disnana/nyansqlite](https://github.com/disnana/nyansqlite)
377
+ - **Issues**: [Report bugs](https://github.com/disnana/nyansqlite/issues)
378
+
379
+ ---
380
+
381
+ ## License
382
+
383
+ MIT License – see [LICENSE](LICENSE) for details.