sdpy-kit 0.1.0__tar.gz → 0.1.2__tar.gz

{sdpy_kit-0.1.0 → sdpy_kit-0.1.2}/PKG-INFO

@@ -1,20 +1,27 @@
 Metadata-Version: 2.5
 Name: sdpy-kit
-Version: 0.1.0
+Version: 0.1.2
 Summary: SDPY Kit——统一数据库访问层（PG/MySQL/SQLite）与 AI/MCP/Redis/文件/文档/向量工具集
 Author-email: Clark <changhongyuan@126.com>
 License-Expression: MIT
+Keywords: ai,kit,mcp,mysql,postgresql,redis,sdpy,sqlalchemy,sqlite,sqlmodel,向量检索,工具集,开发工具,数据库
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: Chinese (Simplified)
+Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.13
 Requires-Dist: fastmcp>=4.0.3
 Requires-Dist: firecrawl-anydoc>=0.2.4
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: markdown-it-py>=3.0
+Requires-Dist: numpy>=2.0
 Requires-Dist: pimd[pdfa]>=2.2.5
 Requires-Dist: psycopg2-binary>=2.9.12
 Requires-Dist: pydantic-settings>=2.0

{sdpy_kit-0.1.0 → sdpy_kit-0.1.2}/kit/__init__.py

@@ -1,68 +1,68 @@
-"""
-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
-"""Kit 模块——统一数据库访问层 + 工具集
-
-数据库访问通过 kit.db 子包提供（基于 SQLModel）。
-"""
-
-__version__ = "0.1.0"
-
-from kit.db import (
-    MYSQL,
-    POSTGRESQL,
-    SQLITE,
-    CRUDBase,
-    DBError,
-    NotFoundError,
-    close_all_engines,
-    close_engine,
-    create_tables,
-    get_engine,
-    get_session,
-    list_tables,
-    session_scope,
-    table_exists,
-    transactional,
-)
-
-__all__ = [
-    # 引擎管理
-    "get_engine",
-    "create_tables",
-    "list_tables",
-    "table_exists",
-    "close_all_engines",
-    "close_engine",
-    # 常量
-    "POSTGRESQL",
-    "MYSQL",
-    "SQLITE",
-    # 会话
-    "session_scope",
-    "get_session",
-    # 异常
-    "DBError",
-    "NotFoundError",
-    # CRUD
-    "CRUDBase",
-    # 事务
-    "transactional",
-]
+"""
+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
+"""Kit 模块——统一数据库访问层 + 工具集
+
+数据库访问通过 kit.db 子包提供（基于 SQLModel）。
+"""
+
+__version__ = "0.1.2"
+
+from kit.db import (
+    MYSQL,
+    POSTGRESQL,
+    SQLITE,
+    CRUDBase,
+    DBError,
+    NotFoundError,
+    close_all_engines,
+    close_engine,
+    create_tables,
+    get_engine,
+    get_session,
+    list_tables,
+    session_scope,
+    table_exists,
+    transactional,
+)
+
+__all__ = [
+    # 引擎管理
+    "get_engine",
+    "create_tables",
+    "list_tables",
+    "table_exists",
+    "close_all_engines",
+    "close_engine",
+    # 常量
+    "POSTGRESQL",
+    "MYSQL",
+    "SQLITE",
+    # 会话
+    "session_scope",
+    "get_session",
+    # 异常
+    "DBError",
+    "NotFoundError",
+    # CRUD
+    "CRUDBase",
+    # 事务
+    "transactional",
+]

{sdpy_kit-0.1.0 → sdpy_kit-0.1.2}/kit/config/kit_config.py

@@ -28,12 +28,6 @@ from pydantic_settings import BaseSettings
 
 
 class Settings(BaseSettings):
-    APP_NAME: str = Field(default="SDPY App")
-    VERSION: str = Field(default="0.1.0")
-    DEBUG: bool = Field(default=True)
-    HOST: str = Field(default="0.0.0.0")
-    PORT: int = Field(default=8000)
-
     LOG_LEVEL: str = Field(default="INFO")
     LOG_TO_CONSOLE: bool = Field(default=True)
     LOG_TO_FILE: bool = Field(default=False)

sdpy_kit-0.1.2/kit/db/query.py

@@ -0,0 +1,338 @@
+"""
+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
+"""查询构建器（不可变）+ 线程安全查询缓存
+
+QueryBuilder 采用不可变设计：每个链式方法返回新实例，避免状态副作用。
+count() 从原始模型构建独立计数查询，仅复制 WHERE 条件，不受 limit/offset 影响。
+"""
+
+import functools
+import threading
+import time
+from collections.abc import Callable
+from datetime import UTC, datetime, timedelta
+from typing import Any, TypeVar
+
+from sqlalchemy import func
+from sqlalchemy.orm import load_only
+from sqlmodel import Session, SQLModel, select
+
+from kit.config.log_config import get_default_logger
+
+logger = get_default_logger(__name__)
+
+T = TypeVar("T", bound=SQLModel)
+
+
+class QueryBuilder:
+    """不可变链式查询构建器
+
+    每个链式方法返回新的 QueryBuilder 实例，避免修改原始 builder 的状态。
+    这允许同一个 builder 安全复用于不同查询。
+
+    用法::
+
+        qb = QueryBuilder(User, session)
+        active = qb.filter(User.is_active == True).all()
+        # qb 的状态未被修改，可继续复用
+        young = qb.filter(User.age < 30).all()
+    """
+
+    def __init__(self, model: type[T], session: Session):
+        self._model = model
+        self._session = session
+        self._statement = select(model)
+
+    def _clone(self) -> "QueryBuilder[T]":
+        """创建当前 builder 的浅拷贝（SQLAlchemy Select 不可变，直接引用即可）"""
+        new = QueryBuilder.__new__(QueryBuilder)
+        new._model = self._model
+        new._session = self._session
+        new._statement = self._statement
+        return new
+
+    def filter(self, *conditions) -> "QueryBuilder[T]":
+        """添加过滤条件"""
+        builder = self._clone()
+        if conditions:
+            builder._statement = builder._statement.where(*conditions)
+        return builder
+
+    def filter_by(self, **kwargs) -> "QueryBuilder[T]":
+        """按字段值过滤（等值条件）"""
+        conditions = [
+            getattr(self._model, key) == value for key, value in kwargs.items()
+        ]
+        return self.filter(*conditions)
+
+    def join(self, target, onclause=None, isouter: bool = False) -> "QueryBuilder[T]":
+        """添加 JOIN"""
+        builder = self._clone()
+        builder._statement = (
+            builder._statement.join(target, onclause, isouter=isouter)
+            if onclause
+            else builder._statement.join(target, isouter=isouter)
+        )
+        return builder
+
+    def order_by(self, *columns) -> "QueryBuilder[T]":
+        """排序"""
+        builder = self._clone()
+        builder._statement = builder._statement.order_by(*columns)
+        return builder
+
+    def limit(self, limit: int) -> "QueryBuilder[T]":
+        """限制返回行数"""
+        builder = self._clone()
+        builder._statement = builder._statement.limit(limit)
+        return builder
+
+    def offset(self, offset: int) -> "QueryBuilder[T]":
+        """跳过前 N 行"""
+        builder = self._clone()
+        builder._statement = builder._statement.offset(offset)
+        return builder
+
+    def distinct(self) -> "QueryBuilder[T]":
+        """去重"""
+        builder = self._clone()
+        builder._statement = builder._statement.distinct()
+        return builder
+
+    def only(self, *field_names: str) -> "QueryBuilder[T]":
+        """只加载指定字段"""
+        builder = self._clone()
+        columns = [getattr(self._model, name) for name in field_names]
+        builder._statement = builder._statement.options(load_only(*columns))
+        return builder
+
+    # ==================== 执行方法 ====================
+
+    def all(self) -> list[T]:
+        """获取所有记录"""
+        return list(self._session.exec(self._statement).all())
+
+    def first(self) -> T | None:
+        """获取第一条记录"""
+        return self._session.exec(self._statement.limit(1)).first()
+
+    def count(self) -> int:
+        """获取记录数（不受 limit/offset 影响）"""
+        # 从原始模型构建计数查询，仅保留 WHERE 条件，忽略 limit/offset
+        count_stmt = select(func.count()).select_from(self._model)
+        whereclause = self._statement.whereclause
+        if whereclause is not None:
+            count_stmt = count_stmt.where(whereclause)
+        return self._session.exec(count_stmt).one()
+
+    def exists(self) -> bool:
+        """检查是否存在符合条件的记录"""
+        from sqlalchemy import exists as sa_exists
+
+        exists_stmt = select(sa_exists().where(self._statement.whereclause))
+        return bool(self._session.exec(exists_stmt).one())
+
+    def paginate(self, page: int = 1, per_page: int = 20) -> dict[str, Any]:
+        """分页查询
+
+        Args:
+            page: 页码（从 1 开始）
+            per_page: 每页条数
+
+        Returns:
+            包含 items/total/page/per_page/pages/has_prev/has_next 的字典
+        """
+        offset = (page - 1) * per_page
+        total = self.count()
+
+        paginated = self._statement.offset(offset).limit(per_page)
+        items = list(self._session.exec(paginated).all())
+
+        return {
+            "items": items,
+            "total": total,
+            "page": page,
+            "per_page": per_page,
+            "pages": (total + per_page - 1) // per_page if per_page > 0 else 0,
+            "has_prev": page > 1,
+            "has_next": page * per_page < total,
+        }
+
+
+class QueryCache:
+    """线程安全的查询缓存（TTL + LRU 淘汰）"""
+
+    def __init__(self, default_ttl: int = 300, maxsize: int = 1000):
+        self._cache: dict[str, dict[str, Any]] = {}
+        self._default_ttl = default_ttl
+        self._maxsize = maxsize
+        self._lock = threading.RLock()
+
+    def get(self, key: str) -> Any | None:
+        """获取缓存值"""
+        with self._lock:
+            if key not in self._cache:
+                return None
+            item = self._cache[key]
+            if item["expires_at"] > datetime.now(UTC):
+                return item["value"]
+            del self._cache[key]
+            return None
+
+    def set(self, key: str, value: Any, ttl: int | None = None) -> None:
+        """设置缓存值"""
+        with self._lock:
+            # 达到上限时清理最早的条目
+            if len(self._cache) >= self._maxsize:
+                oldest = min(self._cache, key=lambda k: self._cache[k]["expires_at"])
+                del self._cache[oldest]
+            self._cache[key] = {
+                "value": value,
+                "expires_at": datetime.now(UTC)
+                + timedelta(seconds=ttl or self._default_ttl),
+            }
+
+    def delete(self, key: str) -> None:
+        """删除缓存"""
+        with self._lock:
+            self._cache.pop(key, None)
+
+    def clear(self) -> None:
+        """清空缓存"""
+        with self._lock:
+            self._cache.clear()
+
+    def clean_expired(self) -> int:
+        """清理过期缓存，返回清理的条目数"""
+        with self._lock:
+            now = datetime.now(UTC)
+            expired = [k for k, v in self._cache.items() if v["expires_at"] <= now]
+            for k in expired:
+                del self._cache[k]
+            return len(expired)
+
+
+class QueryOptimizer:
+    """查询优化器：分析执行计划、建议索引、监控性能"""
+
+    def __init__(self, session: Session):
+        self.session = session
+        self._stats: list[dict[str, Any]] = []
+
+    def explain(self, statement) -> dict[str, Any]:
+        """分析查询执行计划"""
+        from sqlalchemy import text
+
+        dialect = self.session.get_bind().dialect.name
+        compiled = statement.compile(self.session.get_bind())
+
+        try:
+            if dialect == "postgresql":
+                result = self.session.execute(text(f"EXPLAIN (FORMAT JSON) {compiled}"))
+                return {"dialect": dialect, "plan": result.scalar()}
+            elif dialect == "mysql":
+                result = self.session.execute(text(f"EXPLAIN FORMAT=JSON {compiled}"))
+                return {"dialect": dialect, "plan": result.scalar()}
+            elif dialect == "sqlite":
+                result = self.session.execute(text(f"EXPLAIN QUERY PLAN {compiled}"))
+                return {
+                    "dialect": dialect,
+                    "plan": [dict(row._mapping) for row in result.fetchall()],
+                }
+            else:
+                return {"dialect": dialect, "plan": None, "error": "不支持的数据库"}
+        except Exception as e:
+            logger.error(f"❌ 查询分析失败: {e}")
+            return {"error": str(e)}
+
+    def suggest_indexes(
+        self, model: type[SQLModel], query_fields: list[str]
+    ) -> list[str]:
+        """建议索引"""
+        table_name = model.__tablename__
+        suggestions = [
+            f"CREATE INDEX idx_{table_name}_{field} ON {table_name}({field});"
+            for field in query_fields
+        ]
+        if len(query_fields) > 1:
+            composite = "_".join(query_fields[:3])
+            suggestions.append(
+                f"CREATE INDEX idx_{table_name}_{composite} "
+                f"ON {table_name}({', '.join(query_fields[:3])});"
+            )
+        return suggestions
+
+    def measure(self, statement, params: dict | None = None) -> dict[str, Any]:
+        """测量查询性能"""
+        start = time.time()
+        try:
+            result = self.session.execute(statement, params or {})
+            rows = result.fetchall()
+            elapsed = time.time() - start
+
+            stats: dict[str, Any] = {
+                "execution_time": elapsed,
+                "row_count": len(rows),
+                "timestamp": datetime.now(UTC).isoformat(),
+            }
+            if elapsed > 1.0:
+                stats["warning"] = "慢查询"
+                logger.warning(f"⚠️ 慢查询: {elapsed:.2f}s, 返回 {len(rows)} 行")
+            self._stats.append(stats)
+            return stats
+        except Exception as e:
+            logger.error(f"❌ 性能测量失败: {e}")
+            return {"error": str(e)}
+
+    @property
+    def stats(self) -> list[dict[str, Any]]:
+        """获取查询统计信息"""
+        return list(self._stats)
+
+    def clear_stats(self) -> None:
+        """清空统计信息"""
+        self._stats.clear()
+
+
+def cached_query(ttl: int = 300, maxsize: int = 1000) -> Callable:
+    """查询缓存装饰器
+
+    注意：被装饰的函数不应将 Session 作为参数，否则每次缓存键不同。
+    """
+    cache = QueryCache(default_ttl=ttl, maxsize=maxsize)
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            cache_key = f"{func.__name__}:{repr(args)}:{repr(kwargs)}"
+            cached = cache.get(cache_key)
+            if cached is not None:
+                logger.debug(f"✅ 缓存命中: {func.__name__}")
+                return cached
+            result = func(*args, **kwargs)
+            cache.set(cache_key, result, ttl)
+            return result
+
+        # 暴露缓存实例供外部管理
+        wrapper._cache = cache  # type: ignore
+        return wrapper
+
+    return decorator

{sdpy_kit-0.1.0 → sdpy_kit-0.1.2}/kit/db/sqlite_kit.py

@@ -84,7 +84,9 @@ class SQLiteKit(BaseDbKit):
             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())
+        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:
@@ -92,6 +94,42 @@ class SQLiteKit(BaseDbKit):
             conn.commit()
         logger.info(f"✅ 创建表 {table_name}")
 
+    @classmethod
+    def raw_insert(cls, table_name: str, data: dict[str, object]) -> int:
+        """向指定表插入一行数据（键为列名）
+
+        Args:
+            table_name: 表名
+            data: 列名 → 值 字典
+
+        Returns:
+            受影响的行数
+        """
+        columns = ", ".join(data.keys())
+        placeholders = ", ".join(f":{name}" for name in data)
+        sql = f"INSERT INTO {table_name} ({columns}) VALUES ({placeholders})"
+        return cls.execute(sql, dict(data))
+
+    @classmethod
+    def raw_get_by(
+        cls, table_name: str, column: str, value: object
+    ) -> dict[str, object] | None:
+        """按单列等值查询一行
+
+        Args:
+            table_name: 表名
+            column: 列名
+            value: 查询值
+
+        Returns:
+            匹配的第一行（字典）；无匹配返回 None
+        """
+        rows = cls.query(
+            f"SELECT * FROM {table_name} WHERE {column} = :value LIMIT 1",
+            {"value": value},
+        )
+        return rows[0] if rows else None
+
     @classmethod
     def get_table_info(cls, table_name: str) -> list[dict[str, object]]:
         """获取表的列信息

{sdpy_kit-0.1.0 → sdpy_kit-0.1.2}/pyproject.toml

@@ -11,17 +11,27 @@ authors = [
     { name = "Clark", email = "changhongyuan@126.com" }
 ]
 requires-python = ">=3.13"
+keywords = [
+    "sdpy", "kit", "工具集", "数据库", "postgresql", "mysql", "sqlite",
+    "sqlmodel", "sqlalchemy", "ai", "mcp", "redis", "向量检索", "开发工具",
+]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
+    "Natural Language :: Chinese (Simplified)",
+    "Operating System :: OS Independent",
     "Programming Language :: Python :: 3 :: Only",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Topic :: Database",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 dependencies = [
     "pydantic>=2.0",
     "pydantic-settings>=2.0",
+    "numpy>=2.0",
     "sqlalchemy~=2.0.51",
     "sqlmodel>=0.0.39",
     "pymysql>=1.2.0",