precis-cli 0.1.3__py3-none-any.whl

app/shared/core/data_source/specs/__init__.py

@@ -0,0 +1,128 @@
+# 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 数据源规格模块入口
+
+功能概述:
+- 统一导出各类数据源规格类（Excel、CSV、JSON、SQL）
+- 提供延迟导入和旧版名称兼容支持
+- 通过 __getattr__ 实现按需加载，避免循环导入并减少启动时间
+
+架构设计:
+- 基础类（DataSourceSpec、FileSourceSpec）直接导入
+- 具体实现类（ExcelSourceSpec 等）通过 __getattr__ 延迟导入
+- 旧版名称（ExcelSpec 等）映射到新版类，保持向后兼容
+- __all__ 显式声明公开接口，控制 from module import * 的行为
+
+输入示例:
+    from app.shared.core.data_source.specs import DataSourceSpec, ExcelSourceSpec
+    from app.shared.core.data_source.specs import create_spec  # 工厂函数
+
+    # 旧版名称仍可正常使用（兼容支持）
+    from app.shared.core.data_source.specs import ExcelSpec
+
+输出示例:
+    # create_spec 根据 type 字段自动创建对应实例
+    spec = create_spec({"type": "csv", "path": "data.csv"})
+    # 返回 CSVSourceSpec 实例
+"""
+
+from .base import (
+    DataSourceSpec,
+    create_spec,
+    get_spec_class,
+    register_source_spec,
+)
+from .file_base import FileSourceSpec
+
+
+# 延迟导入具体实现，避免循环依赖
+# 当用户首次访问这些名称时，才会执行实际导入
+def __getattr__(name: str) -> type[DataSourceSpec]:
+    """
+    @methoddesc 延迟导入具体数据源规格类
+
+    当代码访问 app.shared.core.data_source.specs.ExcelSourceSpec 等属性时，
+    此函数会被调用，执行实际的导入操作。
+
+    延迟导入的好处：
+    1. 避免循环依赖（具体子类可能引用其他模块）
+    2. 减少启动时间（只有实际使用的类才会被加载）
+    3. 内存优化（未使用的类不会占用内存）
+
+    Args:
+        name: 要访问的属性名称（如 "ExcelSourceSpec"）
+
+    Returns:
+        对应的数据源规格类
+
+    Raises:
+        AttributeError: 如果名称不是已知的规格类或旧版别名
+    """
+    if name == "ExcelSourceSpec":
+        from .excel_source import ExcelSourceSpec
+
+        return ExcelSourceSpec
+    elif name == "CSVSourceSpec":
+        from .csv_source import CSVSourceSpec
+
+        return CSVSourceSpec
+    elif name == "JSONSourceSpec":
+        from .json_source import JSONSourceSpec
+
+        return JSONSourceSpec
+    elif name == "SQLSourceSpec":
+        from .sql_source import SQLSourceSpec
+
+        return SQLSourceSpec
+    elif name in ("ExcelSpec", "CSVSpec", "JSONSpec"):
+        # 旧版名称映射到新类，保持向后兼容
+        # 这样使用旧名称的代码无需修改即可继续工作
+        if name == "ExcelSpec":
+            from .excel_source import ExcelSourceSpec
+
+            return ExcelSourceSpec
+        elif name == "CSVSpec":
+            from .csv_source import CSVSourceSpec
+
+            return CSVSourceSpec
+        elif name == "JSONSpec":
+            from .json_source import JSONSourceSpec
+
+            return JSONSourceSpec
+    # 如果名称不匹配任何已知类，抛出标准 AttributeError
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
+# 显式声明模块的公开接口
+# 控制 from app.shared.core.data_source.specs import * 时导入哪些名称
+__all__ = [
+    # 基础规格
+    "DataSourceSpec",  # 所有数据源的抽象基类
+    "FileSourceSpec",  # 文件数据源的抽象基类
+    # 旧版规格（兼容）
+    "ExcelSpec",
+    "CSVSpec",
+    "JSONSpec",
+    # 新版规格（延迟加载）
+    "ExcelSourceSpec",  # Excel 数据源规格
+    "CSVSourceSpec",  # CSV 数据源规格
+    "JSONSourceSpec",  # JSON 数据源规格
+    "SQLSourceSpec",  # SQL 数据源规格
+    # 注册函数
+    "register_source_spec",  # 装饰器：注册数据源规格类
+    "get_spec_class",  # 根据类型获取规格类
+    "create_spec",  # 工厂函数：根据字典创建规格实例
+]

app/shared/core/data_source/specs/base.py

@@ -0,0 +1,258 @@
+# 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 数据源规范基类模块
+
+功能概述:
+- 提供所有数据源配置的抽象基类 DataSourceSpec
+- 使用 Pydantic 进行配置验证和类型约束
+- 支持多态反序列化（通过 discriminator 字段）
+- 提供缓存、超时等通用配置字段
+
+架构设计:
+- 抽象基类模式（ABC + BaseModel）
+- 子类必须设置 source_type 类属性并通过装饰器注册
+- model_validator 自动校验 type 与 source_type 一致性
+- 与 DataSourceLoader 形成规格-加载器配对关系
+
+输入示例:
+    @register_source_spec
+    class JSONSourceSpec(FileSourceSpec):
+        source_type: ClassVar[str] = "json"
+        type: str = "json"
+        path: str = "data.json"
+
+输出示例:
+    spec = DataSourceSpec.model_validate({"type": "json", "path": "data.json"})
+    # 自动反序列化为 JSONSourceSpec 实例
+    key = spec.get_connection_key()   # 返回连接标识（用于缓存）
+"""
+
+from __future__ import annotations
+
+import builtins
+from abc import ABC, abstractmethod
+from typing import Any, ClassVar, Self
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class DataSourceSpec(BaseModel, ABC):
+    """
+    @classdesc 数据源规范抽象基类
+
+    所有数据源配置（文件、数据库、API等）的基类。
+    子类必须设置 source_type 类属性，并通过装饰器注册。
+
+    属性说明:
+        source_type: 类级别的类型标识，用于反序列化时识别类型
+        type: 实例级别的类型字段，必须与 source_type 保持一致
+        name: 数据源的显示名称（可选）
+        description: 数据源的描述信息（可选）
+        cache_enabled: 是否启用数据缓存，默认 True
+        cache_ttl: 缓存有效期（秒），默认 300 秒（5分钟）
+        timeout_seconds: 数据加载超时时间（秒），默认 30 秒
+
+    示例:
+        @register_source_spec
+        class JSONSourceSpec(FileSourceSpec):
+            source_type: ClassVar[str] = "json"
+            type: str = "json"
+            # ... 其他字段
+    """
+
+    # 类级别的类型标识，用于反序列化时识别类型
+    source_type: ClassVar[str] = "abstract"
+
+    # 实例级别的类型字段
+    type: str = Field(..., description="数据源类型标识")
+
+    # 通用字段（所有数据源都有）
+    name: str | None = Field(None, description="数据源显示名称")
+    description: str | None = Field(None, description="数据源描述")
+
+    # 缓存和性能配置
+    cache_enabled: bool = Field(True, description="是否启用缓存")
+    cache_ttl: int = Field(300, ge=0, description="缓存有效期（秒）")
+
+    # 超时配置
+    timeout_seconds: int = Field(30, ge=1, description="加载超时时间（秒）")
+
+    @model_validator(mode="after")
+    def validate_type_match(self) -> Self:
+        """
+        @methoddesc 验证实例类型与声明的 type 字段一致
+
+        这是为了防止配置文件中声明的类型与实际类不匹配。
+        例如：配置写 type="excel"，但实际解析成 CSVSourceSpec 就会报错。
+
+        Raises:
+            ValueError: 当 self.type 与 self.source_type 不一致时抛出
+
+        Returns:
+            验证通过后的实例自身（遵循 Pydantic 验证器约定）
+        """
+        if self.type != self.source_type:
+            raise ValueError(f"类型不匹配: 声明为 '{self.type}'，但类定义为 '{self.source_type}'")
+        return self
+
+    @abstractmethod
+    def get_connection_key(self) -> str:
+        """
+        @methoddesc 获取连接标识符（用于缓存键）
+
+        每个数据源实例应有唯一的连接标识。
+        例如：
+        - 文件：绝对路径
+        - 数据库：connection_url + table
+
+        Returns:
+            连接标识字符串，用于在缓存中唯一标识该数据源
+        """
+        pass
+
+    @abstractmethod
+    def get_loader_class(self) -> builtins.type[DataSourceLoader]:
+        """
+        @methoddesc 获取对应的加载器类
+
+        子类需要返回对应的数据加载器类（如 CSVLoader、ExcelLoader 等）。
+        采用延迟导入（在方法内部 import）以避免循环依赖。
+
+        Returns:
+            DataSourceLoader 的子类，负责实际的数据读取工作
+        """
+        pass
+
+    def get_discriminator_value(self) -> str:
+        """
+        @methoddesc 获取类型标识符（用于加载器注册表）
+
+        默认返回 source_type，子类可以覆盖。
+        该值用于在反序列化时识别应该创建哪个子类的实例。
+
+        Returns:
+            类型标识字符串（如 "csv"、"excel"、"sql"）
+        """
+        return self.source_type
+
+    def to_display_dict(self) -> dict[str, Any]:
+        """
+        @methoddesc 转换为显示用的字典（去除敏感信息）
+
+        用于前端展示或日志记录，避免暴露密码等敏感字段。
+        子类应通过 super().to_display_dict() 复用基类字段。
+
+        Returns:
+            包含安全字段的字典，至少包含 type、name、source_type
+        """
+        return {
+            "type": self.type,
+            "name": self.name,
+            "source_type": self.source_type,
+        }
+
+
+# 用于 Pydantic 多态反序列化的类型映射
+# 键是数据源类型标识（如 "csv"），值是对应的 Spec 类
+# 通过 @register_source_spec 装饰器自动填充
+SOURCE_SPEC_REGISTRY: dict[str, type[DataSourceSpec]] = {}
+
+
+def register_source_spec(spec_class: type[DataSourceSpec]) -> type[DataSourceSpec]:
+    """
+    @methoddesc 装饰器：注册数据源规范类
+
+    用法:
+        @register_source_spec
+        class JSONSourceSpec(FileSourceSpec):
+            source_type = "json"
+            ...
+
+    注册后，该类型会被加入 SOURCE_SPEC_REGISTRY，
+    从而支持通过 create_spec() 根据 type 字段自动创建对应实例。
+
+    Args:
+        spec_class: 数据源规范类，必须定义 source_type 类属性
+
+    Returns:
+        原类（装饰器模式，不改变类本身）
+
+    Raises:
+        ValueError: 如果类没有 source_type 属性，或 source_type 为 "abstract"
+    """
+    # 检查是否定义了 source_type 类属性
+    if not hasattr(spec_class, "source_type"):
+        raise ValueError(f"{spec_class.__name__} 必须定义 source_type 类属性")
+
+    # 禁止将抽象基类注册到注册表
+    if spec_class.source_type == "abstract":
+        raise ValueError(f"{spec_class.__name__} 的 source_type 不能为 'abstract'")
+
+    # 将类注册到全局字典中，键为 source_type 的值
+    SOURCE_SPEC_REGISTRY[spec_class.source_type] = spec_class
+    return spec_class
+
+
+def get_spec_class(source_type: str) -> type[DataSourceSpec] | None:
+    """
+    @methoddesc 根据类型标识获取对应的 Spec 类
+
+    用于在反序列化时查找对应的类，或判断某种类型是否被支持。
+
+    Args:
+        source_type: 数据源类型标识（如 "excel", "json", "csv", "sql"）
+
+    Returns:
+        Spec 类，或 None（如果该类型未注册）
+    """
+    return SOURCE_SPEC_REGISTRY.get(source_type)
+
+
+def create_spec(source_dict: dict[str, Any]) -> DataSourceSpec:
+    """
+    @methoddesc 根据字典创建对应的 Spec 实例
+
+    这是多态反序列化的入口：根据字典中的 "type" 字段，
+    自动查找并实例化对应的 Spec 子类。
+
+    Args:
+        source_dict: 包含 type 字段的配置字典，其他字段取决于具体子类
+
+    Returns:
+        DataSourceSpec 子类的实例
+
+    Raises:
+        ValueError: 缺少 type 字段，或 type 对应的类型未注册
+    """
+    # 从字典中提取类型标识
+    source_type = source_dict.get("type")
+    if not source_type:
+        raise ValueError("配置字典必须包含 'type' 字段")
+
+    # 查找对应的数据源规格类
+    spec_class = get_spec_class(source_type)
+    if not spec_class:
+        raise ValueError(f"未知的数据源类型: '{source_type}'。支持的类型: {list(SOURCE_SPEC_REGISTRY.keys())}")
+
+    # 使用 Pydantic 模型解析字典，自动进行类型校验和转换
+    return spec_class(**source_dict)
+
+
+# 延迟导入，避免循环依赖
+# DataSourceLoader 在加载时会引用 DataSourceSpec，
+# 如果在这里顶层导入会导致循环导入问题
+from ..loaders.base import DataSourceLoader

app/shared/core/data_source/specs/csv_source.py

@@ -0,0 +1,137 @@
+# 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 CSV 数据源规范模块
+
+功能概述:
+- 定义 CSV 文件的数据源规格类
+- 支持自定义分隔符、引号字符、转义字符
+- 提供自动编码检测和编码回退机制
+- 支持坏行处理策略（error/warn/skip）
+
+架构设计:
+- 继承自 FileSourceSpec，复用文件通用配置
+- 通过 @register_source_spec 装饰器自动注册到规格注册表
+- 与 CSVLoader 配对使用，实现 CSV 数据加载
+- Pydantic Field 提供默认值和校验约束
+
+输入示例:
+    spec = CSVSourceSpec(
+        path="data/users.csv",
+        delimiter=",",
+        quotechar='"',
+        encoding="utf-8",
+        encoding_detection=True,
+        on_bad_lines="error"
+    )
+
+输出示例:
+    loader_class = spec.get_loader_class()   # 返回 CSVLoader
+    display = spec.to_display_dict()
+    # {"path": "data/users.csv", "delimiter": ",", "encoding": "utf-8", ...}
+"""
+
+from __future__ import annotations
+
+import builtins
+from typing import TYPE_CHECKING, Any, ClassVar, Literal
+
+if TYPE_CHECKING:
+    from ..loaders.base import DataSourceLoader
+
+from pydantic import Field
+
+from .base import register_source_spec
+from .file_base import FileSourceSpec
+
+
+@register_source_spec
+class CSVSourceSpec(FileSourceSpec):
+    """
+    @classdesc CSV 数据源配置
+
+    支持标准 CSV（逗号分隔值）文件，提供自动编码检测功能。
+    CSV 是纯文本格式，每行是一条记录，字段之间用分隔符隔开。
+
+    特有配置:
+        delimiter: 字段分隔符（默认逗号），也可以是分号、制表符等
+        quotechar: 引号字符（默认双引号），用于包裹包含分隔符的字段
+        escapechar: 转义字符，用于转义引号等特殊字符
+        encoding_detection: 是否自动检测编码（通过 chardet 等库）
+        fallback_encodings: 编码检测失败时依次尝试的编码列表
+        on_bad_lines: 遇到格式错误的行时的处理方式
+
+    示例:
+        ```yaml
+        source:
+          type: csv
+          path: data/users.csv
+          delimiter: ","
+          encoding: utf-8
+        ```
+    """
+
+    source_type: ClassVar[str] = "csv"
+    type: str = "csv"
+
+    # CSV 特有配置
+    delimiter: str = Field(",", min_length=1, max_length=1, description="字段分隔符（如逗号、分号、制表符）")
+    quotechar: str = Field('"', min_length=1, max_length=1, description="引号字符（用于包裹包含特殊字符的字段）")
+    escapechar: str | None = Field(None, description="转义字符（用于转义引号等）")
+
+    # 编码处理
+    encoding_detection: bool = Field(True, description="是否自动检测编码（检测失败时使用 fallback_encodings）")
+    fallback_encodings: list[str] = Field(
+        default_factory=lambda: ["utf-8", "gbk", "latin1"],
+        description="编码检测失败时尝试的编码列表（按优先级排序）",
+    )
+
+    # 错误处理
+    # 默认 error（校验工具红线：字段数超表头的坏行静默跳过=漏报，用户在"缺行"
+    # 的数据上看到全绿；warn/skip 是显式 opt-in 的容忍行为）
+    on_bad_lines: Literal["error", "warn", "skip"] = Field(
+        "error", description="遇到坏行的处理方式：error-报错（默认，fail-closed）, warn-警告并跳过, skip-静默跳过"
+    )
+
+    def get_loader_class(self) -> builtins.type[DataSourceLoader]:
+        """
+        @methoddesc 获取 CSV 数据加载器类
+
+        延迟导入 CSVLoader，避免循环依赖。
+        CSVLoader 负责调用 pandas.read_csv 读取数据。
+
+        Returns:
+            CSVLoader 类
+        """
+        from ..loaders.csv_loader import CSVLoader
+
+        return CSVLoader
+
+    def to_display_dict(self) -> dict[str, Any]:
+        """
+        @methoddesc 转换为显示用的字典
+
+        在基类的基础上增加 CSV 特有的展示字段，
+        使用 repr() 显示分隔符以便区分空格等特殊字符。
+
+        Returns:
+            包含 delimiter、encoding 等 CSV 特有字段的字典
+        """
+        return {
+            **super().to_display_dict(),
+            "delimiter": repr(self.delimiter),  # 使用 repr 显示特殊字符
+            "encoding": self.encoding,
+        }

app/shared/core/data_source/specs/excel_source.py

@@ -0,0 +1,141 @@
+# 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 Excel 数据源规范模块
+
+功能概述:
+- 定义 Excel 文件的数据源规格类
+- 支持 .xlsx 和 .xls 格式
+- 提供工作表名称/索引选择和读取引擎配置
+- 支持数据类型自动推断开关
+
+架构设计:
+- 继承自 FileSourceSpec，复用文件通用配置
+- 通过 @register_source_spec 装饰器自动注册到规格注册表
+- 与 ExcelLoader 配对使用，实现 Excel 数据加载
+- 连接键包含文件路径和工作表信息，确保唯一性
+
+输入示例:
+    spec = ExcelSourceSpec(
+        path="data/users.xlsx",
+        sheet="Sheet1",
+        sheet_index=0,
+        engine="openpyxl",
+        dtype_inference=True
+    )
+
+输出示例:
+    key = spec.get_connection_key()       # "absolute_path#Sheet1"
+    loader_class = spec.get_loader_class()  # 返回 ExcelLoader
+    display = spec.to_display_dict()
+    # {"path": "data/users.xlsx", "sheet": "Sheet1", "engine": "openpyxl", ...}
+"""
+
+from __future__ import annotations
+
+import builtins
+from typing import TYPE_CHECKING, Any, ClassVar, Literal
+
+if TYPE_CHECKING:
+    from ..loaders.base import DataSourceLoader
+
+from pydantic import Field
+
+from .base import register_source_spec
+from .file_base import FileSourceSpec
+
+
+@register_source_spec
+class ExcelSourceSpec(FileSourceSpec):
+    """
+    @classdesc Excel 数据源配置
+
+    支持 .xlsx（Excel 2007+）和 .xls（Excel 97-2003）格式的 Excel 文件。
+    Excel 文件可以包含多个工作表（sheet），需要指定读取哪个工作表。
+
+    特有配置:
+        sheet: 工作表名称（如 "Sheet1"），默认 None（使用 sheet_index）
+        sheet_index: 工作表索引（从0开始），当 sheet 未指定时使用
+        engine: 读取引擎，openpyxl 支持 .xlsx，xlrd 支持 .xls
+        dtype_inference: 是否自动推断数据类型（如将数字字符串转为数值）
+
+    示例:
+        ```yaml
+        source:
+          type: excel
+          path: data/users.xlsx
+          sheet: Sheet1
+          header_row: 0
+        ```
+    """
+
+    source_type: ClassVar[str] = "excel"
+    type: str = "excel"
+
+    # Excel 特有配置
+    sheet: str | None = Field(None, description="工作表名称（优先使用）；如果为 None，则使用 sheet_index")
+    sheet_index: int = Field(0, ge=0, description="工作表索引（从0开始），当 sheet 未指定时使用")
+    engine: Literal["openpyxl", "xlrd"] = Field(
+        "openpyxl", description="读取引擎：openpyxl（支持 .xlsx）或 xlrd（支持 .xls）"
+    )
+
+    # 数据类型推断
+    dtype_inference: bool = Field(True, description="是否自动推断数据类型（如 '123' 转为整数 123）")
+
+    def get_connection_key(self) -> str:
+        """
+        @methoddesc 获取连接标识符
+
+        Excel 的连接键由文件路径和工作表信息组合而成，
+        确保同一个文件的不同工作表被视为不同的数据源。
+
+        Returns:
+            "文件绝对路径#工作表名称" 格式的字符串
+        """
+        base_key = super().get_connection_key()  # 获取文件绝对路径
+        # 如果指定了 sheet 名称则使用，否则使用 sheet_index
+        sheet = self.sheet or f"sheet_{self.sheet_index}"
+        return f"{base_key}#{sheet}"
+
+    def get_loader_class(self) -> builtins.type[DataSourceLoader]:
+        """
+        @methoddesc 获取 Excel 数据加载器类
+
+        延迟导入 ExcelLoader，避免循环依赖。
+        ExcelLoader 负责调用 pandas.read_excel 读取数据。
+
+        Returns:
+            ExcelLoader 类
+        """
+        from ..loaders.excel_loader import ExcelLoader
+
+        return ExcelLoader
+
+    def to_display_dict(self) -> dict[str, Any]:
+        """
+        @methoddesc 转换为显示用的字典
+
+        在基类的基础上增加 Excel 特有的展示字段。
+        如果未指定 sheet 名称，则显示为 "sheet_索引" 形式。
+
+        Returns:
+            包含 sheet、engine 等 Excel 特有字段的字典
+        """
+        return {
+            **super().to_display_dict(),
+            "sheet": self.sheet or f"sheet_{self.sheet_index}",
+            "engine": self.engine,
+        }