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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.2.4
+Version: 0.2.6
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/MCP/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -18,38 +18,38 @@ 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: pydantic>=2.14.1
 Requires-Dist: sqlalchemy~=2.0.54
-Requires-Dist: sqlmodel>=0.0.46
+Requires-Dist: sqlmodel>=0.0.48
 Provides-Extra: ai
 Requires-Dist: httpx>=0.28.1; extra == 'ai'
-Requires-Dist: python-dotenv>=1.2.3; 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.0.5; 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.3; extra == 'all'
-Requires-Dist: pikepdf>=10.13.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.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.13.0; 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.0.5; 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'
@@ -62,7 +62,7 @@ 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: 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'
@@ -362,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` | 按单列等值取首行 |
@@ -511,6 +512,25 @@ 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.6 变更
+
+| 编号 | 变更 | 影响 |
+|------|------|------|
+| D1 | `prepare_statement` 的 `params` 支持**参数行列表**（`list[dict]`）：**原样返回该列表** → `session.execute(*prepare_statement(sql, params))` 即批量执行（executemany），与 `build_insert_vectors` 的返回形态直接对接；行键集不一致或行值含序列 → 本地可操作 `ValueError`（与 `execute` 批量形态**同一规则**） | 向后兼容：单字典 / `None` 形态行为不变；行列表形态**不做** `IN` 展开（与批量互斥） |
+| D1 | 文档：修正「自有事务」示例——0.2.5 的示例把 `build_insert_vectors` 返回的**行列表**传给了单字典形态，照抄会抛 `AttributeError: 'list' object has no attribute 'items'` | **纯文档缺陷修正**（0.2.5 示例照抄即崩） |
+| — | 文档：批量执行补充 `rowcount` 备注——忽略型写入（如 SQLite `INSERT OR IGNORE`）的冲突行不计入 `rowcount`（即 `rowcount` = 实际插入数；⚠ 仅 SQLite 实测） | 文档 |
+
+#### 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 变更
 
 | 编号 | 变更 | 影响 |
@@ -541,15 +561,16 @@ rows = SQLiteKit.query("SELECT id, title FROM items WHERE id IN :ids",
 **自有事务内写向量（推荐：`build_insert_vectors` + `transaction()`）**：
 
 ```python
-from sqlalchemy import text
+from kit.db import SQLiteKit, prepare_statement   # 无须 import sqlalchemy
 
 with SQLiteKit.transaction() as session:          # 换成 PgKit / MySqlKit 写法相同
-    session.execute(text("INSERT INTO docs_item (id, title) VALUES (:id, :t)"),
-                    {"id": doc_id, "t": title})
+    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(text(sql), params)
+        session.execute(*prepare_statement(sql, params))
 # 正常退出统一提交；异常自动回滚（多处写入保持同一事务）
 ```
 

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

@@ -292,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` | 按单列等值取首行 |
@@ -441,6 +442,25 @@ 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.6 变更
+
+| 编号 | 变更 | 影响 |
+|------|------|------|
+| D1 | `prepare_statement` 的 `params` 支持**参数行列表**（`list[dict]`）：**原样返回该列表** → `session.execute(*prepare_statement(sql, params))` 即批量执行（executemany），与 `build_insert_vectors` 的返回形态直接对接；行键集不一致或行值含序列 → 本地可操作 `ValueError`（与 `execute` 批量形态**同一规则**） | 向后兼容：单字典 / `None` 形态行为不变；行列表形态**不做** `IN` 展开（与批量互斥） |
+| D1 | 文档：修正「自有事务」示例——0.2.5 的示例把 `build_insert_vectors` 返回的**行列表**传给了单字典形态，照抄会抛 `AttributeError: 'list' object has no attribute 'items'` | **纯文档缺陷修正**（0.2.5 示例照抄即崩） |
+| — | 文档：批量执行补充 `rowcount` 备注——忽略型写入（如 SQLite `INSERT OR IGNORE`）的冲突行不计入 `rowcount`（即 `rowcount` = 实际插入数；⚠ 仅 SQLite 实测） | 文档 |
+
+#### 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 变更
 
 | 编号 | 变更 | 影响 |
@@ -471,15 +491,16 @@ rows = SQLiteKit.query("SELECT id, title FROM items WHERE id IN :ids",
 **自有事务内写向量（推荐：`build_insert_vectors` + `transaction()`）**：
 
 ```python
-from sqlalchemy import text
+from kit.db import SQLiteKit, prepare_statement   # 无须 import sqlalchemy
 
 with SQLiteKit.transaction() as session:          # 换成 PgKit / MySqlKit 写法相同
-    session.execute(text("INSERT INTO docs_item (id, title) VALUES (:id, :t)"),
-                    {"id": doc_id, "t": title})
+    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(text(sql), params)
+        session.execute(*prepare_statement(sql, params))
 # 正常退出统一提交；异常自动回滚（多处写入保持同一事务）
 ```
 

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

@@ -23,7 +23,7 @@ Author: Clark Chang
 数据库访问通过 kit.db 子包提供（基于 SQLModel）。
 """
 
-__version__ = "0.2.4"
+__version__ = "0.2.6"
 
 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.4 → sdpy_kit-0.2.6}/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",

{sdpy_kit-0.2.4 → sdpy_kit-0.2.6}/kit/db/base_db_kit.py

@@ -201,24 +201,79 @@ def generate_snowflake_ids(count: int) -> builtins.list[int]:
 _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`` 与顺序无关，故归一化不改变语义。
+def prepare_statement(
+    sql: str, params: FieldData | builtins.list[FieldData] | None = None
+) -> tuple[TextClause, FieldData | builtins.list[FieldData] | None]:
+    """把 SQL 文本 + 参数转为（可直接执行的语句, 参数）
+
+    供调用方在**自有事务**（`*Kit.transaction()`）内执行原生 SQL，
+    与 ``query`` / ``execute`` 使用**同一套参数规则**（单一事实源）——
+    单字典形态下后两者等价于 ``session.execute(*prepare_statement(sql, params))``；
+    本函数**不建连接、不改状态、不执行**。
+
+    两种参数形态（与 ``execute`` 对称）：
+
+    - **单字典**：值为 ``list`` / ``tuple`` / ``set`` / ``frozenset`` 的键按
+      SQLAlchemy **expanding** 语义绑定，可直接书写 ``WHERE id IN :ids``
+      （三库通用）；第二项为归一化后的参数字典；
+    - **字典列表**（批量 / executemany）：第二项**原样返回该列表**，语句为
+      裸 ``text(sql)``（**不做** ``IN`` 展开——批量与展开参数互斥，与
+      ``execute`` 的批量约束一致）；经 ``_validate_batch_rows`` 本地预校验
+      （各行键集一致、行值为标量）。
+
+    典型用法（调用方**无须 import sqlalchemy**）::
+
+        from kit.db import SQLiteKit, prepare_statement
+
+        stmt, bound = prepare_statement(
+            "DELETE FROM t WHERE id IN :ids", {"ids": [1, 2, 3]}
+        )
+        with SQLiteKit.transaction() as session:
+            session.execute(stmt, bound)          # 第二个值必须一并传入
+
+        stmt, rows = prepare_statement(           # 批量（executemany）
+            "INSERT INTO t (a, b) VALUES (:a, :b)", [{"a": 1, "b": 2}]
+        )
+        with SQLiteKit.transaction() as session:
+            session.execute(stmt, rows)
+
+    三条实现约束（**单字典形态**，与 ``query`` / ``execute`` 现有语义完全一致）：
+
+    1. 只对**确实出现在 SQL 文本中**的参数名做 expanding —— 否则传入"未使用的
+       序列参数"会触发 SQLAlchemy 的 ``ArgumentError: This text() construct
+       doesn't define a bound parameter …``，该报错对使用方没有意义；
+    2. 按类型白名单判断（见 `_EXPANDING_TYPES`），字符串不会被当作列表；
+    3. ``set`` / ``frozenset`` 归一化为 ``list`` —— SQLAlchemy 的 expanding 只接受
+       **可下标序列**（直接传 set 会抛 ``TypeError: 'set' object is not
+       subscriptable``）；``IN`` 与顺序无关，故归一化不改变语义。
+
+    Args:
+        sql: SQL 语句（使用命名参数 ``:param``）
+        params: **单个参数字典**（值为 ``list`` / ``tuple`` / ``set`` / ``frozenset``
+            的键按 ``IN`` 展开，三库通用）或**参数字典的列表**（批量，行值须为标量）
+
+    Returns:
+        ``(语句, 参数)``：执行时**必须**把第二个值一并传给 ``session.execute``；
+        ``params`` 为 None 时第二项即 None，为列表时**原样返回该列表**
+
+    Note:
+        ``:name::type`` 这类 PostgreSQL 风格 cast **不被 SQLAlchemy 的 ``text()``
+        识别**（该写法在支持本函数之前同样不可用），请改用 ``CAST(:name AS type)``。
+
+    Raises:
+        ValueError: 列表形态的行键集不一致或行值含序列类型（来自
+            ``_validate_batch_rows``，与 ``execute`` 批量形态同一规则）
+
+    See Also:
+        ``query`` / ``execute``：kit 自管事务的原生 SQL 入口（同样支持列表参数）。
     """
+    if isinstance(params, builtins.list):
+        # 批量形态：语句不做 IN 展开，参数行列表原样返回（由 execute/session
+        # 以 executemany 执行）；空列表不校验、不报错（构造期无副作用）
+        if params:
+            _validate_batch_rows(params)
+        return text(sql), params
+
     statement = text(sql)
     if not params:
         return statement, params
@@ -230,6 +285,7 @@ def _prepare_statement(
             if isinstance(value, (set, frozenset)):
                 value = list(value)
             normalized[name] = value
+            # 约束 1：只对确实出现在 SQL 文本中的参数名做 expanding
             if re.search(rf":{re.escape(name)}\b", sql):
                 expanding.append(bindparam(name, expanding=True))
         else:
@@ -240,6 +296,46 @@ def _prepare_statement(
     return statement, normalized
 
 
+def _validate_batch_rows(rows: builtins.list[FieldData]) -> None:
+    """批量执行（executemany）的本地预校验：键集一致 + 不含序列参数
+
+    约束来自 DBAPI 的 executemany 语义（实测）：
+
+    1. 各行字典的**键集必须完全一致** —— 否则 SQLAlchemy 报
+       ``StatementError: A value is required for bind parameter 'xxx'``，
+       不指明是哪一行，对使用方没有意义；
+    2. 行值须为**标量** —— 批量与 ``IN`` 展开（expanding）**互斥**：对批量语句
+       做 expanding 标注后按行执行会得到 ``OperationalError: near "?": syntax error``
+       这类驱动级错误（三库通用行为）。
+
+    在本地提前给出**可操作的** ``ValueError``（含行号与差异明细），
+    避免把上述两类无意义报错暴露给使用方。
+
+    Args:
+        rows: 批量参数（非空）
+
+    Raises:
+        ValueError: 键集不一致，或行值中含序列类型
+    """
+    base = set(rows[0])
+    for index, row in enumerate(rows):
+        keys = set(row)
+        if keys != base:
+            raise ValueError(
+                f"批量参数第 {index} 行的键集与第 0 行不一致："
+                f"缺少 {sorted(base - keys)}，多出 {sorted(keys - base)}；"
+                f"executemany 要求各行键集完全一致"
+            )
+        for name, value in row.items():
+            if isinstance(value, _EXPANDING_TYPES):
+                raise ValueError(
+                    f"批量参数第 {index} 行的 {name!r} 是序列类型："
+                    f"批量执行（executemany）与 IN 展开（expanding）互斥；"
+                    f"如需 IN 语义请改用单个参数字典（execute 的单字典形态），"
+                    f"或逐行调用 execute"
+                )
+
+
 class BaseDbKit(ABC):
     """数据库工具类共享基类
 
@@ -606,7 +702,7 @@ class BaseDbKit(ABC):
             ``IN`` **不保证返回顺序**，需要顺序请自行按 id 重排；参数列表过大时
             （如 PG 单语句参数上限 65535）应分批查询。
         """
-        statement, bound = _prepare_statement(sql, params)
+        statement, bound = prepare_statement(sql, params)
         with session_scope(cls.DB_TYPE, autocommit=False) as session:
             result = session.execute(statement, bound or {})
             rows = result.fetchall()
@@ -616,24 +712,66 @@ class BaseDbKit(ABC):
             return data
 
     @classmethod
-    def execute(cls, sql: str, params: FieldData | None = None) -> int:
-        """执行原生更新 SQL（INSERT/UPDATE/DELETE）
+    def execute(
+        cls, sql: str, params: FieldData | builtins.list[FieldData] | None = None
+    ) -> int:
+        """执行原生更新 SQL（INSERT/UPDATE/DELETE），支持批量（executemany）
 
         Args:
-            sql: SQL 语句（使用命名参数 :param）
-            params: 参数字典。值为 list / tuple / set / frozenset 的参数按 ``IN`` 展开
-                （如 ``DELETE FROM t WHERE id IN :ids``，三库通用）
+            sql: SQL 语句（使用命名参数 ``:param``）
+            params: 两种形态：
+
+                - **None / 单个参数字典**：执行一次；值为 ``list`` / ``tuple`` /
+                  ``set`` / ``frozenset`` 的参数按 ``IN`` 展开
+                  （如 ``DELETE FROM t WHERE id IN :ids``，三库通用）；
+                - **参数字典的列表**：批量执行（executemany，同一语句 + N 行参数，
+                  一次往返）。⚠ 与 ``IN`` 展开**互斥**（行值须为标量），
+                  各行字典的**键集必须完全一致**，**空列表**不触库直接返回 0。
 
         Returns:
-            受影响的行数
+            受影响的行数（批量形态为各行累加；部分驱动对 executemany 不上报
+            精确行数时可能为 ``-1``，请以数据为准）
+
+        Raises:
+            ValueError: 批量形态的行参数键集不一致，或行值中含序列类型
+                （批量与 ``IN`` 展开互斥）
         """
-        statement, bound = _prepare_statement(sql, params)
+        if isinstance(params, builtins.list):
+            return cls._execute_batch(sql, params)
+        statement, bound = prepare_statement(sql, params)
         with session_scope(cls.DB_TYPE) as session:
             result = session.execute(statement, bound or {})
             affected = getattr(result, "rowcount", 0) or 0
             logger.info(f"✅ 执行更新 → 影响 {affected} 行")
             return affected
 
+    @classmethod
+    def _execute_batch(cls, sql: str, rows: builtins.list[FieldData]) -> int:
+        """批量执行（executemany）：先本地预校验，再一次往返执行 N 行参数
+
+        私有方法（不属于公共面）：仅 ``execute`` 的列表形态会进入。
+
+        Args:
+            sql: SQL 语句（使用命名参数 ``:param``；**不传** ``params`` 构造语句，
+                即不做 ``IN`` 展开——批量与展开参数互斥）
+            rows: 参数字典列表（非空；键集一致；值须为标量）
+
+        Returns:
+            受影响的行数（各行累加；驱动不上报时为 ``-1``）
+        """
+        if not rows:
+            # 空列表语义：不触库、不报错，直接返回 0（DBAPI 对 executemany
+            # 传空列表会报 "A value is required for bind parameter"）
+            logger.info("批量执行收到空参数列表 → 不执行任何语句")
+            return 0
+        _validate_batch_rows(rows)
+        statement, _ = prepare_statement(sql)
+        with session_scope(cls.DB_TYPE) as session:
+            result = session.execute(statement, rows)
+            affected = getattr(result, "rowcount", 0) or 0
+            logger.info(f"✅ 批量执行 → {len(rows)} 行参数，影响 {affected} 行")
+            return affected
+
     # ==================== 原生表操作 ====================
 
     @classmethod

{sdpy_kit-0.2.4 → sdpy_kit-0.2.6}/pyproject.toml

@@ -31,10 +31,10 @@ classifiers = [
 # base + extras 须与主工程 pyproject.toml 的 dependencies 保持一致（双向锚定），
 # publish.py --check-only 会自动校验，主工程缺失即报错。
 dependencies = [
-    "pydantic>=2.13.5",
+    "pydantic>=2.14.1",
     "pydantic-settings>=2.15.0",
     "sqlalchemy~=2.0.54",
-    "sqlmodel>=0.0.46",
+    "sqlmodel>=0.0.48",
 ]
 dynamic = ["version"]
 
@@ -57,15 +57,15 @@ dynamic = ["version"]
 pg = ["psycopg2-binary>=2.9.13"]
 mysql = ["pymysql>=1.2.3"]
 sqliteai = [
-    "numpy>=2.5.3",
+    "numpy>=2.5.4",
     "sqliteai-vector>=1.1.2",
 ]
 zvec = ["zvec>=0.7.0"]
 redis = ["redis>=8.1.0"]
-mcp = ["fastmcp>=4.0.5"]
+mcp = ["fastmcp>=4.1.0"]
 ai = [
     "httpx>=0.28.1",
-    "python-dotenv>=1.2.3",
+    "python-dotenv>=1.2.4",
 ]
 md2doc = [
     "pimd[pdfa]>=2.2.5",
@@ -73,7 +73,7 @@ md2doc = [
 ]
 anydoc = [
     "firecrawl-anydoc>=0.2.4",
-    "pikepdf>=10.13.0",
+    "pikepdf>=10.17.0",
 ]
 docx = ["docxtpl>=0.20.2"]
 mineru = ["requests>=2.34.2"]
@@ -81,17 +81,17 @@ marker = ["marker-pdf[full]>=2.0.0"]
 all = [
     "psycopg2-binary>=2.9.13",
     "pymysql>=1.2.3",
-    "numpy>=2.5.3",
+    "numpy>=2.5.4",
     "sqliteai-vector>=1.1.2",
     "zvec>=0.7.0",
     "redis>=8.1.0",
-    "fastmcp>=4.0.5",
+    "fastmcp>=4.1.0",
     "httpx>=0.28.1",
-    "python-dotenv>=1.2.3",
+    "python-dotenv>=1.2.4",
     "pimd[pdfa]>=2.2.5",
     "markdown-it-py>=4.2.0",
     "firecrawl-anydoc>=0.2.4",
-    "pikepdf>=10.13.0",
+    "pikepdf>=10.17.0",
     "docxtpl>=0.20.2",
     "requests>=2.34.2",
     "marker-pdf[full]>=2.0.0",