sdpy-kit 0.2.3__tar.gz → 0.2.5__tar.gz

sdpy_kit-0.2.3/README.md → sdpy_kit-0.2.5/PKG-INFO

@@ -1,3 +1,73 @@
+Metadata-Version: 2.5
+Name: sdpy-kit
+Version: 0.2.5
+Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/MCP/Redis/文件/文档/向量工具集
+Author-email: Clark <changhongyuan@126.com>
+License-Expression: MIT
+Keywords: ai,kit,mcp,mysql,postgresql,redis,sdpy,sqlalchemy,sqlite,sqlmodel,向量检索,工具集,开发工具,数据库
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: Chinese (Simplified)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.13
+Requires-Dist: pydantic-settings>=2.15.0
+Requires-Dist: pydantic>=2.14.1
+Requires-Dist: sqlalchemy~=2.0.54
+Requires-Dist: sqlmodel>=0.0.48
+Provides-Extra: ai
+Requires-Dist: httpx>=0.28.1; extra == 'ai'
+Requires-Dist: python-dotenv>=1.2.4; extra == 'ai'
+Provides-Extra: all
+Requires-Dist: docxtpl>=0.20.2; extra == 'all'
+Requires-Dist: fastmcp>=4.1.0; extra == 'all'
+Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'all'
+Requires-Dist: httpx>=0.28.1; extra == 'all'
+Requires-Dist: markdown-it-py>=4.2.0; extra == 'all'
+Requires-Dist: marker-pdf[full]>=2.0.0; extra == 'all'
+Requires-Dist: numpy>=2.5.4; extra == 'all'
+Requires-Dist: pikepdf>=10.17.0; extra == 'all'
+Requires-Dist: pimd[pdfa]>=2.2.5; extra == 'all'
+Requires-Dist: psycopg2-binary>=2.9.13; extra == 'all'
+Requires-Dist: pymysql>=1.2.3; extra == 'all'
+Requires-Dist: python-dotenv>=1.2.4; extra == 'all'
+Requires-Dist: redis>=8.1.0; extra == 'all'
+Requires-Dist: requests>=2.34.2; extra == 'all'
+Requires-Dist: sqliteai-vector>=1.1.2; extra == 'all'
+Requires-Dist: zvec>=0.7.0; extra == 'all'
+Provides-Extra: anydoc
+Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'anydoc'
+Requires-Dist: pikepdf>=10.17.0; extra == 'anydoc'
+Provides-Extra: docx
+Requires-Dist: docxtpl>=0.20.2; extra == 'docx'
+Provides-Extra: marker
+Requires-Dist: marker-pdf[full]>=2.0.0; extra == 'marker'
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=4.1.0; extra == 'mcp'
+Provides-Extra: md2doc
+Requires-Dist: markdown-it-py>=4.2.0; extra == 'md2doc'
+Requires-Dist: pimd[pdfa]>=2.2.5; extra == 'md2doc'
+Provides-Extra: mineru
+Requires-Dist: requests>=2.34.2; extra == 'mineru'
+Provides-Extra: mysql
+Requires-Dist: pymysql>=1.2.3; extra == 'mysql'
+Provides-Extra: pg
+Requires-Dist: psycopg2-binary>=2.9.13; extra == 'pg'
+Provides-Extra: redis
+Requires-Dist: redis>=8.1.0; extra == 'redis'
+Provides-Extra: sqliteai
+Requires-Dist: numpy>=2.5.4; extra == 'sqliteai'
+Requires-Dist: sqliteai-vector>=1.1.2; extra == 'sqliteai'
+Provides-Extra: zvec
+Requires-Dist: zvec>=0.7.0; extra == 'zvec'
+Description-Content-Type: text/markdown
+
 # sdpy-kit
 
 SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
@@ -266,7 +336,7 @@ from kit.db import session_scope, transactional, DBError    # 推荐
 from kit import session_scope, transactional, DBError       # 等价
 ```
 
-### 1. 三个数据库 Kit（23 个共享方法 API 完全一致）
+### 1. 三个数据库 Kit（24 个共享方法 API 完全一致）
 
 | 类 | 导入 | 数据库 | extra |
 |----|------|--------|-------|
@@ -292,7 +362,8 @@ from kit import session_scope, transactional, DBError       # 等价
 | ORM | `upsert(model, data, conflict_fields) -> Model` | 原子插入或更新（`conflict_fields` 须为唯一约束） |
 | ORM | `count(model) -> int` | 记录总数 |
 | 原生 SQL | `query(sql, params=None) -> list[dict]` | 原生查询，返回字典列表 |
-| 原生 SQL | `execute(sql, params=None) -> int` | 原生写入，返回影响行数 |
+| 原生 SQL | `execute(sql, params=None) -> int` | 原生写入，返回影响行数；`params` 传**字典列表**时批量执行（executemany，行键集须一致、行值须为标量、空列表返回 0） |
+| 原生 SQL | `prepare_statement(sql, params=None) -> (语句, dict \| None)` | **模块级函数**（`from kit.db import prepare_statement`）：构造可在**自有事务**内 `session.execute(stmt, bound)` 的语句，支持 `IN :ids`，调用方无须 import `sqlalchemy` |
 | 原生表 | `create_raw_table(table_name, columns, if_not_exists=True) -> None` | 按「列名 → 列定义」建普通表；⚠ 列定义须按目标库方言书写，不做方言翻译 |
 | 原生表 | `raw_insert(table_name, data) -> int` | 插入一行，返回影响行数 |
 | 原生表 | `raw_get_by(table_name, column, value) -> dict \| None` | 按单列等值取首行 |
@@ -354,8 +425,9 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 
 | 方法 | 说明 |
 |------|------|
-| `create_vector_table(table_name, dims, id_col="id", column="embedding", extra_cols=None) -> None` | 建含向量列的表；**`dims` 必填**（SQLite 用 `CHECK` 落实为数据库层约束；PG 硬约束并回读校验已存在表；MySQL 为上限语义） |
-| `insert_vectors(table_name, vectors, ids=None, extra_data=None, id_col="id", column="embedding") -> int` | 批量插入向量（单事务提交）；`ids=None` 时由 Kit 生成雪花 ID；接受 `list[list[float]]` 或二维 numpy 数组 |
+| `create_vector_table(table_name, dims, id_col="id", column="embedding", extra_cols=None) -> None` | 建含向量列的表；**`dims` 必填**（SQLite 用 `CHECK` 落实为数据库层约束；PG 硬约束并回读校验已存在表；MySQL 为上限语义）。`extra_cols` 支持 `{列名: 类型串}`（推荐，与 `create_raw_table` 同形）与 `[{"name","type"}]` 两种形态 |
+| `insert_vectors(table_name, vectors, ids=None, extra_data=None, id_col="id", column="embedding") -> int` | 批量插入向量（**自成一事务并提交**）；`ids=None` 时由 Kit 生成雪花 ID；接受 `list[list[float]]` 或二维 numpy 数组 |
+| `build_insert_vectors(table_name, vectors, ids=None, extra_data=None, id_col="id", column="embedding") -> list[tuple[str, list[dict]]]` | **只拼装、不执行、不管事务**：返回按列集分组的 `(SQL, 参数列表)`，供调用方在**自有事务**内写向量行（见「自有事务内写向量」） |
 | `search_vectors(table_name, query_vector, top_k=10, distance_type="L2", filter_sql=None, exact=True, id_col="id", column="embedding") -> list[dict]` | KNN 检索，按距离升序返回 `{"id", "distance"}`；`exact=True`（默认）禁止近似加速；**MySQL 侧抛 `VectorNotSupportedError`** |
 | `vector_version() -> str` | 向量后端版本；不可用时返回 `"unavailable"`（MySQL 侧为服务端版本号） |
 
@@ -440,6 +512,27 @@ PgKit.search_vectors("my_vec", [0.1] * 384, top_k=5, id_col="vid", column="vec")
 > 新增（非破坏性）：`VECTOR_CAPABILITIES` 能力声明、`id_col` / `column` 逃生口参数、
 > `insert_vectors` 支持二维 numpy 数组与批量提交。
 
+#### 0.2.5 变更（开发中，未发布）
+
+| 编号 | 变更 | 影响 |
+|------|------|------|
+| — | 新增**模块级公共函数** `prepare_statement(sql, params=None) -> (语句, 归一化参数)`：供调用方在**自有事务**内执行原生 SQL（含 `IN :ids`），**调用方无须 import `sqlalchemy`**；与 `query` / `execute` 同一实现（单一事实源） | **纯新增**：`query` / `transaction` 的签名与行为**零变更**；共享方法数仍为 **24**（模块级函数不计入） |
+| — | `execute` 的 `params` 支持**字典列表**（executemany，同一语句 + N 行参数一次往返）；**空列表**不触库返回 `0` | 向后兼容：单字典 / `None` 形态行为不变；批量要求各行字典**键集一致**、行值为**标量**（与 `IN` 展开互斥），违规在本地抛可操作 `ValueError`（含行号），不触库 |
+| — | 文档：自有事务示例改用 `prepare_statement`（不再需要 `from sqlalchemy import text`）；补「批量执行」说明与约束 | 文档 |
+
+> ⚠ `:name::type` 这类 PostgreSQL 风格 cast **不被 SQLAlchemy 的 `text()` 识别**（0.2.5 之前亦如此），
+> 请改用 `CAST(:name AS type)`。
+
+#### 0.2.4 变更
+
+| 编号 | 变更 | 影响 |
+|------|------|------|
+| B4 | **入参自洽性校验**（`extra_data` 的键）：保留绑定名 `id` / `vec`、与 `id_col` / `column` 重复、不是合法标识符、`id_col == column` → 抛可操作的 `ValueError` | **唯一行为变更**：此前 SQLite 会**静默写坏数据**（如 `id` 列被覆盖）、PG/MySQL 报误导性错误；正常调用**零影响** |
+| — | 新增共享方法 `build_insert_vectors`（只拼装不执行，由 `BaseDbKit` 收敛 → 共享方法 23 → **24**） | 纯新增：可在**自有事务**内写向量行（见下） |
+| — | `create_vector_table` 的 `extra_cols` 支持 `{列名: 类型串}`（与 `create_raw_table` 同形） | 纯新增：既有 `[{"name","type"}]` 形态保留，两者产出 DDL 逐字一致 |
+| — | 后端差异收口：向量列占位符由 `VECTOR_PLACEHOLDER` 驱动（MySQL = `STRING_TO_VECTOR(:vec)`） | 内部整理：公开签名与行为不变 |
+| — | `SQLiteKit.insert_vectors` 的事务获取统一为 `transaction()`（与另两库同构） | 内部一致：行为等价（自成一事务并提交） |
+
 #### 0.2.3 变更
 
 | 编号 | 变更 | 影响 |
@@ -457,18 +550,41 @@ rows = SQLiteKit.query("SELECT id, title FROM items WHERE id IN :ids",
                        {"ids": [h["id"] for h in hits]})   # IN 不保证顺序，需按 hits 重排
 ```
 
-**自有事务内写向量（SQLite）**：
+**自有事务内写向量（推荐：`build_insert_vectors` + `transaction()`）**：
 
 ```python
-conn = SQLiteKit.raw_connection()          # DBAPI 连接：位置参数 ? + 手工 commit
+from kit.db import SQLiteKit, prepare_statement   # 无须 import sqlalchemy
+
+with SQLiteKit.transaction() as session:          # 换成 PgKit / MySqlKit 写法相同
+    stmt, bound = prepare_statement(
+        "INSERT INTO docs_item (id, title) VALUES (:id, :t)", {"id": doc_id, "t": title})
+    session.execute(stmt, bound)                  # 第二个值必须一并传入
+    for sql, params in SQLiteKit.build_insert_vectors("docs_doc_vectors", vectors,
+                                                      ids=row_ids, extra_data=metas,
+                                                      id_col="rowid"):
+        session.execute(*prepare_statement(sql, params))
+# 正常退出统一提交；异常自动回滚（多处写入保持同一事务）
+```
+
+**SQLite 的 DBAPI 变体**（`raw_connection()` 支持 `:name` 命名参数）：
+
+```python
+conn = SQLiteKit.raw_connection()          # 调用方负责 commit / close
 try:
-    conn.execute("INSERT INTO item_vectors (id, embedding) VALUES (?, ?)",
-                 (item_id, SQLiteKit.encode_vector(vec)))
+    for sql, params in SQLiteKit.build_insert_vectors("item_vectors", vectors,
+                                                      ids=row_ids, extra_data=metas):
+        conn.executemany(sql, params)
     conn.commit()
 finally:
     conn.close()
 ```
 
+> ⚠ 两点约束：① `build_insert_vectors` 输出为 `:name` 风格，**PG / MySQL 的原生 DBAPI 不支持**
+> （psycopg2 / pymysql 需 `%(name)s`），只能经 `transaction()` 的 session 执行；
+> ② SQLite 上**持有未提交写事务**时再调 kit 的**自提交**方法（如 `insert_vectors`）会因另一个连接
+> 拿不到写锁而失败（`OperationalError: database is locked`，约 **6.4s** 后才报错）——
+> 把写入并入**同一个** `transaction()`（如上）即可避免。
+
 > 相似度换算建议：SQLite 仅支持 L2，若向量入库前已**归一化**，则 `cos = 1 − L2²/2`；
 > PG 可直接用 `distance_type="COSINE"`。
 

sdpy_kit-0.2.3/PKG-INFO → sdpy_kit-0.2.5/README.md

@@ -1,73 +1,3 @@
-Metadata-Version: 2.5
-Name: sdpy-kit
-Version: 0.2.3
-Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/MCP/Redis/文件/文档/向量工具集
-Author-email: Clark <changhongyuan@126.com>
-License-Expression: MIT
-Keywords: ai,kit,mcp,mysql,postgresql,redis,sdpy,sqlalchemy,sqlite,sqlmodel,向量检索,工具集,开发工具,数据库
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Natural Language :: Chinese (Simplified)
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Topic :: Database
-Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.13
-Requires-Dist: pydantic-settings>=2.15.0
-Requires-Dist: pydantic>=2.13.5
-Requires-Dist: sqlalchemy~=2.0.54
-Requires-Dist: sqlmodel>=0.0.46
-Provides-Extra: ai
-Requires-Dist: httpx>=0.28.1; extra == 'ai'
-Requires-Dist: python-dotenv>=1.2.3; extra == 'ai'
-Provides-Extra: all
-Requires-Dist: docxtpl>=0.20.2; extra == 'all'
-Requires-Dist: fastmcp>=4.0.5; extra == 'all'
-Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'all'
-Requires-Dist: httpx>=0.28.1; extra == 'all'
-Requires-Dist: markdown-it-py>=4.2.0; extra == 'all'
-Requires-Dist: marker-pdf[full]>=2.0.0; extra == 'all'
-Requires-Dist: numpy>=2.5.3; extra == 'all'
-Requires-Dist: pikepdf>=10.13.0; extra == 'all'
-Requires-Dist: pimd[pdfa]>=2.2.5; extra == 'all'
-Requires-Dist: psycopg2-binary>=2.9.13; extra == 'all'
-Requires-Dist: pymysql>=1.2.3; extra == 'all'
-Requires-Dist: python-dotenv>=1.2.3; extra == 'all'
-Requires-Dist: redis>=8.1.0; extra == 'all'
-Requires-Dist: requests>=2.34.2; extra == 'all'
-Requires-Dist: sqliteai-vector>=1.1.2; extra == 'all'
-Requires-Dist: zvec>=0.7.0; extra == 'all'
-Provides-Extra: anydoc
-Requires-Dist: firecrawl-anydoc>=0.2.4; extra == 'anydoc'
-Requires-Dist: pikepdf>=10.13.0; extra == 'anydoc'
-Provides-Extra: docx
-Requires-Dist: docxtpl>=0.20.2; extra == 'docx'
-Provides-Extra: marker
-Requires-Dist: marker-pdf[full]>=2.0.0; extra == 'marker'
-Provides-Extra: mcp
-Requires-Dist: fastmcp>=4.0.5; extra == 'mcp'
-Provides-Extra: md2doc
-Requires-Dist: markdown-it-py>=4.2.0; extra == 'md2doc'
-Requires-Dist: pimd[pdfa]>=2.2.5; extra == 'md2doc'
-Provides-Extra: mineru
-Requires-Dist: requests>=2.34.2; extra == 'mineru'
-Provides-Extra: mysql
-Requires-Dist: pymysql>=1.2.3; extra == 'mysql'
-Provides-Extra: pg
-Requires-Dist: psycopg2-binary>=2.9.13; extra == 'pg'
-Provides-Extra: redis
-Requires-Dist: redis>=8.1.0; extra == 'redis'
-Provides-Extra: sqliteai
-Requires-Dist: numpy>=2.5.3; extra == 'sqliteai'
-Requires-Dist: sqliteai-vector>=1.1.2; extra == 'sqliteai'
-Provides-Extra: zvec
-Requires-Dist: zvec>=0.7.0; extra == 'zvec'
-Description-Content-Type: text/markdown
-
 # sdpy-kit
 
 SDPY 统一工具集（Kit 体系），供 Python 项目开箱即用：
@@ -336,7 +266,7 @@ from kit.db import session_scope, transactional, DBError    # 推荐
 from kit import session_scope, transactional, DBError       # 等价
 ```
 
-### 1. 三个数据库 Kit（23 个共享方法 API 完全一致）
+### 1. 三个数据库 Kit（24 个共享方法 API 完全一致）
 
 | 类 | 导入 | 数据库 | extra |
 |----|------|--------|-------|
@@ -362,7 +292,8 @@ from kit import session_scope, transactional, DBError       # 等价
 | ORM | `upsert(model, data, conflict_fields) -> Model` | 原子插入或更新（`conflict_fields` 须为唯一约束） |
 | ORM | `count(model) -> int` | 记录总数 |
 | 原生 SQL | `query(sql, params=None) -> list[dict]` | 原生查询，返回字典列表 |
-| 原生 SQL | `execute(sql, params=None) -> int` | 原生写入，返回影响行数 |
+| 原生 SQL | `execute(sql, params=None) -> int` | 原生写入，返回影响行数；`params` 传**字典列表**时批量执行（executemany，行键集须一致、行值须为标量、空列表返回 0） |
+| 原生 SQL | `prepare_statement(sql, params=None) -> (语句, dict \| None)` | **模块级函数**（`from kit.db import prepare_statement`）：构造可在**自有事务**内 `session.execute(stmt, bound)` 的语句，支持 `IN :ids`，调用方无须 import `sqlalchemy` |
 | 原生表 | `create_raw_table(table_name, columns, if_not_exists=True) -> None` | 按「列名 → 列定义」建普通表；⚠ 列定义须按目标库方言书写，不做方言翻译 |
 | 原生表 | `raw_insert(table_name, data) -> int` | 插入一行，返回影响行数 |
 | 原生表 | `raw_get_by(table_name, column, value) -> dict \| None` | 按单列等值取首行 |
@@ -424,8 +355,9 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 
 | 方法 | 说明 |
 |------|------|
-| `create_vector_table(table_name, dims, id_col="id", column="embedding", extra_cols=None) -> None` | 建含向量列的表；**`dims` 必填**（SQLite 用 `CHECK` 落实为数据库层约束；PG 硬约束并回读校验已存在表；MySQL 为上限语义） |
-| `insert_vectors(table_name, vectors, ids=None, extra_data=None, id_col="id", column="embedding") -> int` | 批量插入向量（单事务提交）；`ids=None` 时由 Kit 生成雪花 ID；接受 `list[list[float]]` 或二维 numpy 数组 |
+| `create_vector_table(table_name, dims, id_col="id", column="embedding", extra_cols=None) -> None` | 建含向量列的表；**`dims` 必填**（SQLite 用 `CHECK` 落实为数据库层约束；PG 硬约束并回读校验已存在表；MySQL 为上限语义）。`extra_cols` 支持 `{列名: 类型串}`（推荐，与 `create_raw_table` 同形）与 `[{"name","type"}]` 两种形态 |
+| `insert_vectors(table_name, vectors, ids=None, extra_data=None, id_col="id", column="embedding") -> int` | 批量插入向量（**自成一事务并提交**）；`ids=None` 时由 Kit 生成雪花 ID；接受 `list[list[float]]` 或二维 numpy 数组 |
+| `build_insert_vectors(table_name, vectors, ids=None, extra_data=None, id_col="id", column="embedding") -> list[tuple[str, list[dict]]]` | **只拼装、不执行、不管事务**：返回按列集分组的 `(SQL, 参数列表)`，供调用方在**自有事务**内写向量行（见「自有事务内写向量」） |
 | `search_vectors(table_name, query_vector, top_k=10, distance_type="L2", filter_sql=None, exact=True, id_col="id", column="embedding") -> list[dict]` | KNN 检索，按距离升序返回 `{"id", "distance"}`；`exact=True`（默认）禁止近似加速；**MySQL 侧抛 `VectorNotSupportedError`** |
 | `vector_version() -> str` | 向量后端版本；不可用时返回 `"unavailable"`（MySQL 侧为服务端版本号） |
 
@@ -510,6 +442,27 @@ PgKit.search_vectors("my_vec", [0.1] * 384, top_k=5, id_col="vid", column="vec")
 > 新增（非破坏性）：`VECTOR_CAPABILITIES` 能力声明、`id_col` / `column` 逃生口参数、
 > `insert_vectors` 支持二维 numpy 数组与批量提交。
 
+#### 0.2.5 变更（开发中，未发布）
+
+| 编号 | 变更 | 影响 |
+|------|------|------|
+| — | 新增**模块级公共函数** `prepare_statement(sql, params=None) -> (语句, 归一化参数)`：供调用方在**自有事务**内执行原生 SQL（含 `IN :ids`），**调用方无须 import `sqlalchemy`**；与 `query` / `execute` 同一实现（单一事实源） | **纯新增**：`query` / `transaction` 的签名与行为**零变更**；共享方法数仍为 **24**（模块级函数不计入） |
+| — | `execute` 的 `params` 支持**字典列表**（executemany，同一语句 + N 行参数一次往返）；**空列表**不触库返回 `0` | 向后兼容：单字典 / `None` 形态行为不变；批量要求各行字典**键集一致**、行值为**标量**（与 `IN` 展开互斥），违规在本地抛可操作 `ValueError`（含行号），不触库 |
+| — | 文档：自有事务示例改用 `prepare_statement`（不再需要 `from sqlalchemy import text`）；补「批量执行」说明与约束 | 文档 |
+
+> ⚠ `:name::type` 这类 PostgreSQL 风格 cast **不被 SQLAlchemy 的 `text()` 识别**（0.2.5 之前亦如此），
+> 请改用 `CAST(:name AS type)`。
+
+#### 0.2.4 变更
+
+| 编号 | 变更 | 影响 |
+|------|------|------|
+| B4 | **入参自洽性校验**（`extra_data` 的键）：保留绑定名 `id` / `vec`、与 `id_col` / `column` 重复、不是合法标识符、`id_col == column` → 抛可操作的 `ValueError` | **唯一行为变更**：此前 SQLite 会**静默写坏数据**（如 `id` 列被覆盖）、PG/MySQL 报误导性错误；正常调用**零影响** |
+| — | 新增共享方法 `build_insert_vectors`（只拼装不执行，由 `BaseDbKit` 收敛 → 共享方法 23 → **24**） | 纯新增：可在**自有事务**内写向量行（见下） |
+| — | `create_vector_table` 的 `extra_cols` 支持 `{列名: 类型串}`（与 `create_raw_table` 同形） | 纯新增：既有 `[{"name","type"}]` 形态保留，两者产出 DDL 逐字一致 |
+| — | 后端差异收口：向量列占位符由 `VECTOR_PLACEHOLDER` 驱动（MySQL = `STRING_TO_VECTOR(:vec)`） | 内部整理：公开签名与行为不变 |
+| — | `SQLiteKit.insert_vectors` 的事务获取统一为 `transaction()`（与另两库同构） | 内部一致：行为等价（自成一事务并提交） |
+
 #### 0.2.3 变更
 
 | 编号 | 变更 | 影响 |
@@ -527,18 +480,41 @@ rows = SQLiteKit.query("SELECT id, title FROM items WHERE id IN :ids",
                        {"ids": [h["id"] for h in hits]})   # IN 不保证顺序，需按 hits 重排
 ```
 
-**自有事务内写向量（SQLite）**：
+**自有事务内写向量（推荐：`build_insert_vectors` + `transaction()`）**：
 
 ```python
-conn = SQLiteKit.raw_connection()          # DBAPI 连接：位置参数 ? + 手工 commit
+from kit.db import SQLiteKit, prepare_statement   # 无须 import sqlalchemy
+
+with SQLiteKit.transaction() as session:          # 换成 PgKit / MySqlKit 写法相同
+    stmt, bound = prepare_statement(
+        "INSERT INTO docs_item (id, title) VALUES (:id, :t)", {"id": doc_id, "t": title})
+    session.execute(stmt, bound)                  # 第二个值必须一并传入
+    for sql, params in SQLiteKit.build_insert_vectors("docs_doc_vectors", vectors,
+                                                      ids=row_ids, extra_data=metas,
+                                                      id_col="rowid"):
+        session.execute(*prepare_statement(sql, params))
+# 正常退出统一提交；异常自动回滚（多处写入保持同一事务）
+```
+
+**SQLite 的 DBAPI 变体**（`raw_connection()` 支持 `:name` 命名参数）：
+
+```python
+conn = SQLiteKit.raw_connection()          # 调用方负责 commit / close
 try:
-    conn.execute("INSERT INTO item_vectors (id, embedding) VALUES (?, ?)",
-                 (item_id, SQLiteKit.encode_vector(vec)))
+    for sql, params in SQLiteKit.build_insert_vectors("item_vectors", vectors,
+                                                      ids=row_ids, extra_data=metas):
+        conn.executemany(sql, params)
     conn.commit()
 finally:
     conn.close()
 ```
 
+> ⚠ 两点约束：① `build_insert_vectors` 输出为 `:name` 风格，**PG / MySQL 的原生 DBAPI 不支持**
+> （psycopg2 / pymysql 需 `%(name)s`），只能经 `transaction()` 的 session 执行；
+> ② SQLite 上**持有未提交写事务**时再调 kit 的**自提交**方法（如 `insert_vectors`）会因另一个连接
+> 拿不到写锁而失败（`OperationalError: database is locked`，约 **6.4s** 后才报错）——
+> 把写入并入**同一个** `transaction()`（如上）即可避免。
+
 > 相似度换算建议：SQLite 仅支持 L2，若向量入库前已**归一化**，则 `cos = 1 − L2²/2`；
 > PG 可直接用 `distance_type="COSINE"`。
 

{sdpy_kit-0.2.3 → sdpy_kit-0.2.5}/kit/__init__.py

@@ -23,7 +23,7 @@ Author: Clark Chang
 数据库访问通过 kit.db 子包提供（基于 SQLModel）。
 """
 
-__version__ = "0.2.3"
+__version__ = "0.2.5"
 
 from kit.db import (
     MYSQL,
@@ -47,6 +47,7 @@ from kit.db import (
     get_engine,
     get_session,
     list_tables,
+    prepare_statement,
     session_scope,
     table_exists,
     to_vector_literal,
@@ -85,6 +86,8 @@ __all__ = [
     "CRUDBase",
     # 事务
     "transactional",
+    # 原生 SQL 语句构造（公共）
+    "prepare_statement",
     # 向量工具（公共）
     "to_vector_literal",
     "generate_snowflake_ids",

{sdpy_kit-0.2.3 → sdpy_kit-0.2.5}/kit/db/__init__.py

@@ -32,6 +32,7 @@ Author: Clark Chang
 from kit.db.base_db_kit import (
     DEFAULT_DISTANCE_TYPE,
     generate_snowflake_ids,
+    prepare_statement,
     to_vector_literal,
 )
 from kit.db.crud import CRUDBase
@@ -87,6 +88,9 @@ __all__ = [
     "CRUDBase",
     # 事务
     "transactional",
+    # 原生 SQL 语句构造（公共）
+    # 自有事务内执行原生 SQL（含列表参数 IN :ids）时使用，调用方无须 import sqlalchemy
+    "prepare_statement",
     # 向量工具（公共）
     "to_vector_literal",
     "generate_snowflake_ids",