sdpy-kit 0.2.2__tar.gz → 0.2.4__tar.gz

{sdpy_kit-0.2.2 → sdpy_kit-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.2.2
+Version: 0.2.4
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/MCP/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -336,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 |
 |----|------|--------|-------|
@@ -370,13 +370,23 @@ from kit import session_scope, transactional, DBError       # 等价
 | 表 | `list_tables() -> list[str]` | 列出全部表名 |
 | 表 | `table_exists(table_name) -> bool` | 判断表是否存在 |
 | 表 | `create_tables(models) -> None` | 按模型列表建表 |
-| 表 | `get_table_info(table_name) -> list[dict]` | 获取列信息（三个 Kit 各自实现） |
+| 表 | `get_table_info(table_name) -> list[dict]` | 获取列信息（按列序；公共键 4 个：`column_name`/`data_type`/`is_nullable`/`column_default`） |
+
+> **列表参数（`IN`）**：`query` / `execute` 的 `params` 中值为 `list`/`tuple`/`set`/`frozenset`
+> 时按 `IN` 展开，可直接写 `WHERE id IN :ids`（三库通用）。`IN` **不保证顺序**；参数列表过大
+> 应分批（PG 单语句上限 65535 参数）。
+>
+> **`LIKE` 的方言差异**：SQLite 对 ASCII 不区分大小写，PostgreSQL 区分（用 `ILIKE`）；
+> 跨库一致写法：`LOWER(col) LIKE LOWER(:pattern)`。
+>
+> **导出面**：`from kit.db import PgKit, SQLiteKit, build_pg_url, to_vector_literal, …`
+> （`kit` 顶层与 `kit.db` 导出同一套符号）。
 
 ```python
 from sqlalchemy import BigInteger
 from sqlmodel import SQLModel, Field
 from kit.common_kit import CommonKit
-from kit.db.sqlite_kit import SQLiteKit
+from kit.db import SQLiteKit          # 也可 from kit.db.sqlite_kit import SQLiteKit
 
 class User(SQLModel, table=True):
     # 主键：64 位整数 + 雪花 ID（应用侧生成，不用数据库自增）
@@ -393,6 +403,7 @@ users = SQLiteKit.list(User, skip=0, limit=10, order_by="id", desc=True)
 
 rows = SQLiteKit.query("SELECT * FROM user WHERE name = :name", {"name": "李四"})
 affected = SQLiteKit.execute("UPDATE user SET name = '王五' WHERE id = :id", {"id": user.id})
+rows = SQLiteKit.query("SELECT * FROM user WHERE id IN :ids", {"ids": [1, 2, 3]})   # 列表参数
 
 with SQLiteKit.transaction() as session:                  # 多操作原子提交
     SQLiteKit.create(User, {"name": "批量一"})
@@ -413,8 +424,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 侧为服务端版本号） |
 
@@ -499,6 +511,70 @@ 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.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 变更
+
+| 编号 | 变更 | 影响 |
+|------|------|------|
+| B6 | **`PgKit.get_table_info` 按数据库解析语义定位表**（`search_path` 解析到的那张表） | 多 schema 下同名表**不再混行**；单 schema / `public` 场景**无影响**；只接受非限定表名 |
+| — | `query` / `execute` 支持**列表参数**（`IN :ids`，三库通用） | 纯新增；`set`/`frozenset` 自动归一化为 `list` |
+| — | 新增 `SQLiteKit.encode_vector` / `decode_vector`（小端 float32） | 纯新增：可在自有事务内写向量表，见下 |
+| — | 导出面统一：`from kit.db import PgKit, MySqlKit, SQLiteKit, build_pg_url, …` | 纯新增；既有导出未删除/未改名 |
+
+**两段查询范式（推荐用法）**：`search_vectors` 只返回 `[{"id", "distance"}]`，载荷二次取回：
+
+```python
+hits = SQLiteKit.search_vectors("item_vectors", query_vector, top_k=5)
+rows = SQLiteKit.query("SELECT id, title FROM items WHERE id IN :ids",
+                       {"ids": [h["id"] for h in hits]})   # IN 不保证顺序，需按 hits 重排
+```
+
+**自有事务内写向量（推荐：`build_insert_vectors` + `transaction()`）**：
+
+```python
+from sqlalchemy import text
+
+with SQLiteKit.transaction() as session:          # 换成 PgKit / MySqlKit 写法相同
+    session.execute(text("INSERT INTO docs_item (id, title) VALUES (:id, :t)"),
+                    {"id": doc_id, "t": title})
+    for sql, params in SQLiteKit.build_insert_vectors("docs_doc_vectors", vectors,
+                                                      ids=row_ids, extra_data=metas,
+                                                      id_col="rowid"):
+        session.execute(text(sql), params)
+# 正常退出统一提交；异常自动回滚（多处写入保持同一事务）
+```
+
+**SQLite 的 DBAPI 变体**（`raw_connection()` 支持 `:name` 命名参数）：
+
+```python
+conn = SQLiteKit.raw_connection()          # 调用方负责 commit / close
+try:
+    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"`。
+
 ### 3. CRUDBase（配合 session_scope，不自动提交）
 
 ```python

{sdpy_kit-0.2.2 → sdpy_kit-0.2.4}/README.md

@@ -266,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 |
 |----|------|--------|-------|
@@ -300,13 +300,23 @@ from kit import session_scope, transactional, DBError       # 等价
 | 表 | `list_tables() -> list[str]` | 列出全部表名 |
 | 表 | `table_exists(table_name) -> bool` | 判断表是否存在 |
 | 表 | `create_tables(models) -> None` | 按模型列表建表 |
-| 表 | `get_table_info(table_name) -> list[dict]` | 获取列信息（三个 Kit 各自实现） |
+| 表 | `get_table_info(table_name) -> list[dict]` | 获取列信息（按列序；公共键 4 个：`column_name`/`data_type`/`is_nullable`/`column_default`） |
+
+> **列表参数（`IN`）**：`query` / `execute` 的 `params` 中值为 `list`/`tuple`/`set`/`frozenset`
+> 时按 `IN` 展开，可直接写 `WHERE id IN :ids`（三库通用）。`IN` **不保证顺序**；参数列表过大
+> 应分批（PG 单语句上限 65535 参数）。
+>
+> **`LIKE` 的方言差异**：SQLite 对 ASCII 不区分大小写，PostgreSQL 区分（用 `ILIKE`）；
+> 跨库一致写法：`LOWER(col) LIKE LOWER(:pattern)`。
+>
+> **导出面**：`from kit.db import PgKit, SQLiteKit, build_pg_url, to_vector_literal, …`
+> （`kit` 顶层与 `kit.db` 导出同一套符号）。
 
 ```python
 from sqlalchemy import BigInteger
 from sqlmodel import SQLModel, Field
 from kit.common_kit import CommonKit
-from kit.db.sqlite_kit import SQLiteKit
+from kit.db import SQLiteKit          # 也可 from kit.db.sqlite_kit import SQLiteKit
 
 class User(SQLModel, table=True):
     # 主键：64 位整数 + 雪花 ID（应用侧生成，不用数据库自增）
@@ -323,6 +333,7 @@ users = SQLiteKit.list(User, skip=0, limit=10, order_by="id", desc=True)
 
 rows = SQLiteKit.query("SELECT * FROM user WHERE name = :name", {"name": "李四"})
 affected = SQLiteKit.execute("UPDATE user SET name = '王五' WHERE id = :id", {"id": user.id})
+rows = SQLiteKit.query("SELECT * FROM user WHERE id IN :ids", {"ids": [1, 2, 3]})   # 列表参数
 
 with SQLiteKit.transaction() as session:                  # 多操作原子提交
     SQLiteKit.create(User, {"name": "批量一"})
@@ -343,8 +354,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 侧为服务端版本号） |
 
@@ -429,6 +441,70 @@ 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.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 变更
+
+| 编号 | 变更 | 影响 |
+|------|------|------|
+| B6 | **`PgKit.get_table_info` 按数据库解析语义定位表**（`search_path` 解析到的那张表） | 多 schema 下同名表**不再混行**；单 schema / `public` 场景**无影响**；只接受非限定表名 |
+| — | `query` / `execute` 支持**列表参数**（`IN :ids`，三库通用） | 纯新增；`set`/`frozenset` 自动归一化为 `list` |
+| — | 新增 `SQLiteKit.encode_vector` / `decode_vector`（小端 float32） | 纯新增：可在自有事务内写向量表，见下 |
+| — | 导出面统一：`from kit.db import PgKit, MySqlKit, SQLiteKit, build_pg_url, …` | 纯新增；既有导出未删除/未改名 |
+
+**两段查询范式（推荐用法）**：`search_vectors` 只返回 `[{"id", "distance"}]`，载荷二次取回：
+
+```python
+hits = SQLiteKit.search_vectors("item_vectors", query_vector, top_k=5)
+rows = SQLiteKit.query("SELECT id, title FROM items WHERE id IN :ids",
+                       {"ids": [h["id"] for h in hits]})   # IN 不保证顺序，需按 hits 重排
+```
+
+**自有事务内写向量（推荐：`build_insert_vectors` + `transaction()`）**：
+
+```python
+from sqlalchemy import text
+
+with SQLiteKit.transaction() as session:          # 换成 PgKit / MySqlKit 写法相同
+    session.execute(text("INSERT INTO docs_item (id, title) VALUES (:id, :t)"),
+                    {"id": doc_id, "t": title})
+    for sql, params in SQLiteKit.build_insert_vectors("docs_doc_vectors", vectors,
+                                                      ids=row_ids, extra_data=metas,
+                                                      id_col="rowid"):
+        session.execute(text(sql), params)
+# 正常退出统一提交；异常自动回滚（多处写入保持同一事务）
+```
+
+**SQLite 的 DBAPI 变体**（`raw_connection()` 支持 `:name` 命名参数）：
+
+```python
+conn = SQLiteKit.raw_connection()          # 调用方负责 commit / close
+try:
+    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"`。
+
 ### 3. CRUDBase（配合 session_scope，不自动提交）
 
 ```python

{sdpy_kit-0.2.2 → sdpy_kit-0.2.4}/kit/__init__.py

@@ -23,26 +23,37 @@ Author: Clark Chang
 数据库访问通过 kit.db 子包提供（基于 SQLModel）。
 """
 
-__version__ = "0.2.2"
+__version__ = "0.2.4"
 
 from kit.db import (
     MYSQL,
     POSTGRESQL,
     SQLITE,
     CRUDBase,
+    DEFAULT_DISTANCE_TYPE,
     DBError,
+    MySqlKit,
     NotFoundError,
+    PgKit,
+    SQLiteKit,
+    VectorNotSupportedError,
+    build_mysql_url,
+    build_pg_url,
+    build_sqlite_url,
     close_all_engines,
     close_engine,
     create_tables,
+    generate_snowflake_ids,
     get_engine,
     get_session,
     list_tables,
     session_scope,
     table_exists,
+    to_vector_literal,
     transactional,
 )
 
+# 顶层公共面与 kit.db 保持一致（同一套符号，避免两处入口漂移）
 __all__ = [
     # 引擎管理
     "get_engine",
@@ -51,18 +62,31 @@ __all__ = [
     "table_exists",
     "close_all_engines",
     "close_engine",
+    # 连接串构造（单一来源）
+    "build_pg_url",
+    "build_mysql_url",
+    "build_sqlite_url",
     # 常量
     "POSTGRESQL",
     "MYSQL",
     "SQLITE",
+    # 数据库 Kit
+    "PgKit",
+    "MySqlKit",
+    "SQLiteKit",
     # 会话
     "session_scope",
     "get_session",
     # 异常
     "DBError",
     "NotFoundError",
+    "VectorNotSupportedError",
     # CRUD
     "CRUDBase",
     # 事务
     "transactional",
+    # 向量工具（公共）
+    "to_vector_literal",
+    "generate_snowflake_ids",
+    "DEFAULT_DISTANCE_TYPE",
 ]

{sdpy_kit-0.2.2 → sdpy_kit-0.2.4}/kit/db/__init__.py

@@ -29,11 +29,19 @@ Author: Clark Chang
 - SQLModel 混入类（models/base.py）
 """
 
+from kit.db.base_db_kit import (
+    DEFAULT_DISTANCE_TYPE,
+    generate_snowflake_ids,
+    to_vector_literal,
+)
 from kit.db.crud import CRUDBase
 from kit.db.engine import (
     MYSQL,
     POSTGRESQL,
     SQLITE,
+    build_mysql_url,
+    build_pg_url,
+    build_sqlite_url,
     close_all_engines,
     close_engine,
     create_tables,
@@ -42,7 +50,10 @@ from kit.db.engine import (
     table_exists,
 )
 from kit.db.exceptions import DBError, NotFoundError, VectorNotSupportedError
+from kit.db.mysql_kit import MySqlKit
+from kit.db.pg_kit import PgKit
 from kit.db.session import get_session, session_scope
+from kit.db.sqlite_kit import SQLiteKit
 from kit.db.transaction import transactional
 
 __all__ = [
@@ -53,10 +64,18 @@ __all__ = [
     "table_exists",
     "close_all_engines",
     "close_engine",
+    # 连接串构造（单一来源，测试/工具可复用）
+    "build_pg_url",
+    "build_mysql_url",
+    "build_sqlite_url",
     # 常量
     "POSTGRESQL",
     "MYSQL",
     "SQLITE",
+    # 数据库 Kit
+    "PgKit",
+    "MySqlKit",
+    "SQLiteKit",
     # 会话
     "session_scope",
     "get_session",
@@ -68,4 +87,8 @@ __all__ = [
     "CRUDBase",
     # 事务
     "transactional",
+    # 向量工具（公共）
+    "to_vector_literal",
+    "generate_snowflake_ids",
+    "DEFAULT_DISTANCE_TYPE",
 ]