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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.2.5
+Version: 0.2.6
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/MCP/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -512,7 +512,15 @@ 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 变更（开发中，未发布）
+#### 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 变更
 
 | 编号 | 变更 | 影响 |
 |------|------|------|

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

@@ -442,7 +442,15 @@ 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 变更（开发中，未发布）
+#### 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 变更
 
 | 编号 | 变更 | 影响 |
 |------|------|------|

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

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

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

@@ -202,14 +202,24 @@ _EXPANDING_TYPES = (list, tuple, set, frozenset)
 
 
 def prepare_statement(
-    sql: str, params: FieldData | None = None
-) -> tuple[TextClause, FieldData | None]:
-    """把 SQL 文本 + 参数字典转为（可直接执行的语句, 归一化后的参数）
+    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))``；本函数**不建连接、
-    不改状态、不执行**。
+    与 ``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**）::
 
@@ -221,7 +231,13 @@ def prepare_statement(
         with SQLiteKit.transaction() as session:
             session.execute(stmt, bound)          # 第二个值必须一并传入
 
-    三条实现约束（与 ``query`` / ``execute`` 现有语义完全一致）：
+        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
@@ -233,20 +249,31 @@ def prepare_statement(
 
     Args:
         sql: SQL 语句（使用命名参数 ``:param``）
-        params: 参数字典，值为 ``list`` / ``tuple`` / ``set`` / ``frozenset`` 的键
-            按 ``IN`` 展开（三库通用）
+        params: **单个参数字典**（值为 ``list`` / ``tuple`` / ``set`` / ``frozenset``
+            的键按 ``IN`` 展开，三库通用）或**参数字典的列表**（批量，行值须为标量）
 
     Returns:
-        ``(语句, 归一化后的参数字典)``：执行时**必须**把第二个值一并传给
-        ``session.execute``；``params`` 为 None 时第二项即 None
+        ``(语句, 参数)``：执行时**必须**把第二个值一并传给 ``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