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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.2.1
+Version: 0.2.2
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/MCP/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -400,8 +400,9 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 ```
 
 > 切换数据库：把 import 的 `SQLiteKit` 换成 `PgKit` / `MySqlKit` 即可，其余代码不变。
-> 注意两点例外：① `create_raw_table` 的列定义文本须按目标库方言改写；② 向量能力
-> **三库同名同参但能力不同**，尤其 **MySQL 侧检索不可用**（见下）。
+> 注意三点例外：① `create_raw_table` 的列定义文本须按目标库方言改写；② 向量能力
+> **三库同名同参但能力不同**（可由 `VECTOR_CAPABILITIES` feature-detect），尤其
+> **MySQL 侧检索不可用**；③ `create_vector_table` 的 `dims` 为**必填**参数。
 
 ### 2. 向量方法（三库同名同参，能力差异化）
 
@@ -412,21 +413,34 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 
 | 方法 | 说明 |
 |------|------|
-| `create_vector_table(table_name, id_col="id", dims=384, extra_cols=None) -> None` | 建含向量列的表（PG / MySQL 侧 `dims` 有约束） |
-| `insert_vectors(table_name, vectors, ids=None, extra_data=None) -> int` | 批量插入向量（单事务提交）；`ids=None` 时由 Kit 生成雪花 ID |
-| `search_vectors(table_name, query_vector, top_k=10, distance_type="COSINE", filter_sql=None) -> list[dict]` | KNN 检索，按距离升序返回 `{"id", "distance"}`；**MySQL 侧抛 `NotImplementedError`** |
+| `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 数组 |
+| `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 侧为服务端版本号） |
 
-**能力差异（跨库不可比较 `distance` 数值）**：
+**`id_col` / `column`（逃生口）**：让**自建 DDL 的向量表**也能读写/检索。需要复合主键、额外约束、
+分区或与既有业务表合表时，用 `execute()` 自建 DDL 再用这两个参数接入；SQLite 侧要求 `id_col`
+为 rowid 别名（`INTEGER PRIMARY KEY`）。
+
+**`exact` 参数（默认 `True` = 禁止近似加速）**：
+
+| 后端 | `exact=True`（默认） | `exact=False` | 是否提速 |
+|------|---------------------|---------------|----------|
+| `PgKit` | 同事务 `SET LOCAL enable_indexscan = off`（有索引也精确；**代价：该查询不使用任何索引**，含过滤列索引） | 不干预查询计划（有索引即近似召回，`distance` 仍为真值） | ✅ 仅"大表 + 已建索引"时 |
+| `SQLiteKit` | `vector_full_scan`（**真值 L2**） | `vector_quantize_scan`（量化 L2 = 真值 × 255） | ❌ **不提速**（每次调用重建量化） |
+| `MySqlKit` | 不适用 | 同左 | — |
+
+**能力差异（仅 L2 可跨库比较数值；float32 vs float64，需带容差）**：
 
 | 项 | `SQLiteKit`（sqlite-vector） | `PgKit`（pgvector） | `MySqlKit`（9.x 原生） |
 |----|------------------------------|---------------------|------------------------|
-| 支持的 `distance_type` | **仅 L2**（该形参当前不生效，取任何值结果相同） | `COSINE` / `L2` / `L1` / `DOT`（负内积） / `SQUARED_L2` | **无（检索不可用）** |
-| 非法取值 | 忽略 | 抛 `ValueError` | `search_vectors` 一律抛 `NotImplementedError` |
-| `distance` 口径 | int8 量化整数距离（= L2 × 255，非物理距离） | 真实距离 | — |
-| 维度约束 | 无 | 强制（不匹配即报错） | 上限约束（超限报错） |
-| `filter_sql` 与 `top_k` | **先取 top_k 再过滤**（可能少于 top_k） | **先过滤再取 top_k** | 不适用 |
-| 索引 | 每次检索 `vector_init` + `vector_quantize` | 默认无索引（可自建 hnsw/ivfflat） | 无法建（B-Tree 拒绝向量列） |
+| 支持的 `distance_type` | **仅 L2** | `COSINE` / `L2` / `L1` / `DOT`（负内积） / `SQUARED_L2` | **无（检索不可用）** |
+| 默认 `distance_type` | `"L2"` | `"L2"`（三库统一，不按后端覆写） | `"L2"`（形参保留，调用即抛错） |
+| 非法取值 | 抛 `ValueError` | 抛 `ValueError` | `search_vectors` 抛 `VectorNotSupportedError` |
+| `distance` 口径 | `exact=True` 真值 L2 / `exact=False` 量化（×255） | 真实距离 | — |
+| 维度约束 | `CHECK`（仅新表；旧表靠方法内校验） | 强制（不匹配即报错；建表时回读比对） | 上限约束（超限报错） |
+| `filter_sql` 与 `top_k` | **先过滤再取 top_k**（与 PG 一致） | **先过滤再取 top_k** | 不适用 |
+| 索引 | 无（精确路径为全表扫描） | kit 不建索引；**自建后须 `exact=False` 才会被使用** | 无法建（B-Tree 拒绝向量列） |
 
 > MySQL `DISTANCE()` / `VECTOR_DISTANCE()` 仅 HeatWave on OCI 与 MySQL AI 提供
 > （Community 实测报 `1305 FUNCTION ... does not exist`）；故 `MySqlKit` 只覆盖存储侧。
@@ -438,24 +452,53 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 多实例部署需各自 `CommonKit.configure(datacenter_id, machine_id)`（默认 `(1,1)` 会重复）。
 
 ```python
-# SQLite
+# SQLite（默认精确：distance 为真值 L2）
 from kit.db.sqlite_kit import SQLiteKit
-SQLiteKit.create_vector_table("images", dims=384)
+SQLiteKit.create_vector_table("images", 384)          # dims 必填
 SQLiteKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
 rows = SQLiteKit.search_vectors("images", [0.1] * 384, top_k=5)
+rows = SQLiteKit.search_vectors("images", [0.1] * 384, top_k=5, exact=False)  # 旧量化口径（不提速）
 
 # PostgreSQL（签名相同；可选 COSINE/L2/L1/DOT/SQUARED_L2）
 from kit.db.pg_kit import PgKit
-PgKit.create_vector_table("images", dims=384)
+PgKit.create_vector_table("images", 384)
 PgKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
-rows = PgKit.search_vectors("images", [0.1] * 384, top_k=5, distance_type="L2")
+rows = PgKit.search_vectors("images", [0.1] * 384, top_k=5, distance_type="COSINE")
+# 大表 + 自建索引时才用 exact=False（否则索引不被使用，见上表）
+PgKit.execute("CREATE INDEX ON images USING hnsw (embedding vector_cosine_ops)")
+rows = PgKit.search_vectors("images", [0.1] * 384, top_k=5,
+                            distance_type="COSINE", exact=False)
 
-# MySQL（仅存储；search_vectors 会抛 NotImplementedError）
+# MySQL（仅存储；search_vectors 抛 VectorNotSupportedError）
 from kit.db.mysql_kit import MySqlKit
-MySqlKit.create_vector_table("images", dims=384)
+MySqlKit.create_vector_table("images", 384)
 MySqlKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
+
+# 能力自省（无需 try/except）
+PgKit.VECTOR_CAPABILITIES
+# {'store': True, 'search': True, 'exact': True,
+#  'distances': ('COSINE', 'L2', 'L1', 'DOT', 'SQUARED_L2'),
+#  'distance_kind': 'true', 'fast_distance_kind': 'true'}
+
+# 自建 DDL 的表：用 id_col / column 接入
+PgKit.execute("CREATE TABLE my_vec (vid BIGINT PRIMARY KEY, vec vector(384))")
+PgKit.insert_vectors("my_vec", [[0.1] * 384], ids=[1], id_col="vid", column="vec")
+PgKit.search_vectors("my_vec", [0.1] * 384, top_k=5, id_col="vid", column="vec")
 ```
 
+#### 0.2.2 行为变更（升级须知）
+
+| 编号 | 变更 | 影响 |
+|------|------|------|
+| B1 | `search_vectors` 新增 `exact: bool = True`，默认**精确** | SQLite 返回的 `distance` 由量化值（≈L2×255）变为**真值 L2**；需旧口径请显式 `exact=False` |
+| B2 | `filter_sql` 语义统一为**先过滤、再取 top_k** | 传 `filter_sql` 的调用返回值**变多/变全**（旧结果 ⊆ 新结果）；曾自行放大 `top_k` 兜底的调用可收紧 |
+| B3 | 默认 `distance_type` 由 `"COSINE"` 改为 `"L2"` | 依赖默认值的调用方请显式传 `distance_type="COSINE"` |
+| B4 | `create_vector_table` 的 `dims` **必填**，参数顺序为 `(table_name, dims, id_col, column, extra_cols)` | `create_vector_table("t")` 类调用需补维度；位置传 `id_col` 的调用改为关键字 |
+| B5 | MySQL 的 `search_vectors` 异常由 `NotImplementedError` 改为 `VectorNotSupportedError`（继承 `DBError`） | `except NotImplementedError` 需改为 `except VectorNotSupportedError`（或 `except DBError`） |
+
+> 新增（非破坏性）：`VECTOR_CAPABILITIES` 能力声明、`id_col` / `column` 逃生口参数、
+> `insert_vectors` 支持二维 numpy 数组与批量提交。
+
 ### 3. CRUDBase（配合 session_scope，不自动提交）
 
 ```python

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

@@ -330,8 +330,9 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 ```
 
 > 切换数据库：把 import 的 `SQLiteKit` 换成 `PgKit` / `MySqlKit` 即可，其余代码不变。
-> 注意两点例外：① `create_raw_table` 的列定义文本须按目标库方言改写；② 向量能力
-> **三库同名同参但能力不同**，尤其 **MySQL 侧检索不可用**（见下）。
+> 注意三点例外：① `create_raw_table` 的列定义文本须按目标库方言改写；② 向量能力
+> **三库同名同参但能力不同**（可由 `VECTOR_CAPABILITIES` feature-detect），尤其
+> **MySQL 侧检索不可用**；③ `create_vector_table` 的 `dims` 为**必填**参数。
 
 ### 2. 向量方法（三库同名同参，能力差异化）
 
@@ -342,21 +343,34 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 
 | 方法 | 说明 |
 |------|------|
-| `create_vector_table(table_name, id_col="id", dims=384, extra_cols=None) -> None` | 建含向量列的表（PG / MySQL 侧 `dims` 有约束） |
-| `insert_vectors(table_name, vectors, ids=None, extra_data=None) -> int` | 批量插入向量（单事务提交）；`ids=None` 时由 Kit 生成雪花 ID |
-| `search_vectors(table_name, query_vector, top_k=10, distance_type="COSINE", filter_sql=None) -> list[dict]` | KNN 检索，按距离升序返回 `{"id", "distance"}`；**MySQL 侧抛 `NotImplementedError`** |
+| `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 数组 |
+| `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 侧为服务端版本号） |
 
-**能力差异（跨库不可比较 `distance` 数值）**：
+**`id_col` / `column`（逃生口）**：让**自建 DDL 的向量表**也能读写/检索。需要复合主键、额外约束、
+分区或与既有业务表合表时，用 `execute()` 自建 DDL 再用这两个参数接入；SQLite 侧要求 `id_col`
+为 rowid 别名（`INTEGER PRIMARY KEY`）。
+
+**`exact` 参数（默认 `True` = 禁止近似加速）**：
+
+| 后端 | `exact=True`（默认） | `exact=False` | 是否提速 |
+|------|---------------------|---------------|----------|
+| `PgKit` | 同事务 `SET LOCAL enable_indexscan = off`（有索引也精确；**代价：该查询不使用任何索引**，含过滤列索引） | 不干预查询计划（有索引即近似召回，`distance` 仍为真值） | ✅ 仅"大表 + 已建索引"时 |
+| `SQLiteKit` | `vector_full_scan`（**真值 L2**） | `vector_quantize_scan`（量化 L2 = 真值 × 255） | ❌ **不提速**（每次调用重建量化） |
+| `MySqlKit` | 不适用 | 同左 | — |
+
+**能力差异（仅 L2 可跨库比较数值；float32 vs float64，需带容差）**：
 
 | 项 | `SQLiteKit`（sqlite-vector） | `PgKit`（pgvector） | `MySqlKit`（9.x 原生） |
 |----|------------------------------|---------------------|------------------------|
-| 支持的 `distance_type` | **仅 L2**（该形参当前不生效，取任何值结果相同） | `COSINE` / `L2` / `L1` / `DOT`（负内积） / `SQUARED_L2` | **无（检索不可用）** |
-| 非法取值 | 忽略 | 抛 `ValueError` | `search_vectors` 一律抛 `NotImplementedError` |
-| `distance` 口径 | int8 量化整数距离（= L2 × 255，非物理距离） | 真实距离 | — |
-| 维度约束 | 无 | 强制（不匹配即报错） | 上限约束（超限报错） |
-| `filter_sql` 与 `top_k` | **先取 top_k 再过滤**（可能少于 top_k） | **先过滤再取 top_k** | 不适用 |
-| 索引 | 每次检索 `vector_init` + `vector_quantize` | 默认无索引（可自建 hnsw/ivfflat） | 无法建（B-Tree 拒绝向量列） |
+| 支持的 `distance_type` | **仅 L2** | `COSINE` / `L2` / `L1` / `DOT`（负内积） / `SQUARED_L2` | **无（检索不可用）** |
+| 默认 `distance_type` | `"L2"` | `"L2"`（三库统一，不按后端覆写） | `"L2"`（形参保留，调用即抛错） |
+| 非法取值 | 抛 `ValueError` | 抛 `ValueError` | `search_vectors` 抛 `VectorNotSupportedError` |
+| `distance` 口径 | `exact=True` 真值 L2 / `exact=False` 量化（×255） | 真实距离 | — |
+| 维度约束 | `CHECK`（仅新表；旧表靠方法内校验） | 强制（不匹配即报错；建表时回读比对） | 上限约束（超限报错） |
+| `filter_sql` 与 `top_k` | **先过滤再取 top_k**（与 PG 一致） | **先过滤再取 top_k** | 不适用 |
+| 索引 | 无（精确路径为全表扫描） | kit 不建索引；**自建后须 `exact=False` 才会被使用** | 无法建（B-Tree 拒绝向量列） |
 
 > MySQL `DISTANCE()` / `VECTOR_DISTANCE()` 仅 HeatWave on OCI 与 MySQL AI 提供
 > （Community 实测报 `1305 FUNCTION ... does not exist`）；故 `MySqlKit` 只覆盖存储侧。
@@ -368,24 +382,53 @@ with SQLiteKit.transaction() as session:                  # 多操作原子提
 多实例部署需各自 `CommonKit.configure(datacenter_id, machine_id)`（默认 `(1,1)` 会重复）。
 
 ```python
-# SQLite
+# SQLite（默认精确：distance 为真值 L2）
 from kit.db.sqlite_kit import SQLiteKit
-SQLiteKit.create_vector_table("images", dims=384)
+SQLiteKit.create_vector_table("images", 384)          # dims 必填
 SQLiteKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
 rows = SQLiteKit.search_vectors("images", [0.1] * 384, top_k=5)
+rows = SQLiteKit.search_vectors("images", [0.1] * 384, top_k=5, exact=False)  # 旧量化口径（不提速）
 
 # PostgreSQL（签名相同；可选 COSINE/L2/L1/DOT/SQUARED_L2）
 from kit.db.pg_kit import PgKit
-PgKit.create_vector_table("images", dims=384)
+PgKit.create_vector_table("images", 384)
 PgKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
-rows = PgKit.search_vectors("images", [0.1] * 384, top_k=5, distance_type="L2")
+rows = PgKit.search_vectors("images", [0.1] * 384, top_k=5, distance_type="COSINE")
+# 大表 + 自建索引时才用 exact=False（否则索引不被使用，见上表）
+PgKit.execute("CREATE INDEX ON images USING hnsw (embedding vector_cosine_ops)")
+rows = PgKit.search_vectors("images", [0.1] * 384, top_k=5,
+                            distance_type="COSINE", exact=False)
 
-# MySQL（仅存储；search_vectors 会抛 NotImplementedError）
+# MySQL（仅存储；search_vectors 抛 VectorNotSupportedError）
 from kit.db.mysql_kit import MySqlKit
-MySqlKit.create_vector_table("images", dims=384)
+MySqlKit.create_vector_table("images", 384)
 MySqlKit.insert_vectors("images", [[0.1] * 384, [0.2] * 384])
+
+# 能力自省（无需 try/except）
+PgKit.VECTOR_CAPABILITIES
+# {'store': True, 'search': True, 'exact': True,
+#  'distances': ('COSINE', 'L2', 'L1', 'DOT', 'SQUARED_L2'),
+#  'distance_kind': 'true', 'fast_distance_kind': 'true'}
+
+# 自建 DDL 的表：用 id_col / column 接入
+PgKit.execute("CREATE TABLE my_vec (vid BIGINT PRIMARY KEY, vec vector(384))")
+PgKit.insert_vectors("my_vec", [[0.1] * 384], ids=[1], id_col="vid", column="vec")
+PgKit.search_vectors("my_vec", [0.1] * 384, top_k=5, id_col="vid", column="vec")
 ```
 
+#### 0.2.2 行为变更（升级须知）
+
+| 编号 | 变更 | 影响 |
+|------|------|------|
+| B1 | `search_vectors` 新增 `exact: bool = True`，默认**精确** | SQLite 返回的 `distance` 由量化值（≈L2×255）变为**真值 L2**；需旧口径请显式 `exact=False` |
+| B2 | `filter_sql` 语义统一为**先过滤、再取 top_k** | 传 `filter_sql` 的调用返回值**变多/变全**（旧结果 ⊆ 新结果）；曾自行放大 `top_k` 兜底的调用可收紧 |
+| B3 | 默认 `distance_type` 由 `"COSINE"` 改为 `"L2"` | 依赖默认值的调用方请显式传 `distance_type="COSINE"` |
+| B4 | `create_vector_table` 的 `dims` **必填**，参数顺序为 `(table_name, dims, id_col, column, extra_cols)` | `create_vector_table("t")` 类调用需补维度；位置传 `id_col` 的调用改为关键字 |
+| B5 | MySQL 的 `search_vectors` 异常由 `NotImplementedError` 改为 `VectorNotSupportedError`（继承 `DBError`） | `except NotImplementedError` 需改为 `except VectorNotSupportedError`（或 `except DBError`） |
+
+> 新增（非破坏性）：`VECTOR_CAPABILITIES` 能力声明、`id_col` / `column` 逃生口参数、
+> `insert_vectors` 支持二维 numpy 数组与批量提交。
+
 ### 3. CRUDBase（配合 session_scope，不自动提交）
 
 ```python

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

@@ -23,7 +23,7 @@ Author: Clark Chang
 数据库访问通过 kit.db 子包提供（基于 SQLModel）。
 """
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"
 
 from kit.db import (
     MYSQL,

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

@@ -41,7 +41,7 @@ from kit.db.engine import (
     list_tables,
     table_exists,
 )
-from kit.db.exceptions import DBError, NotFoundError
+from kit.db.exceptions import DBError, NotFoundError, VectorNotSupportedError
 from kit.db.session import get_session, session_scope
 from kit.db.transaction import transactional
 
@@ -63,6 +63,7 @@ __all__ = [
     # 异常
     "DBError",
     "NotFoundError",
+    "VectorNotSupportedError",
     # CRUD
     "CRUDBase",
     # 事务

{sdpy_kit-0.2.1 → sdpy_kit-0.2.2}/kit/db/base_db_kit.py

@@ -70,6 +70,11 @@ logger = get_default_logger(__name__)
 # 字段数据：列名到值的映射（object 覆盖全部 SQLModel 支持类型）
 type FieldData = dict[str, object]
 
+# 向量检索的默认距离类型：三库能力集的交集（SQLite 仅支持 L2），
+# 由三个数据库 Kit 的 search_vectors 共用，避免各 Kit 默认值漂移。
+# 默认值不得按后端覆写——否则同一份代码换 import 后会在静默中改变度量语义。
+DEFAULT_DISTANCE_TYPE = "L2"
+
 # CRUD 实例缓存：CRUDBase 无状态（仅存 model），按 model 复用避免重复实例化
 # 值类型取宽基类 SQLModel，规避 PEP 695 类型参数上界约束
 _crud_cache: dict[type, CRUDBase[SQLModel, SQLModel, SQLModel]] = {}
@@ -98,6 +103,26 @@ def to_vector_literal(vector: builtins.list[float]) -> str:
     return "[" + ",".join(repr(float(value)) for value in vector) + "]"
 
 
+def vector_insert_placeholders(
+    columns: builtins.list[str], id_col: str, column: str
+) -> str:
+    """生成向量表 INSERT 的占位符串（供三个数据库 Kit 的 insert_vectors 共用）
+
+    绑定参数名与列名**解耦**：id 列固定为 ``:id``、向量列固定为 ``:vec``、
+    其余列用 ``:列名``。这样调用方覆写 ``id_col`` / ``column``（自建 DDL 场景）时，
+    参数字典的键不受列名影响。
+    """
+
+    def _one(name: str) -> str:
+        if name == column:
+            return ":vec"
+        if name == id_col:
+            return ":id"
+        return f":{name}"
+
+    return ", ".join(_one(name) for name in columns)
+
+
 def generate_snowflake_ids(count: int) -> builtins.list[int]:
     """生成 count 个雪花 ID（int64；当前 18 位，上限 19 位）
 

{sdpy_kit-0.2.1 → sdpy_kit-0.2.2}/kit/db/engine.py

@@ -22,6 +22,10 @@ Author: Clark Chang
 
 支持 PostgreSQL、MySQL、SQLite 三种数据库。
 使用 threading.Lock 保护 _engines 字典，避免 TOCTOU 竞态。
+
+`build_pg_url` / `build_mysql_url` / `build_sqlite_url` 为**公开**的连接串构造器：
+除本模块创建引擎外，测试与外部工具（如迁移脚本）也应复用它们，避免各自手抄导致取值漂移
+（历史问题：`tests/db/conftest.py` 曾手抄 MySQL 串，漏了 `MYSQL_USER` 覆盖）。
 """
 
 import threading
@@ -46,8 +50,11 @@ _engines: dict[str, Engine] = {}
 _lock = threading.Lock()
 
 
-def _build_pg_url(settings: Settings) -> str:
-    """构建 PostgreSQL 连接字符串"""
+def build_pg_url(settings: Settings) -> str:
+    """构建 PostgreSQL 连接字符串
+
+    取值全部来自 `DB_*` 配置（密码经 `quote_plus` 转义）。
+    """
     password = urllib.parse.quote_plus(settings.DB_PASSWORD)
     return (
         f"postgresql://{settings.DB_USER}:{password}"
@@ -56,10 +63,10 @@ def _build_pg_url(settings: Settings) -> str:
     )
 
 
-def _build_mysql_url(settings: Settings) -> str:
+def build_mysql_url(settings: Settings) -> str:
     """构建 MySQL 连接字符串
 
-    MySQL 端口/用户/库名通过 MYSQL_* 覆盖，密码共用 DB_PASSWORD。
+    端口 / 用户 / 库名 / 字符集通过 `MYSQL_*` 覆盖，主机与密码共用 `DB_HOST` / `DB_PASSWORD`。
     """
     password = urllib.parse.quote_plus(settings.DB_PASSWORD)
     port = getattr(settings, "MYSQL_PORT", settings.DB_PORT)
@@ -73,7 +80,7 @@ def _build_mysql_url(settings: Settings) -> str:
     )
 
 
-def _build_sqlite_url(settings: Settings) -> str:
+def build_sqlite_url(settings: Settings) -> str:
     """构建 SQLite 连接字符串"""
     db_path = getattr(settings, "SQLITE_DB_PATH", "./data/sqlite.db")
     return f"sqlite:///{db_path}"
@@ -115,11 +122,11 @@ def _create_engine(db_type: str, **kwargs: object) -> Engine:
     settings = get_settings()
 
     if db_type == POSTGRESQL:
-        url = _build_pg_url(settings)
+        url = build_pg_url(settings)
     elif db_type == MYSQL:
-        url = _build_mysql_url(settings)
+        url = build_mysql_url(settings)
     elif db_type == SQLITE:
-        url = _build_sqlite_url(settings)
+        url = build_sqlite_url(settings)
     else:
         raise ValueError(f"不支持的数据库类型: {db_type}")
 

{sdpy_kit-0.2.1 → sdpy_kit-0.2.2}/kit/db/exceptions.py

@@ -32,3 +32,14 @@ class DBError(SQLAlchemyError):
 
 class NotFoundError(DBError):
     """记录不存在"""
+
+
+class VectorNotSupportedError(DBError):
+    """当前后端不支持所请求的向量能力
+
+    用于语义上"该后端没有这条能力路径"的场景（区别于"执行失败"）。典型用法：
+    ``MySqlKit.search_vectors`` 在 MySQL Community / Commercial 发行版上恒定抛出本异常
+    （未提供 `DISTANCE()` 距离函数，且 `VECTOR` 列无法建立索引）。
+
+    仅继承 :class:`DBError`，遵循项目「异常 ``*Error`` 继承 ``DBError``」的统一错误面约定。
+    """