sdpy-kit 0.6.0__tar.gz → 0.6.1__tar.gz

{sdpy_kit-0.6.0 → sdpy_kit-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.6.0
+Version: 0.6.1
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
@@ -662,6 +662,8 @@ AuditConfig.set_fields(None)  # 恢复默认
 
 约定与局限：
 
+- `set_fields` 的列名必须是合法标识符（字母 / 数字 / 下划线，不以数字开头），
+  否则立即 `ValueError`——列名会被拼进 SQL 的标识符位置。
 - `deleted` 支持整数列（填 `0`）与字符串列（填 `"0"`，`VARCHAR` / `CHAR` / `TEXT`）；
   **boolean 列不支持**（会报类型错误）。
 - 查询过滤严格等值 `deleted = 0`（字符串列 `"0"`）；`NULL` **不**视为未删除，历史数据需自行回填。

{sdpy_kit-0.6.0 → sdpy_kit-0.6.1}/README.md

@@ -586,6 +586,8 @@ AuditConfig.set_fields(None)  # 恢复默认
 
 约定与局限：
 
+- `set_fields` 的列名必须是合法标识符（字母 / 数字 / 下划线，不以数字开头），
+  否则立即 `ValueError`——列名会被拼进 SQL 的标识符位置。
 - `deleted` 支持整数列（填 `0`）与字符串列（填 `"0"`，`VARCHAR` / `CHAR` / `TEXT`）；
   **boolean 列不支持**（会报类型错误）。
 - 查询过滤严格等值 `deleted = 0`（字符串列 `"0"`）；`NULL` **不**视为未删除，历史数据需自行回填。

{sdpy_kit-0.6.0 → sdpy_kit-0.6.1}/kit/__init__.py

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

{sdpy_kit-0.6.0 → sdpy_kit-0.6.1}/kit/db/audit.py

@@ -68,6 +68,7 @@ UPDATE    不参与        空才填                   不参与
     AuditConfig.enable(user_resolver=get_current_userid)  # 应用启动时调用一次
 """
 
+import re
 import threading
 from collections.abc import Callable, Generator, Mapping, MutableMapping
 from contextlib import contextmanager
@@ -132,6 +133,23 @@ def _is_empty(value: object) -> bool:
     return isinstance(value, str) and not value.strip()
 
 
+# 列名会被拼进 SQL 的标识符位置（`SET name = :name` / `INSERT ... (name)`），
+# 故配置入口必须与 raw_* 的 data 键同一套白名单，避免手误到写入时才报晦涩错误。
+_IDENT_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def _check_field_name(name: object) -> None:
+    """校验配置的列名是合法标识符（拼接进 SQL 前拦截）
+
+    Raises:
+        ValueError: 非字符串 / 空串 / 含字母、数字、下划线以外的字符 / 以数字开头
+    """
+    if not isinstance(name, str) or not _IDENT_RE.match(name):
+        raise ValueError(
+            f"{name!r} 不是合法列名（仅允许字母、数字、下划线，且不能以数字开头）"
+        )
+
+
 def _is_string_type(column_type: TypeEngine[Any]) -> bool:
     """是否为字符串列（兼容 SQLModel 的 ``AutoString`` 这类 ``TypeDecorator``）
 
@@ -238,7 +256,8 @@ class AuditConfig:
                 ``deleted``
 
         Raises:
-            ValueError: 出现未知槽位（防手误，例如把 ``created_at`` 写成 ``create_at``）
+            ValueError: 出现未知槽位（防手误，例如把 ``created_at`` 写成 ``create_at``）；
+                或列名不是合法标识符（会被拼进 SQL 的标识符位置）
 
         用法::
 
@@ -254,6 +273,8 @@ class AuditConfig:
                     f"未知的字段槽位: {sorted(unknown)}；"
                     f"可用槽位: {sorted(DEFAULT_FIELDS)}"
                 )
+            for name in fields.values():
+                _check_field_name(name)
             merged.update(fields)
         with cls._lock:
             cls._fields = merged
@@ -365,6 +386,14 @@ def _candidates(slot: str) -> tuple[str, ...]:
     return (primary, *(alias for alias in aliases if alias != primary))
 
 
+def candidate_columns(slot: str) -> tuple[str, ...]:
+    """槽位的候选列名（当前配置名 + 内置别名），供错误消息与诊断使用
+
+    ⚠ 内部符号（不进 ``kit.db.__all__``）。
+    """
+    return _candidates(slot)
+
+
 def insert_only_columns() -> tuple[str, ...]:
     """只在 INSERT 填充的列（created_at / created_by 槽位的**全部候选**）
 

{sdpy_kit-0.6.0 → sdpy_kit-0.6.1}/kit/db/base_db_kit.py

@@ -58,7 +58,9 @@ from sqlmodel import Session, SQLModel
 from kit.common_kit import CommonKit
 from kit.config.log_config import get_default_logger
 from kit.db.audit import (
+    UPDATED_AT,
     AuditConfig,
+    candidate_columns,
     deleted_predicate,
     fill_insert_for,
     fill_update,
@@ -195,7 +197,15 @@ def _adapt_write_values(
             data[name] = json.dumps(value, ensure_ascii=False)
             continue
         if isinstance(value, _WRITE_SEQUENCE_TYPES):
-            if isinstance(columns.get(name), JSON):
+            column_type = columns.get(name)
+            if column_type is None:
+                raise ValueError(
+                    f"{name!r} 的值是序列，但表 {table_name} 中查不到该列"
+                    f"（或列探测失败）：请确认表已提交建好；"
+                    f"JSON 列请传 dict / list；向量请用 to_vector_literal(...)；"
+                    f"数组等其它类型请用 execute() 手写 SQL"
+                )
+            if isinstance(column_type, JSON):
                 data[name] = json.dumps(list(value), ensure_ascii=False)
             else:
                 raise ValueError(
@@ -1000,8 +1010,9 @@ class BaseDbKit(ABC):
                 "或改用 raw_update 显式给字段"
             )
         if not touch_columns(cls.DB_TYPE, table_name):
+            expected = " / ".join(candidate_columns(UPDATED_AT))
             raise DBError(
-                f"表 {table_name} 没有 updated_at 相关列，无法 touch；"
+                f"表 {table_name} 没有 {expected} 中的任何一列，无法 touch；"
                 f"请改用 raw_update 显式给字段"
             )