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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.2.2
+Version: 0.2.3
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/MCP/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -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": "批量一"})
@@ -499,6 +510,38 @@ 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.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 重排
+```
+
+**自有事务内写向量（SQLite）**：
+
+```python
+conn = SQLiteKit.raw_connection()          # DBAPI 连接：位置参数 ? + 手工 commit
+try:
+    conn.execute("INSERT INTO item_vectors (id, embedding) VALUES (?, ?)",
+                 (item_id, SQLiteKit.encode_vector(vec)))
+    conn.commit()
+finally:
+    conn.close()
+```
+
+> 相似度换算建议：SQLite 仅支持 L2，若向量入库前已**归一化**，则 `cos = 1 − L2²/2`；
+> PG 可直接用 `distance_type="COSINE"`。
+
 ### 3. CRUDBase（配合 session_scope，不自动提交）
 
 ```python

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

@@ -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": "批量一"})
@@ -429,6 +440,38 @@ 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.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 重排
+```
+
+**自有事务内写向量（SQLite）**：
+
+```python
+conn = SQLiteKit.raw_connection()          # DBAPI 连接：位置参数 ? + 手工 commit
+try:
+    conn.execute("INSERT INTO item_vectors (id, embedding) VALUES (?, ?)",
+                 (item_id, SQLiteKit.encode_vector(vec)))
+    conn.commit()
+finally:
+    conn.close()
+```
+
+> 相似度换算建议：SQLite 仅支持 L2，若向量入库前已**归一化**，则 `cos = 1 − L2²/2`；
+> PG 可直接用 `distance_type="COSINE"`。
+
 ### 3. CRUDBase（配合 session_scope，不自动提交）
 
 ```python

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

@@ -23,26 +23,37 @@ Author: Clark Chang
 数据库访问通过 kit.db 子包提供（基于 SQLModel）。
 """
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"
 
 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.3}/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",
 ]

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

@@ -43,13 +43,14 @@ create_raw_table / raw_insert / raw_get_by）上移到本基类，使三个 Kit
 """
 
 import builtins
+import re
 import threading
 from abc import ABC, abstractmethod
 from collections.abc import Generator
 from contextlib import contextmanager
 from typing import cast
 
-from sqlalchemy import text
+from sqlalchemy import TextClause, bindparam, text
 from sqlalchemy.pool import PoolProxiedConnection
 from sqlmodel import Session, SQLModel
 
@@ -135,6 +136,50 @@ def generate_snowflake_ids(count: int) -> builtins.list[int]:
     return [CommonKit.generate_snowflake_id() for _ in range(count)]
 
 
+# 可参与 IN 展开的参数类型（按类型白名单判断，绝不用 Iterable：
+# 否则字符串会被逐字符展开）
+_EXPANDING_TYPES = (list, tuple, set, frozenset)
+
+
+def _prepare_statement(
+    sql: str, params: FieldData | None
+) -> tuple[TextClause, FieldData | None]:
+    """把 SQL 文本 + 参数字典转为（可执行语句, 归一化后的参数）
+
+    `params` 中值为**序列类型**（list / tuple / set / frozenset）的键按 SQLAlchemy
+    **expanding** 语义绑定，使 ``WHERE id IN :ids`` 可直接书写（三库通用）。
+
+    三条实现约束：
+
+    1. 按类型白名单判断（见 `_EXPANDING_TYPES`），字符串不会被当作列表；
+    2. 只对**确实出现在 SQL 中**的参数名做 expanding —— 否则传入"未使用的序列参数"
+       会触发 SQLAlchemy 的 ``ArgumentError: This text() construct doesn't define
+       a bound parameter …``，该报错对使用方没有意义；
+    3. `set` / `frozenset` 归一化为 `list` —— SQLAlchemy 的 expanding 只接受
+       **可下标序列**（直接传 set 会抛 ``TypeError: 'set' object is not subscriptable``）；
+       ``IN`` 与顺序无关，故归一化不改变语义。
+    """
+    statement = text(sql)
+    if not params:
+        return statement, params
+
+    normalized: FieldData = {}
+    expanding: list[object] = []
+    for name, value in params.items():
+        if isinstance(value, _EXPANDING_TYPES):
+            if isinstance(value, (set, frozenset)):
+                value = list(value)
+            normalized[name] = value
+            if re.search(rf":{re.escape(name)}\b", sql):
+                expanding.append(bindparam(name, expanding=True))
+        else:
+            normalized[name] = value
+
+    if expanding:
+        statement = statement.bindparams(*expanding)  # type: ignore[arg-type]
+    return statement, normalized
+
+
 class BaseDbKit(ABC):
     """数据库工具类共享基类
 
@@ -385,13 +430,19 @@ class BaseDbKit(ABC):
 
         Args:
             sql: SQL 查询语句（使用命名参数 :param）
-            params: 参数字典
+            params: 参数字典。值为 list / tuple / set / frozenset 的参数按 ``IN`` 展开，
+                可直接书写 ``WHERE id IN :ids``（三库通用）
 
         Returns:
             查询结果列表，每行为一个字典
+
+        Note:
+            ``IN`` **不保证返回顺序**，需要顺序请自行按 id 重排；参数列表过大时
+            （如 PG 单语句参数上限 65535）应分批查询。
         """
+        statement, bound = _prepare_statement(sql, params)
         with session_scope(cls.DB_TYPE, autocommit=False) as session:
-            result = session.execute(text(sql), params or {})
+            result = session.execute(statement, bound or {})
             rows = result.fetchall()
             columns = result.keys()
             data = [dict(zip(columns, row)) for row in rows]
@@ -404,13 +455,15 @@ class BaseDbKit(ABC):
 
         Args:
             sql: SQL 语句（使用命名参数 :param）
-            params: 参数字典
+            params: 参数字典。值为 list / tuple / set / frozenset 的参数按 ``IN`` 展开
+                （如 ``DELETE FROM t WHERE id IN :ids``，三库通用）
 
         Returns:
             受影响的行数
         """
+        statement, bound = _prepare_statement(sql, params)
         with session_scope(cls.DB_TYPE) as session:
-            result = session.execute(text(sql), params or {})
+            result = session.execute(statement, bound or {})
             affected = getattr(result, "rowcount", 0) or 0
             logger.info(f"✅ 执行更新 → 影响 {affected} 行")
             return affected

{sdpy_kit-0.2.2 → sdpy_kit-0.2.3}/kit/db/pg_kit.py

@@ -113,13 +113,22 @@ class PgKit(BaseDbKit):
 
     @classmethod
     def get_table_info(cls, table_name: str) -> list[dict[str, object]]:
-        """获取表的列信息
+        """获取表的列信息（按列序返回）
 
         Args:
-            table_name: 表名
+            table_name: 表名（**非限定名**，如 ``items``）
 
         Returns:
-            列信息字典列表（column_name, data_type, is_nullable, column_default）
+            列信息字典列表，公共键 4 个：``column_name`` / ``data_type`` /
+            ``is_nullable``（``"YES"``/``"NO"``）/ ``column_default``；
+            ``data_type`` 为**后端原生类型名**（不做跨库归一化）
+
+        Note:
+            - 表按 **PostgreSQL 自身的解析规则**定位（``to_regclass``，即 ``search_path``
+              顺序），与 ``SELECT … FROM 表名`` 命中的那张表一致——因此不会因多 schema
+              同名表而返回混行；表不存在时返回空列表。
+            - **只接受非限定表名**：跨 schema 请用 `query()` 显式指定 ``table_schema``。
+            - 与 `list_tables()`（枚举**当前默认 schema**）语义不同，二者非互斥。
         """
         sql = """
         SELECT
@@ -129,6 +138,12 @@ class PgKit(BaseDbKit):
             column_default
         FROM information_schema.columns
         WHERE table_name = :table_name
+          AND table_schema = (
+              SELECT n.nspname
+              FROM pg_class cl
+              JOIN pg_namespace n ON n.oid = cl.relnamespace
+              WHERE cl.oid = to_regclass(:table_name)
+          )
         ORDER BY ordinal_position
         """
         return cls.query(sql, {"table_name": table_name})

{sdpy_kit-0.2.2 → sdpy_kit-0.2.3}/kit/db/sqlite_kit.py

@@ -26,7 +26,8 @@ from __future__ import annotations
 业务代码无需管理 session/transaction，直接调用即可。
 
 本类继承 BaseDbKit，复用全部共享实现（连接管理 / ORM / 原生 SQL / 原生表操作 /
-事务 / 表操作），并额外提供基于 sqlite-vector 扩展的 4 个向量方法。
+事务 / 表操作），并额外提供基于 sqlite-vector 扩展的 4 个向量方法，以及 2 个
+**编码原语**（`encode_vector` / `decode_vector`，仅本后端具备）。
 
 使用方式::
 
@@ -74,6 +75,9 @@ SUPPORTED_DISTANCE_TYPES: tuple[str, ...] = ("L2",)
 # float32 = 4 字节/维：BLOB 长度与维度的换算基准
 BYTES_PER_DIM = 4
 
+# sqlite-vector 的向量表示：**小端** float32（显式指定，不依赖本机字节序）
+_VECTOR_DTYPE = "<f4"
+
 
 class SQLiteKit(BaseDbKit):
     """SQLite 数据库工具类
@@ -120,6 +124,54 @@ class SQLiteKit(BaseDbKit):
 
     # ==================== 向量操作 ====================
 
+    @classmethod
+    def encode_vector(cls, vector: list[float]) -> bytes:
+        """把向量编码为 sqlite-vector 使用的 float32 **小端** BLOB（4 字节/维）
+
+        Args:
+            vector: 一维向量（float 序列，也接受一维 numpy 数组）
+
+        Returns:
+            ``len(vector) * 4`` 字节的 BLOB
+
+        Raises:
+            ValueError: 向量为空，或输入不是一维（二维数组会被静默编成多个向量）
+
+        Note:
+            本方法是**后端专属原语**（文本后端对应 `to_vector_literal`，两者不可互换）：
+            用于调用方在**自有事务/连接**内拼写 INSERT 时编码，例如::
+
+                with SQLiteKit.raw_connection() as conn:
+                    conn.execute(
+                        "INSERT INTO item_vectors (id, embedding) VALUES (?, ?)",
+                        (item_id, SQLiteKit.encode_vector(vec)),
+                    )
+                    conn.commit()
+        """
+        # numpy 仅向量方法需要（vec extra），延迟导入保持基础安装可用
+        import numpy as np
+
+        array = np.asarray(vector, dtype=_VECTOR_DTYPE)
+        if array.size == 0:
+            raise ValueError("vector 不能为空")
+        if array.ndim != 1:
+            raise ValueError(f"encode_vector 只接受一维向量，当前 ndim={array.ndim}")
+        return array.tobytes()
+
+    @classmethod
+    def decode_vector(cls, blob: bytes) -> list[float]:
+        """把 float32 小端 BLOB 解码为 float 列表（便于自检与断言）
+
+        Args:
+            blob: `encode_vector` 产出的字节串（4 的整数倍）
+
+        Returns:
+            float 列表
+        """
+        import numpy as np
+
+        return [float(x) for x in np.frombuffer(blob, dtype=_VECTOR_DTYPE)]
+
     @classmethod
     def create_vector_table(
         cls,
@@ -225,13 +277,11 @@ class SQLiteKit(BaseDbKit):
             )
 
         engine = get_engine(cls.DB_TYPE)
-        # numpy 仅向量方法需要（vec extra），延迟导入保持基础安装可用
-        import numpy as np
 
         # 按「列集合」分组：键集相同的行才能共用同一条批量语句（executemany）
         groups: dict[tuple[str, ...], list[dict[str, object]]] = {}
         for i, vec in enumerate(vectors):
-            vec_bytes = np.array(vec, dtype=np.float32).tobytes()
+            vec_bytes = cls.encode_vector(vec)
             columns: list[str] = [id_col, column]
             params: dict[str, object] = {"id": ids[i], "vec": vec_bytes}
 
@@ -323,10 +373,8 @@ class SQLiteKit(BaseDbKit):
 
         dims = len(query_vector)
         engine = get_engine(cls.DB_TYPE)
-        # numpy 仅向量方法需要（vec extra），延迟导入保持基础安装可用
-        import numpy as np
 
-        query_bytes = np.array(query_vector, dtype=np.float32).tobytes()
+        query_bytes = cls.encode_vector(query_vector)
 
         with engine.connect() as conn:
             # 维度前置校验：把「Invalid vector blob found at rowid N」换成语义明确的错误