precis-cli 0.1.3__py3-none-any.whl

app/shared/core/data_source/loaders/sql_loader.py

@@ -0,0 +1,313 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# 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.
+"""
+@fileoverview SQL 数据源加载器模块
+
+功能概述:
+- 通过 SQLAlchemy 连接数据库并执行 SELECT / WITH 查询
+- 使用 pandas.read_sql 加载结果为 DataFrame
+- 查询字符串安全清洗：拒绝非 SELECT/WITH、分号、危险关键字（B20）
+- 支持 schema-prefixed 表名（如 public.users，B21）
+- 模块级引擎缓存，按 connection_string 复用，避免连接池耗尽（B22）
+
+架构设计:
+- 继承 DataSourceLoader，通过注册表自动发现
+- _get_engine() 管理 SQLAlchemy 引擎生命周期（带缓存）
+- _sanitize_query() 在查询执行前进行白名单校验
+- 危险关键字和语法特征通过模块级常量集中管理
+
+输入示例:
+    spec = SQLSourceSpec(
+        connection_string="postgresql://user:pass@localhost/db",
+        query="SELECT id, name FROM public.users WHERE active = true"
+    )
+    loader = SQLLoader(spec)
+
+输出示例:
+    df = loader.load()
+    # 返回 pandas.DataFrame，仅包含查询结果
+    # 若查询包含危险关键字或非 SELECT 语句则抛出 DataLoadError
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import threading
+from collections import OrderedDict
+from typing import Any
+
+import pandas as pd
+
+from ..specs.sql_source import SQLSourceSpec
+from .base import DataLoadError, DataSourceLoader
+from .registry import register_loader
+
+logger = logging.getLogger(__name__)
+
+# 模块级引擎缓存，按 connection_string 复用，避免连接池耗尽（B22）。
+# B-locksafety: 多线程安全改造——
+#   1. 校验执行器会把同步加载工作 offload 到线程池（executor.py），_get_engine 会被
+#      多线程并发调用，原裸 dict 无锁存在竞态（两线程同时 miss 各建一个 engine，
+#      一个成孤儿永不 dispose）。
+#   2. 缓存改为 OrderedDict 实现 LRU（容量 _ENGINE_CACHE_MAX），淘汰时调用
+#      engine.dispose() 释放底层连接池，避免轮换凭据/多 DB 场景 FD 耗尽。
+#   3. atexit 注册进程退出时全量 dispose（桌面应用生命周期短，主要靠 LRU 淘汰兜底）。
+_ENGINE_CACHE_MAX = 8
+_engine_cache: OrderedDict[str, Any] = OrderedDict()
+_engine_cache_lock = threading.Lock()
+
+# 危险的 SQL 关键字，用于拒绝潜在的注入攻击（B20）。
+# 词级关键字按 \b 词边界匹配（列名 last_update 不再误杀）；符号类按子串匹配。
+_WORD_BOUNDARY_SQL_KEYWORDS = (
+    "drop",
+    "delete",
+    "insert",
+    "update",
+    "create",
+    "alter",
+    "truncate",
+    "grant",
+    "revoke",
+    "exec",
+    "execute",
+    "union",
+)
+_SUBSTRING_SQL_KEYWORDS = (
+    "--",
+    "/*",
+    "*/",
+)
+
+
+@register_loader("sql")
+class SQLLoader(DataSourceLoader["SQLSourceSpec"]):
+    """
+    @classdesc SQL 数据库加载器
+
+    使用 pandas 的 read_sql 方法从数据库加载数据。
+    支持多种数据库后端（通过 SQLAlchemy）。
+    """
+
+    spec_class = SQLSourceSpec  # 类型由泛型指定
+
+    def _get_engine(self, connection_string: str) -> Any:
+        """
+        @methoddesc 获取或创建数据库引擎（带缓存）。
+
+        使用模块级字典 _engine_cache 按 connection_string 缓存引擎实例，
+        避免重复创建连接池导致资源耗尽。
+
+        Args:
+            connection_string: SQLAlchemy 数据库连接字符串
+                例如 "postgresql://user:pass@localhost/db"
+
+        Returns:
+            SQLAlchemy 引擎实例
+
+        Raises:
+            ImportError: 如果未安装 sqlalchemy 则会在 import 时抛出
+
+        示例:
+            >>> engine = loader._get_engine("sqlite:///test.db")
+        """
+        from sqlalchemy import create_engine
+
+        # B-locksafety: 加锁保证"检查-创建-放入缓存"原子，避免并发 miss 各建 engine。
+        # 锁只保护 dict 操作（快），create_engine 在锁外执行后会再次拿锁写入——
+        # 但为简单起见这里在锁内创建（SQLLoader 加载本身是 offload 到线程的批操作，
+        # create_engine 的开销相对 DB 查询可忽略，优先保证正确性）。
+        with _engine_cache_lock:
+            if connection_string in _engine_cache:
+                # 命中：移到队尾标记为最近使用（LRU）
+                _engine_cache.move_to_end(connection_string)
+                return _engine_cache[connection_string]
+
+            engine = create_engine(connection_string)
+
+            # 放入缓存前，若已达容量上限，淘汰最久未用的 engine 并 dispose 其连接池
+            while len(_engine_cache) >= _ENGINE_CACHE_MAX:
+                _, evicted = _engine_cache.popitem(last=False)
+                try:
+                    evicted.dispose()
+                except Exception as e:  # noqa: BLE001
+                    logger.warning("淘汰 SQL engine 时 dispose 失败（可能已关闭）: %s", e)
+
+            _engine_cache[connection_string] = engine
+            return engine
+
+    def _sanitize_query(self, query: str) -> str:
+        """
+        @methoddesc 检查查询字符串是否包含危险的 SQL 注入特征（B20）。
+
+        安全策略（白名单模式）：
+        1. 只允许以 SELECT 或 WITH 开头的查询
+        2. 拒绝包含分号（;）的查询，防止多语句执行
+        3. 拒绝危险关键字（如 DROP、DELETE、INSERT、UPDATE 等）
+
+        如果查询不通过安全检查，会抛出 DataLoadError。
+
+        Args:
+            query: 用户提供的原始 SQL 查询字符串
+
+        Returns:
+            清洗后的查询字符串（去除首尾空白）
+
+        Raises:
+            DataLoadError: 查询包含危险特征或不以 SELECT/WITH 开头时抛出
+
+        示例:
+            >>> safe_query = loader._sanitize_query("SELECT * FROM users")
+            >>> # 返回: "SELECT * FROM users"
+            >>> loader._sanitize_query("DROP TABLE users")
+            >>> # 抛出 DataLoadError
+        """
+        stripped = query.strip()
+        lower = stripped.lower()
+
+        # 只允许 SELECT 和 WITH 开头的查询
+        if not lower.startswith(("select", "with")):
+            raise DataLoadError(
+                f"SQL 查询必须以 SELECT 或 WITH 开头，当前查询: {stripped[:80]}...",
+                self.spec,
+            )
+
+        # 拒绝分号（多语句特征）
+        if ";" in stripped:
+            raise DataLoadError(
+                "SQL 查询不允许包含分号（;），请使用单条 SELECT 语句",
+                self.spec,
+            )
+
+        # 拒绝危险关键字。
+        # 词级关键字（drop/update 等）按词边界匹配：子串匹配会把列名 last_update
+        # （含 "update "）误判为危险语句。_ 是词字符，\b 不在其前，故 last_update 放行、
+        # 独立的 UPDATE 仍拒绝。符号类（--、/*、*/）无词边界概念，保持子串匹配。
+        for keyword in _WORD_BOUNDARY_SQL_KEYWORDS:
+            if re.search(rf"\b{keyword}\b", lower):
+                raise DataLoadError(
+                    f"SQL 查询包含危险关键字 '{keyword}'，已被拒绝",
+                    self.spec,
+                )
+        for symbol in _SUBSTRING_SQL_KEYWORDS:
+            if symbol in lower:
+                raise DataLoadError(
+                    f"SQL 查询包含危险特征 '{symbol}'，已被拒绝",
+                    self.spec,
+                )
+
+        return stripped
+
+    def load(self) -> pd.DataFrame:
+        """
+        @methoddesc 从 SQL 数据库加载数据
+
+        Returns:
+            DataFrame
+
+        Raises:
+            DataLoadError: 加载失败时抛出
+            ImportError: 缺少必要的驱动时抛出
+        """
+        try:
+            from sqlalchemy import text
+        except ImportError:
+            raise DataLoadError("加载 SQL 数据源需要安装 sqlalchemy: pip install sqlalchemy", self.spec)
+
+        try:
+            # 复用已缓存的引擎（B22）
+            engine = self._get_engine(self.spec.connection_string)
+
+            # 构建查询
+            query_input = self.spec.table_or_query.strip()
+            if query_input.lower().startswith(("select", "with")):
+                # 用户提供了查询语句，先进行安全检查（B20）
+                safe_query = self._sanitize_query(query_input)
+                with engine.connect() as conn:
+                    df = pd.read_sql(text(safe_query), conn, params=self.spec.params)
+            else:
+                # 用户提供了表名，使用 SQLAlchemy 的 Table + select 安全构建查询
+                # Table 名称会被自动引用，防止 SQL 注入
+                from sqlalchemy import MetaData, Table, select
+
+                # 表名中禁止出现可疑字符
+                if not re.match(r"^[\w.]+$", query_input):
+                    raise DataLoadError(f"表名包含非法字符: {query_input}", self.spec)
+
+                # 支持 schema.table 格式（如 public.users）（B21）
+                if "." in query_input:
+                    schema_name, table_name = query_input.rsplit(".", 1)
+                    table = Table(table_name, MetaData(), schema=schema_name)
+                else:
+                    table = Table(query_input, MetaData())
+                with engine.connect() as conn:
+                    df = pd.read_sql(select(table), conn)
+
+            return df
+
+        except Exception as e:
+            raise DataLoadError(f"SQL 加载失败: {e}", self.spec, e)
+
+    def validate(self) -> list[str]:
+        """
+        @methoddesc 验证 SQL 数据源配置。
+
+        检查项：
+        - 连接字符串是否为空
+        - 表名或查询语句是否为空
+        - SQLAlchemy 库是否已安装
+
+        Returns:
+            错误信息列表，空列表表示验证通过
+
+        示例:
+            >>> errors = loader.validate()
+            >>> if errors:
+            ...     print("验证失败:", errors)
+        """
+        errors = []
+
+        # 检查连接字符串
+        if not self.spec.connection_string:
+            errors.append("连接字符串不能为空")
+
+        # 检查表名/查询
+        if not self.spec.table_or_query:
+            errors.append("表名或查询语句不能为空")
+
+        # 检查 SQLAlchemy 是否可用
+        import importlib.util
+
+        if importlib.util.find_spec("sqlalchemy") is None:
+            errors.append("缺少 SQLAlchemy: pip install sqlalchemy")
+
+        return errors
+
+
+def _dispose_all_engines() -> None:
+    """进程退出时全量释放缓存的 SQL engine 连接池（B-locksafety）。"""
+    with _engine_cache_lock:
+        while _engine_cache:
+            _, engine = _engine_cache.popitem(last=False)
+            try:
+                engine.dispose()
+            except Exception as e:  # noqa: BLE001
+                logger.warning("进程退出 dispose SQL engine 失败: %s", e)
+
+
+import atexit
+
+atexit.register(_dispose_all_engines)

app/shared/core/data_source/loaders/strategies/__init__.py

@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# 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.
+"""
+@fileoverview JSON 解析策略模块入口
+
+功能概述:
+- 聚合和导出所有 JSON 解析策略类
+- 提供 get_parser 工厂函数按格式获取解析器
+- 支持 array、lines、object 三种解析格式(D8: auto 已废弃)
+- 统一管理解析策略的公共接口
+
+架构设计:
+- 策略模式：各解析器实现 JSONParserStrategy 协议
+- 工厂模式：get_parser 按格式字符串返回对应解析器实例
+- 与 JSONLoader 配合使用，实现 JSON 的显式格式解析
+
+输入示例:
+    >>> from app.shared.core.data_source.loaders.strategies import get_parser
+    >>> parser = get_parser("array")     # 顶层数组格式
+    >>> parser = get_parser("lines")     # JSON Lines 格式
+    >>> parser = get_parser("object")    # 嵌套对象格式
+
+输出示例:
+    >>> parser = get_parser("array")
+    >>> data = parser.parse('[{"id": 1}, {"id": 2}]')
+    >>> # 返回 [{"id": 1}, {"id": 2}]
+"""
+
+from __future__ import annotations
+
+from .array_parser import ArrayParser
+from .lines_parser import (
+    JSONParserStrategy,
+    LinesParser,
+    ParserStrategyRegistry,
+    StandardJSONParser,
+)
+from .object_parser import ObjectParser
+
+__all__ = [
+    "JSONParserStrategy",
+    "LinesParser",
+    "StandardJSONParser",
+    "ParserStrategyRegistry",
+    "ArrayParser",
+    "ObjectParser",
+]
+
+
+def get_parser(format: str) -> JSONParserStrategy:
+    """
+    @methoddesc 获取指定格式的解析器
+
+    D8: format 必须显式指定(array/lines/object),不再支持 auto 自动检测。
+    auto 会猜测主数据数组(取最长/取第一个),与精确列定义的设计矛盾,已废弃。
+
+    Args:
+        format: JSON 格式类型(必填)
+            - "array": 顶层数组 JSON(如 [{...}])
+            - "lines": JSON Lines 格式(每行一个 JSON)
+            - "object": 嵌套对象格式(需配合 json_path 精确指定数据数组)
+
+    Returns:
+        JSON 解析器实例
+
+    Raises:
+        ValueError: format="auto"(已废弃)或不支持时抛出,引导用户改用显式 format
+    """
+    # D8: auto 已废弃,明确报错引导(不替用户猜该改成什么)
+    if format == "auto":
+        raise ValueError(
+            "format='auto' 已废弃(自动检测会猜测主数据数组,可能导致校验跑错对象)。"
+            "请显式指定 format:array(顶层数组 [{...}])、lines(JSON Lines)、"
+            "或 object(嵌套对象,需配合 json_path 如 $.data 精确指定数据数组路径)。"
+        )
+
+    parsers: dict[str, type[JSONParserStrategy]] = {
+        "array": ArrayParser,
+        "lines": LinesParser,
+        "object": ObjectParser,
+    }
+
+    parser_class = parsers.get(format)
+    if not parser_class:
+        raise ValueError(f"不支持的 JSON 格式: {format}，支持的格式: {list(parsers.keys())}(auto 已废弃)")
+
+    return parser_class()

app/shared/core/data_source/loaders/strategies/array_parser.py

@@ -0,0 +1,277 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# 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.
+"""
+@fileoverview ArrayParser JSON 数组解析策略
+
+功能概述:
+- 解析标准 JSON 数组格式: [{"a": 1}, {"a": 2}]
+- 解析单个对象包装格式: {"a": 1}
+- 自动检测输入数据是否为数组格式
+- 处理 json.JSONDecodeError 异常
+
+架构设计:
+- 实现 JSONParserStrategy Protocol 协议
+- 策略模式用于支持多种 JSON 解析方式
+- 可与 JSONLoader 配合使用
+
+输入示例:
+    # 标准数组格式
+    '[{"a": 1}, {"a": 2}]'
+    # 单个对象格式
+    '{"a": 1}'
+    # 嵌套数组格式
+    '{"data": [{"a": 1}, {"a": 2}]}'
+
+输出示例:
+    [{"a": 1}, {"a": 2}]  # 返回字典列表
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Protocol, runtime_checkable
+
+logger = logging.getLogger(__name__)
+
+
+@runtime_checkable
+class JSONParserStrategy(Protocol):
+    """
+    @classdesc JSON 解析策略协议
+
+    定义 JSON 解析器的标准接口。
+    实现此协议的具体策略类可以处理不同格式的 JSON 数据。
+    """
+
+    def can_parse(self, raw_content: str) -> bool:
+        """
+        @methoddesc 检测是否能够解析给定的原始内容
+
+        Args:
+            raw_content: 原始 JSON 字符串
+
+        Returns:
+            如果能够解析返回 True，否则返回 False
+        """
+        ...
+
+    def parse(self, raw_content: str) -> list[dict[str, Any]]:
+        """
+        @methoddesc 解析 JSON 字符串为字典列表
+
+        Args:
+            raw_content: 原始 JSON 字符串
+
+        Returns:
+            字典列表
+
+        Raises:
+            ArrayParseError: 解析失败时抛出
+        """
+        ...
+
+
+class ArrayParseError(Exception):
+    """
+    @classdesc JSON 数组解析异常
+
+    当 JSON 数组解析失败时抛出此异常，
+    携带原始错误信息以便排查问题。
+
+    使用场景:
+    - JSON 格式非法导致解析失败
+    - 输入数据类型不匹配（期望数组/字典但收到其他类型）
+    - JSONPath 指向的路径不存在
+    """
+
+    def __init__(self, message: str, cause: Exception | None = None):
+        """
+        @methoddesc 初始化解析异常
+
+        参数:
+            message: 错误描述信息
+            cause: 原始异常对象（可选，用于异常链追踪）
+        """
+        super().__init__(message)
+        self.cause = cause
+
+    def __str__(self) -> str:
+        msg = super().__str__()
+        if self.cause:
+            msg = f"{msg} (原因: {self.cause})"
+        return msg
+
+
+class ArrayParser:
+    """
+    @classdesc JSON 数组解析器
+
+    专门处理 JSON 数组格式的解析器，支持：
+    - 标准 JSON 数组格式: [{"a": 1}, {"a": 2}]
+    - 单个对象包装格式: {"a": 1}
+    - 嵌套数组提取: {"data": [{"a": 1}, {"a": 2}]}
+
+    使用示例:
+        parser = ArrayParser()
+
+        # 解析标准数组
+        result = parser.parse('[{"a": 1}, {"a": 2}]')
+        # 返回: [{"a": 1}, {"a": 2}]
+
+        # 解析单个对象
+        result = parser.parse('{"a": 1}')
+        # 返回: [{"a": 1}]
+
+        # 检测是否可解析
+        can_parse = parser.can_parse('[{"a": 1}]')
+        # 返回: True
+    """
+
+    def can_parse(self, raw_content: str) -> bool:
+        """
+        @methoddesc 检测给定的原始内容是否为数组格式
+
+        检测逻辑:
+        1. 首先尝试 JSON 解析，检查解析结果是否为列表
+        2. 如果是字典，检查是否包含列表类型的值
+        3. 处理空白字符和常见格式错误
+
+        Args:
+            raw_content: 原始 JSON 字符串
+
+        Returns:
+            如果可以解析为数组格式返回 True，否则返回 False
+        """
+        if not raw_content or not isinstance(raw_content, str):
+            return False
+
+        stripped = raw_content.strip()
+        if not stripped:
+            return False
+
+        try:
+            parsed = json.loads(stripped)
+
+            # 直接是列表
+            if isinstance(parsed, list):
+                return True
+
+            # D8: 收紧 array 格式。仅接受"无内嵌数组的 dict"(单条记录,如 {"a":1})。
+            # 含内嵌数组的嵌套对象(如 {"data":[...]})不算 array 格式——主数据数组位置
+            # 有歧义,必须用 format=object + json_path 精确指定,不再猜测取第一个数组。
+            if isinstance(parsed, dict):
+                has_nested_list = any(isinstance(value, list) for value in parsed.values())
+                return not has_nested_list
+
+            return False
+
+        except (json.JSONDecodeError, ValueError) as e:
+            logger.debug(f"JSON 格式检测失败: {e}")
+            return False
+
+    def parse(self, raw_content: str) -> list[dict[str, Any]]:
+        """
+        @methoddesc 解析 JSON 字符串为字典列表
+
+        支持的格式:
+        1. 标准数组: [{"a": 1}, {"a": 2}] -> 返回原列表
+        2. 单个对象: {"a": 1} -> 返回包装后的列表 [{"a": 1}]
+        3. 嵌套对象: {"data": [{"a": 1}]} -> 提取内层数组
+
+        Args:
+            raw_content: 原始 JSON 字符串
+
+        Returns:
+            字典列表
+
+        Raises:
+            ArrayParseError: JSON 解析失败或格式不支持时抛出
+        """
+        if not raw_content or not isinstance(raw_content, str):
+            raise ArrayParseError("输入为空或类型错误")
+
+        stripped = raw_content.strip()
+        if not stripped:
+            raise ArrayParseError("输入内容为空")
+
+        try:
+            parsed = json.loads(stripped)
+        except json.JSONDecodeError as e:
+            raise ArrayParseError(f"JSON 解析失败 (行 {e.lineno}, 列 {e.colno}): {e.msg}", cause=e)
+        except ValueError as e:
+            raise ArrayParseError(f"JSON 格式错误: {e}", cause=e)
+
+        # 处理不同格式
+        if isinstance(parsed, list):
+            return self._parse_list(parsed)
+
+        elif isinstance(parsed, dict):
+            return self._parse_dict(parsed)
+
+        else:
+            raise ArrayParseError(f"不支持的 JSON 类型: {type(parsed).__name__}，期望列表或字典")
+
+    def _parse_list(self, data: list) -> list[dict[str, Any]]:
+        """
+        @methoddesc 解析列表数据
+
+        Args:
+            data: 解析后的列表数据
+
+        Returns:
+            字典列表
+        """
+        result: list[dict[str, Any]] = []
+
+        for item in data:
+            if isinstance(item, dict):
+                result.append(item)
+            else:
+                # 非字典类型，包装为单值对象
+                result.append({"value": item})
+
+        return result
+
+    def _parse_dict(self, data: dict) -> list[dict[str, Any]]:
+        """
+        @methoddesc 解析字典数据
+
+        D8 策略(零启发式):
+        - 含内嵌数组的嵌套对象(如 {"data":[...]})→ 报错,引导改用 format=object + json_path
+          精确指定数据数组路径(不再猜测取第一个数组)。
+        - 无内嵌数组的单条 dict(如 {"a":1})→ 返回 [data](无歧义)。
+
+        Args:
+            data: 解析后的字典数据
+
+        Returns:
+            字典列表
+
+        Raises:
+            ArrayParseError: 字典含内嵌数组(嵌套对象)时抛出
+        """
+        # D8: 含内嵌数组的嵌套对象拒绝(主数据数组位置有歧义,不应猜测)
+        has_nested_list = any(isinstance(value, list) for value in data.values())
+        if has_nested_list:
+            raise ArrayParseError(
+                "array 格式仅支持顶层数组 JSON(如 [{...}])或无内嵌数组的单条对象;"
+                "嵌套对象(含内嵌数组)请改用 format=object 并通过 json_path "
+                "(如 $.data)精确指定数据数组路径。"
+            )
+
+        # 无内嵌数组,将字典作为单条记录
+        return [data]