sdpy-kit 0.1.0__py3-none-any.whl

kit/db/models/base.py

@@ -0,0 +1,56 @@
+"""
+Copyright (c) 2021-2026 Clark Chang. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+Project: sdpy
+Author: Clark Chang
+"""
+
+# date: 2026-08-23
+"""SQLModel 基础模型混入类
+
+提供 TimestampMixin（时间戳）、SoftDeleteMixin（软删除）、AuditMixin（审计字段）。
+default_factory 统一使用 datetime.now(UTC)，避免废弃的 utcnow()。
+"""
+
+from datetime import UTC, datetime
+from typing import Optional
+
+from sqlmodel import Field, SQLModel
+
+
+def _utcnow() -> datetime:
+    """获取当前 UTC 时间"""
+    return datetime.now(UTC)
+
+
+class TimestampMixin(SQLModel):
+    """时间戳混入：自动添加 created_at 和 updated_at 字段"""
+
+    created_at: datetime = Field(default_factory=_utcnow, nullable=False)
+    updated_at: Optional[datetime] = Field(default=None, nullable=True)
+
+
+class SoftDeleteMixin(SQLModel):
+    """软删除混入：添加 is_deleted 和 deleted_at 字段"""
+
+    is_deleted: bool = Field(default=False, nullable=False)
+    deleted_at: Optional[datetime] = Field(default=None, nullable=True)
+
+
+class AuditMixin(TimestampMixin):
+    """审计混入：在 TimestampMixin 基础上添加操作人字段"""
+
+    created_by: Optional[str] = Field(default=None, max_length=100)
+    updated_by: Optional[str] = Field(default=None, max_length=100)

kit/db/mysql_kit.py

@@ -0,0 +1,89 @@
+"""
+Copyright (c) 2021-2026 Clark Chang. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+Project: sdpy
+Author: Clark Chang
+"""
+
+from __future__ import annotations
+
+# date: 2026-08-22
+"""MySQL 数据库工具类
+
+基于 kit.db 统一数据库层封装，提供开箱即用的服务方法。
+业务代码无需管理 session/transaction，直接调用即可。
+
+本类继承 BaseDbKit，复用全部共享实现（连接管理 / ORM / 原生 SQL / 事务 /
+表操作），仅声明 DB_TYPE 并覆写 MySQL 专属的 get_table_info。
+
+使用方式::
+
+    # 单条操作（自动管理事务）
+    user = MySqlKit.create(UserModel, {"name": "张三", "email": "zs@example.com"})
+    users = MySqlKit.list(UserModel, skip=0, limit=10)
+    MySqlKit.update(UserModel, user.id, {"name": "李四"})
+
+    # 原生 SQL 操作
+    rows = MySqlKit.query("SELECT * FROM users WHERE id = :id", {"id": 1})
+
+    # 多操作事务
+    with MySqlKit.transaction() as session:
+        crud = CRUDBase(UserModel)
+        crud.create(session, {"name": "test"})
+        # 退出 with 时统一提交
+"""
+
+from kit.config.log_config import get_default_logger
+from kit.db.base_db_kit import BaseDbKit
+from kit.db.engine import MYSQL
+
+logger = get_default_logger(__name__)
+
+
+class MySqlKit(BaseDbKit):
+    """MySQL 数据库工具类
+
+    基于 kit.db 统一数据库层，封装为业务可直调的服务方法。
+    所有 ORM 方法内部使用 session_scope 管理事务（自动提交/回滚），
+    业务代码无需手动管理 session。
+
+    对于多操作事务场景，请使用 transaction() 上下文管理器。
+    """
+
+    DB_TYPE = MYSQL
+
+    @classmethod
+    def get_table_info(cls, table_name: str) -> list[dict[str, object]]:
+        """获取表的列信息
+
+        Args:
+            table_name: 表名
+
+        Returns:
+            列信息字典列表（column_name, data_type, is_nullable 等）
+        """
+        sql = """
+        SELECT
+            COLUMN_NAME as column_name,
+            DATA_TYPE as data_type,
+            IS_NULLABLE as is_nullable,
+            COLUMN_DEFAULT as column_default,
+            COLUMN_COMMENT as column_comment
+        FROM INFORMATION_SCHEMA.COLUMNS
+        WHERE TABLE_NAME = :table_name
+        AND TABLE_SCHEMA = DATABASE()
+        ORDER BY ORDINAL_POSITION
+        """
+        return cls.query(sql, {"table_name": table_name})

kit/db/pg_kit.py

@@ -0,0 +1,87 @@
+"""
+Copyright (c) 2021-2026 Clark Chang. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+Project: sdpy
+Author: Clark Chang
+"""
+
+from __future__ import annotations
+
+# date: 2026-08-22
+"""PostgreSQL 数据库工具类
+
+基于 kit.db 统一数据库层封装，提供开箱即用的服务方法。
+业务代码无需管理 session/transaction，直接调用即可。
+
+本类继承 BaseDbKit，复用全部共享实现（连接管理 / ORM / 原生 SQL / 事务 /
+表操作），仅声明 DB_TYPE 并覆写 PostgreSQL 专属的 get_table_info。
+
+使用方式::
+
+    # 单条操作（自动管理事务）
+    user = PgKit.create(UserModel, {"name": "张三", "email": "zs@example.com"})
+    users = PgKit.list(UserModel, skip=0, limit=10)
+    PgKit.update(UserModel, user.id, {"name": "李四"})
+
+    # 原生 SQL 操作
+    rows = PgKit.query("SELECT * FROM users WHERE active = :active", {"active": True})
+
+    # 多操作事务
+    with PgKit.transaction() as session:
+        crud = CRUDBase(UserModel)
+        crud.create(session, {"name": "test"})
+        # 退出 with 时统一提交
+"""
+
+from kit.config.log_config import get_default_logger
+from kit.db.base_db_kit import BaseDbKit
+from kit.db.engine import POSTGRESQL
+
+logger = get_default_logger(__name__)
+
+
+class PgKit(BaseDbKit):
+    """PostgreSQL 数据库工具类
+
+    基于 kit.db 统一数据库层，封装为业务可直调的服务方法。
+    所有 ORM 方法内部使用 session_scope 管理事务（自动提交/回滚），
+    业务代码无需手动管理 session。
+
+    对于多操作事务场景，请使用 transaction() 上下文管理器。
+    """
+
+    DB_TYPE = POSTGRESQL
+
+    @classmethod
+    def get_table_info(cls, table_name: str) -> list[dict[str, object]]:
+        """获取表的列信息
+
+        Args:
+            table_name: 表名
+
+        Returns:
+            列信息字典列表（column_name, data_type, is_nullable, column_default）
+        """
+        sql = """
+        SELECT
+            column_name,
+            data_type,
+            is_nullable,
+            column_default
+        FROM information_schema.columns
+        WHERE table_name = :table_name
+        ORDER BY ordinal_position
+        """
+        return cls.query(sql, {"table_name": table_name})

kit/db/session.py

@@ -0,0 +1,85 @@
+"""
+Copyright (c) 2021-2026 Clark Chang. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+Project: sdpy
+Author: Clark Chang
+"""
+
+# date: 2025-04-19
+"""统一的会话管理模块
+
+提供唯一的会话入口 session_scope，自动管理提交/回滚/关闭。
+CRUD 操作不应在内部调用 commit/rollback，由 session_scope 统一管理事务边界。
+"""
+
+from contextlib import contextmanager
+from typing import Generator
+
+from sqlmodel import Session
+
+from kit.config.log_config import get_default_logger
+from kit.db.engine import get_engine
+
+logger = get_default_logger(__name__)
+
+
+@contextmanager
+def session_scope(
+    db_type: str | None = None,
+    *,
+    autocommit: bool = True,
+) -> Generator[Session, None, None]:
+    """会话作用域上下文管理器（唯一的会话入口）
+
+    正常退出时自动提交（autocommit=True），异常时自动回滚，最终关闭会话。
+
+    Args:
+        db_type: 数据库类型（postgresql/mysql/sqlite），None 时使用配置默认值
+        autocommit: 是否在正常退出时自动提交事务
+
+    Yields:
+        SQLModel Session 实例
+
+    用法::
+
+        with session_scope() as session:
+            user = User(name="test")
+            session.add(user)
+            # 退出时自动提交
+    """
+    engine = get_engine(db_type)
+    session = Session(engine)
+    db_name = db_type or "默认"
+
+    try:
+        yield session
+        if autocommit:
+            session.commit()
+            logger.info(f"✅ [{db_name}] 会话事务已提交")
+    except Exception as e:
+        session.rollback()
+        logger.warning(f"⚠️ [{db_name}] 会话事务已回滚，原因: {e}")
+        raise
+    finally:
+        session.close()
+
+
+def get_session(db_type: str | None = None) -> Session:
+    """获取裸 Session（调用者需自行管理生命周期）
+
+    建议优先使用 session_scope 上下文管理器。
+    """
+    engine = get_engine(db_type)
+    return Session(engine)

kit/db/sqlite_kit.py

@@ -0,0 +1,284 @@
+"""
+Copyright (c) 2021-2026 Clark Chang. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+Project: sdpy
+Author: Clark Chang
+"""
+
+from __future__ import annotations
+
+# date: 2026-08-22
+"""SQLite 数据库工具类
+
+基于 kit.db 统一数据库层封装，提供开箱即用的服务方法。
+业务代码无需管理 session/transaction，直接调用即可。
+
+本类继承 BaseDbKit，复用全部共享实现（连接管理 / ORM / 原生 SQL / 事务 /
+表操作），并额外提供 SQLite 专属的向量操作（基于 sqlite-vector 扩展）。
+
+使用方式::
+
+    # 单条操作（自动管理事务）
+    user = SQLiteKit.create(UserModel, {"name": "张三"})
+    users = SQLiteKit.list(UserModel, skip=0, limit=10)
+    SQLiteKit.update(UserModel, user.id, {"name": "李四"})
+
+    # 向量操作
+    SQLiteKit.create_vector_table("images", dims=384)
+    SQLiteKit.insert_vectors("images", [[0.1, 0.2, ...], ...])
+    rows = SQLiteKit.search_vectors("images", [0.1, 0.2, ...], top_k=5)
+"""
+
+import numpy as np
+from sqlalchemy import text
+
+from kit.config.log_config import get_default_logger
+from kit.db.base_db_kit import BaseDbKit
+from kit.db.engine import SQLITE, get_engine
+from kit.db.session import session_scope
+
+logger = get_default_logger(__name__)
+
+
+class SQLiteKit(BaseDbKit):
+    """SQLite 数据库工具类
+
+    基于 kit.db 统一数据库层，封装为业务可直调的服务方法。
+    所有 ORM 方法内部使用 session_scope 管理事务（自动提交/回滚），
+    业务代码无需手动管理 session。
+
+    对于多操作事务场景，请使用 transaction() 上下文管理器。
+    """
+
+    DB_TYPE = SQLITE
+
+    @classmethod
+    def raw_connection(cls):
+        """获取原生 DBAPI 连接（sqlite-vector 扩展已由引擎自动加载）
+
+        用于执行 sqlite-vector 特殊函数（vector_init / vector_quantize /
+        vector_quantize_preload 等）与静态 DDL。调用方负责关闭连接。
+        """
+        return get_engine(cls.DB_TYPE).raw_connection()
+
+    @classmethod
+    def create_raw_table(
+        cls, table_name: str, columns: dict[str, str], if_not_exists: bool = True
+    ) -> None:
+        """根据「列名 → 列定义」字典创建普通表
+
+        Args:
+            table_name: 表名
+            columns: 列定义字典，如 {"id": "TEXT PRIMARY KEY", "name": "TEXT NOT NULL"}
+            if_not_exists: 是否附加 IF NOT EXISTS（默认 True）
+        """
+        column_defs = ", ".join(f"{name} {definition}" for name, definition in columns.items())
+        if_not_exists_sql = "IF NOT EXISTS " if if_not_exists else ""
+        sql = f"CREATE TABLE {if_not_exists_sql}{table_name} ({column_defs})"
+        with get_engine(cls.DB_TYPE).connect() as conn:
+            conn.execute(text(sql))
+            conn.commit()
+        logger.info(f"✅ 创建表 {table_name}")
+
+    @classmethod
+    def get_table_info(cls, table_name: str) -> list[dict[str, object]]:
+        """获取表的列信息
+
+        Args:
+            table_name: 表名
+
+        Returns:
+            列信息字典列表（column_name, data_type, is_nullable, column_default）
+        """
+        sql = """
+        SELECT
+            name as column_name,
+            type as data_type,
+            CASE WHEN "notnull" = 0 THEN 'YES' ELSE 'NO' END as is_nullable,
+            dflt_value as column_default
+        FROM pragma_table_info(:table_name)
+        ORDER BY cid
+        """
+        return cls.query(sql, {"table_name": table_name})
+
+    # ==================== 向量操作 ====================
+
+    @classmethod
+    def create_vector_table(
+        cls,
+        table_name: str,
+        id_col: str = "id",
+        dims: int = 384,
+        extra_cols: list[dict[str, str]] | None = None,
+    ) -> None:
+        """创建包含向量列的表
+
+        Args:
+            table_name: 表名
+            id_col: 主键列名（INTEGER PRIMARY KEY）
+            dims: 向量维度（默认 384）
+            extra_cols: 额外列定义，每项为 {"name": str, "type": str}，
+                如 [{"name": "label", "type": "TEXT"}]
+
+        表结构示例::
+
+            CREATE TABLE images (
+                id INTEGER PRIMARY KEY,
+                embedding BLOB,  -- FLOAT32 向量
+                label TEXT
+            );
+        """
+        extra_defs = ""
+        if extra_cols:
+            extra_defs = ", " + ", ".join(
+                f"{c['name']} {c['type']}" for c in extra_cols
+            )
+
+        sql = f"""
+        CREATE TABLE IF NOT EXISTS {table_name} (
+            {id_col} INTEGER PRIMARY KEY,
+            embedding BLOB{extra_defs}
+        )
+        """
+        with session_scope(cls.DB_TYPE, autocommit=False) as session:
+            session.execute(text(sql))
+            logger.info(f"✅ 创建向量表 {table_name}（维度={dims}）")
+
+    @classmethod
+    def insert_vectors(
+        cls,
+        table_name: str,
+        vectors: list[list[float]],
+        ids: list[int] | None = None,
+        extra_data: list[dict[str, object]] | None = None,
+    ) -> int:
+        """批量插入向量数据
+
+        Args:
+            table_name: 表名
+            vectors: 向量列表，每个向量为 float 列表
+            ids: 可选的 ID 列表（长度需与 vectors 一致），None 时自动递增
+            extra_data: 额外列数据列表（长度需与 vectors 一致）
+
+        Returns:
+            插入的行数
+        """
+        if ids is not None and len(ids) != len(vectors):
+            raise ValueError("ids 长度必须与 vectors 一致")
+        if extra_data is not None and len(extra_data) != len(vectors):
+            raise ValueError("extra_data 长度必须与 vectors 一致")
+
+        engine = get_engine(cls.DB_TYPE)
+        with engine.connect() as conn:
+            for i, vec in enumerate(vectors):
+                vec_bytes = np.array(vec, dtype=np.float32).tobytes()
+                if ids is not None:
+                    _id = ids[i]
+                    sql = f"INSERT INTO {table_name} (id, embedding) VALUES (:id, :vec)"
+                    params: dict[str, object] = {"id": _id, "vec": vec_bytes}
+                else:
+                    sql = f"INSERT INTO {table_name} (embedding) VALUES (:vec)"
+                    params = {"vec": vec_bytes}
+
+                if extra_data is not None:
+                    col_names = ", ".join(k for k in extra_data[i].keys())
+                    col_vals = ", ".join(f":{k}" for k in extra_data[i].keys())
+                    if ids is not None:
+                        sql = (
+                            f"INSERT INTO {table_name} "
+                            f"(id, embedding, {col_names}) VALUES (:id, :vec, {col_vals})"  # noqa: E501
+                        )
+                        params.update(extra_data[i])
+                    else:
+                        sql = (
+                            f"INSERT INTO {table_name} "
+                            f"(embedding, {col_names}) VALUES (:vec, {col_vals})"
+                        )
+                        params = {"vec": vec_bytes, **extra_data[i]}
+
+                conn.execute(text(sql), params)
+            conn.commit()
+            logger.info(f"✅ 插入 {len(vectors)} 条向量到 {table_name}")
+            return len(vectors)
+
+    @classmethod
+    def search_vectors(
+        cls,
+        table_name: str,
+        query_vector: list[float],
+        top_k: int = 10,
+        distance_type: str = "COSINE",
+        filter_sql: str | None = None,
+    ) -> list[dict[str, object]]:
+        """搜索最近邻向量
+
+        Args:
+            table_name: 表名
+            query_vector: 查询向量（float 列表）
+            top_k: 返回结果数
+            distance_type: 距离类型（COSINE / L2 / L1 / DOT / SQUARED_L2）
+            filter_sql: 可选的过滤条件 WHERE 子句（不含 WHERE 关键字），
+                如 "label = 'cat'"
+
+        Returns:
+            按距离升序排列的结果列表，每项为 {"id": int, "distance": float, ...额外列}
+        """
+        engine = get_engine(cls.DB_TYPE)
+        query_bytes = np.array(query_vector, dtype=np.float32).tobytes()
+
+        with engine.connect() as conn:
+            # 初始化向量索引
+            conn.execute(
+                text(
+                    "SELECT vector_init("
+                    f"'{table_name}', 'embedding', 'type=FLOAT32,dimension={len(query_vector)}')"  # noqa: E501
+                )
+            )
+
+            # 量化
+            conn.execute(text(f"SELECT vector_quantize('{table_name}', 'embedding')"))
+
+            where_clause = f"WHERE {filter_sql}" if filter_sql else ""
+
+            sql = f"""
+            SELECT e.id, v.distance
+            FROM {table_name} AS e
+            JOIN vector_quantize_scan('{table_name}', 'embedding', :query, {top_k}) AS v
+            ON e.id = v.rowid
+            {where_clause}
+            ORDER BY v.distance ASC
+            """
+            result = conn.execute(text(sql), {"query": query_bytes})
+            rows = result.fetchall()
+            columns = result.keys()
+            data = [dict(zip(columns, row)) for row in rows]
+            logger.info(f"🔍 向量搜索 {table_name} → 返回 {len(data)} 条")
+            return data
+
+    @classmethod
+    def vector_version(cls) -> str:
+        """获取 sqlite-vector 扩展版本
+
+        Returns:
+            版本号字符串，加载失败时返回 "unavailable"
+        """
+        try:
+            engine = get_engine(cls.DB_TYPE)
+            with engine.connect() as conn:
+                row = conn.execute(text("SELECT vector_version()")).fetchone()
+                return str(row[0]) if row else "unknown"
+        except Exception as e:
+            logger.warning(f"⚠️ 获取 vector_version 失败: {e}")
+            return "unavailable"