precis-cli 0.1.3__py3-none-any.whl

app/shared/core/project/schema/types_parts/source_options.py

@@ -0,0 +1,347 @@
+# 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 数据源格式选项模块
+
+功能概述:
+- 定义不同数据源格式的特定配置选项
+- 实现 FormatOptions 联合类型
+- 支持 JSON、CSV、Excel 等格式的特定配置
+
+架构设计:
+- JSONOptions: JSON 格式配置（format, json_path, sep, dtype）
+- CSVOptions: CSV 格式配置（delimiter, encoding, quote_char）
+- ExcelOptions: Excel 格式配置（暂无特有选项）
+- FormatOptions: 联合类型，通过 Union 实现多态
+
+输入示例 (schema.yaml):
+    # JSON 格式选项
+    source:
+      path: data/users.json
+      options:
+        format: auto
+        json_path: "$.data.items"
+        sep: "."
+
+    # CSV 格式选项
+    source:
+      path: data/users.csv
+      options:
+        delimiter: ","
+        encoding: utf-8
+        skip_rows: 0
+
+    # Excel 格式选项
+    source:
+      path: data/users.xlsx
+      options:
+        engine: openpyxl
+        dtype_inference: true
+
+输出示例:
+    # JSON 格式选项
+    JSONOptions(format="auto", json_path="$.data.items", sep=".")
+
+    # CSV 格式选项
+    CSVOptions(delimiter=",", encoding="utf-8", skip_rows=0)
+
+    # Excel 格式选项
+    ExcelOptions(engine="openpyxl", dtype_inference=True)
+
+    # 联合类型使用
+    SourceSpec(
+        mode="relative_file",
+        path="data/users.json",
+        options=JSONOptions(format="array")
+    )
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class JSONOptions(BaseModel):
+    """@classdesc JSON 格式选项
+
+    包含 JSON 数据源的特定配置。
+
+    字段说明:
+        - format: JSON 格式类型
+            - auto: 自动检测
+            - array: 对象数组格式
+            - lines: JSON Lines 格式
+            - object: 嵌套对象格式
+        - json_path: JSONPath 提取路径
+        - record_path: 要展平的路径
+        - meta_prefix: 元数据字段前缀
+        - sep: 嵌套对象展平时的分隔符
+        - dtype: 列类型指定
+
+    输入示例:
+        options:
+          format: object
+          json_path: "$.data.items"
+          sep: "."
+
+    输出示例:
+        JSONOptions(
+            format="object",
+            json_path="$.data.items",
+            sep="."
+        )
+    """
+
+    format: Literal["array", "lines", "object"] = Field(
+        ..., description="JSON 格式类型(必填):array-顶层数组, lines-JSON Lines, object-嵌套对象(需 json_path)"
+    )
+
+    json_path: str | None = Field(None, description="JSONPath 提取路径，如 '$.data.items'（用于从嵌套对象提取数组）")
+
+    record_path: str | None = Field(None, description="要展平的路径，如 'items'（用于数组字段）")
+
+    meta_prefix: str = Field("meta.", description="元数据字段前缀")
+
+    sep: str = Field(".", description="嵌套对象展平时的分隔符")
+
+    dtype: dict[str, str] | None = Field(None, description="列类型指定，如 {'id': 'str', 'count': 'int'}")
+
+    flatten: bool = Field(False, description="是否自动扁平化嵌套结构")
+
+    def to_loader_config(self) -> dict[str, Any]:
+        """@methoddesc 转换为加载器配置字典
+
+        将 JSONOptions 对象转换为数据加载器可识别的配置字典。
+        加载器使用这些参数来正确解析 JSON 文件。
+
+        返回:
+            包含 type、format、json_path 等键的字典
+
+        示例:
+            >>> opts = JSONOptions(format="array", json_path="$.data")
+            >>> opts.to_loader_config()
+            {'type': 'json', 'format': 'array', 'json_path': '$.data', ...}
+        """
+        return {
+            "type": "json",
+            "format": self.format,
+            "json_path": self.json_path,
+            "record_path": self.record_path,
+            "meta_prefix": self.meta_prefix,
+            "sep": self.sep,
+            "dtype": self.dtype,
+            "flatten": self.flatten,
+        }
+
+
+class CSVOptions(BaseModel):
+    """@classdesc CSV 格式选项
+
+    包含 CSV 数据源的特定配置。
+
+    字段说明:
+        - delimiter: 字段分隔符（默认逗号）
+        - quotechar: 引号字符（默认双引号）
+        - escapechar: 转义字符
+        - encoding: 文件编码（默认 utf-8）
+        - skip_rows: 跳过的行数
+        - on_bad_lines: 遇到坏行的处理方式
+
+    输入示例:
+        options:
+          delimiter: ","
+          encoding: utf-8
+          skip_rows: 0
+
+    输出示例:
+        CSVOptions(
+            delimiter=",",
+            encoding="utf-8",
+            skip_rows=0
+        )
+    """
+
+    delimiter: str = Field(",", description="字段分隔符")
+
+    quotechar: str = Field('"', description="引号字符")
+
+    escapechar: str | None = Field(None, description="转义字符")
+
+    encoding: str = Field("utf-8", description="文件编码")
+
+    skip_rows: int = Field(0, ge=0, description="跳过的行数")
+
+    # 默认 error（校验工具红线：坏行静默跳过=漏报；warn/skip 为显式 opt-in，
+    # 与 CSVSourceSpec.on_bad_lines 默认值保持一致，标准/分块两路径同口径）
+    on_bad_lines: Literal["error", "warn", "skip"] = Field(
+        "error", description="遇到坏行的处理方式：error-报错（默认，fail-closed）, warn-警告并跳过, skip-静默跳过"
+    )
+
+    def to_loader_config(self) -> dict[str, Any]:
+        """@methoddesc 转换为加载器配置字典
+
+        将 CSVOptions 对象转换为数据加载器可识别的配置字典。
+        加载器使用这些参数来正确解析 CSV 文件。
+
+        返回:
+            包含 type、delimiter、encoding 等键的字典
+
+        示例:
+            >>> opts = CSVOptions(delimiter=";", encoding="gbk")
+            >>> opts.to_loader_config()
+            {'type': 'csv', 'delimiter': ';', 'encoding': 'gbk', ...}
+        """
+        return {
+            "type": "csv",
+            "delimiter": self.delimiter,
+            "quotechar": self.quotechar,
+            "escapechar": self.escapechar,
+            "encoding": self.encoding,
+            "skip_rows": self.skip_rows,
+            "on_bad_lines": self.on_bad_lines,
+        }
+
+
+class ExcelOptions(BaseModel):
+    """@classdesc Excel 格式选项
+
+    包含 Excel 数据源的特定配置。
+
+    字段说明:
+        - engine: 读取引擎（openpyxl 或 xlrd）
+        - dtype_inference: 是否自动推断数据类型
+
+    输入示例:
+        options:
+          engine: openpyxl
+          dtype_inference: true
+
+    输出示例:
+        ExcelOptions(
+            engine="openpyxl",
+            dtype_inference=True
+        )
+    """
+
+    engine: Literal["openpyxl", "xlrd"] = Field("openpyxl", description="读取引擎")
+
+    dtype_inference: bool = Field(True, description="是否自动推断数据类型")
+
+    def to_loader_config(self) -> dict[str, Any]:
+        """@methoddesc 转换为加载器配置字典
+
+        将 ExcelOptions 对象转换为数据加载器可识别的配置字典。
+        加载器使用这些参数来正确解析 Excel 文件。
+
+        返回:
+            包含 type、engine、dtype_inference 等键的字典
+
+        示例:
+            >>> opts = ExcelOptions(engine="openpyxl")
+            >>> opts.to_loader_config()
+            {'type': 'excel', 'engine': 'openpyxl', 'dtype_inference': True}
+        """
+        return {
+            "type": "excel",
+            "engine": self.engine,
+            "dtype_inference": self.dtype_inference,
+        }
+
+
+# 格式选项联合类型
+# 使用联合类型实现多态，支持不同格式的特定配置
+# 这意味着一个变量可以是 JSONOptions、CSVOptions 或 ExcelOptions 中的任意一种
+FormatOptions = JSONOptions | CSVOptions | ExcelOptions
+
+
+def create_format_options(file_ext: str, options_dict: dict | None = None) -> FormatOptions | None:
+    """@methoddesc 根据文件扩展名创建对应的格式选项对象
+
+    本函数是格式选项的工厂方法，根据文件扩展名自动选择正确的选项类，
+    并将配置字典转换为对应的 Pydantic 模型对象。
+
+    参数说明:
+        :param file_ext: 文件扩展名，支持以下格式：
+            - ".json", ".jsonl", ".ndjson" -> JSONOptions
+            - ".csv" -> CSVOptions
+            - ".xlsx", ".xls" -> ExcelOptions
+        :param options_dict: 选项配置字典（来自 schema.yaml 的 options 字段）
+        :return: 对应格式的选项对象，如果扩展名不支持或 options_dict 为空则返回 None
+
+    示例:
+        >>> # 创建 JSON 选项
+        >>> opts = create_format_options('.json', {'format': 'array', 'json_path': '$.data'})
+        >>> type(opts).__name__
+        'JSONOptions'
+
+        >>> # 创建 CSV 选项
+        >>> opts = create_format_options('.csv', {'delimiter': ';', 'encoding': 'gbk'})
+        >>> type(opts).__name__
+        'CSVOptions'
+
+        >>> # 无配置时返回 None
+        >>> opts = create_format_options('.json', None)
+        >>> opts is None
+        True
+    """
+    # 如果未提供配置字典，直接返回 None（表示使用默认配置）
+    if not options_dict:
+        return None
+
+    # 将扩展名统一转为小写，保证大小写不敏感匹配
+    ext = file_ext.lower()
+
+    # 根据扩展名创建对应的格式选项对象
+    # JSON 格式（包括标准 JSON、JSON Lines、Newline Delimited JSON）
+    if ext in (".json", ".jsonl", ".ndjson"):
+        return JSONOptions(**options_dict)
+    # CSV 格式
+    elif ext == ".csv":
+        return CSVOptions(**options_dict)
+    # Excel 格式（包括 .xlsx 和 .xls）
+    elif ext in (".xlsx", ".xls"):
+        return ExcelOptions(**options_dict)
+
+    # 不支持的扩展名，返回 None
+    return None
+
+
+def get_options_type(options: FormatOptions | None) -> str:
+    """@methoddesc 获取格式选项的类型名称
+
+    用于调试和日志记录，快速判断一个 FormatOptions 对象具体是哪种类型。
+
+    参数说明:
+        :param options: 格式选项对象（JSONOptions / CSVOptions / ExcelOptions）
+        :return: 类型名称字符串
+            - "JSONOptions" - JSON 格式选项
+            - "CSVOptions" - CSV 格式选项
+            - "ExcelOptions" - Excel 格式选项
+            - "None" - 空值
+
+    示例:
+        >>> get_options_type(JSONOptions(format="array"))
+        'JSONOptions'
+        >>> get_options_type(None)
+        'None'
+    """
+    # 如果 options 为 None，直接返回 "None"
+    if options is None:
+        return "None"
+    # 使用 Python 内置的 type() 函数获取对象的类名
+    return type(options).__name__

app/shared/core/project/schema/types_parts/table.py

@@ -0,0 +1,230 @@
+# 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 表结构类型定义模块
+
+功能概述:
+- 定义 Schema 文件的主要结构 (TableSchemaFile)
+- 包含表 ID、名称、列定义、约束、数据源等
+
+架构设计:
+- 主模型: TableSchemaFile 是 schema.yaml 解析后的根对象
+- 验证: 自动检查列 ID/name 唯一性、约束 ID 唯一性
+- 兼容性: source.sheet 和 sheet 字段互斥
+
+输入示例 (schema.yaml):
+    version: 2
+    id: sc_xxxencodedid
+    name: 用户表
+    source:
+      path: data/users.xlsx
+      sheet: Sheet1
+      header_row: 0
+    columns:
+      - id: col_1
+        name: id
+        type: integer
+        primary_key: true
+      - id: col_2
+        name: username
+        type: string
+        nullable: false
+    constraints:
+      - id: not_null_username
+        type: NotNull
+        column: username
+
+输出示例:
+    TableSchemaFile(
+        version=2,
+        id="sc_xxxencodedid",
+        name="用户表",
+        source=SourceSpec(path="data/users.xlsx", sheet="Sheet1", header_row=0),
+        columns=[
+            ColumnSpec(id="col_1", name="id", type="integer", primary_key=True),
+            ColumnSpec(id="col_2", name="username", type="string", nullable=False)
+        ],
+        constraints=[
+            ConstraintItem(id="not_null_username", type="NotNull", column="username")
+        ],
+        script_checks=[]
+    )
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field, model_validator
+
+from app.shared.core.project.schema.types_parts.column import ColumnSpec
+from app.shared.core.project.schema.types_parts.constraint import ConstraintItem
+from app.shared.core.project.schema.types_parts.source import SourceSpec
+
+
+class TableSchemaFile(BaseModel):
+    """@classdesc 表结构文件模型
+
+    这是一个 schema.yaml 文件解析后的根对象。
+
+    字段说明:
+        - version: 配置文件版本，固定为 2
+        - id: 表的唯一标识符 (系统生成或手动指定)
+        - name: 表的展示名称 (用于 UI 显示和校验错误提示)
+        - source: 数据源描述 (可选，不提供时自动发现)
+        - sheet: Excel 工作表名 (与 source.sheet 互斥)
+        - columns: 列定义列表
+        - constraints: 内嵌约束列表 (可直接在 schema 中定义)
+        - script_checks: 脚本化检查列表
+
+    数据校验:
+        - 列 ID 唯一性: 所有 columns.id 必须唯一
+        - 列名唯一性: 所有 columns.name 必须唯一
+        - 约束 ID 唯一性: 所有 constraints.id 必须唯一
+        - sheet 一致性: source.sheet 和 sheet 字段不能同时指定且不同
+
+    示例:
+        # 最小配置
+        id: users
+        name: 用户表
+        columns:
+          - id: col_1
+            name: id
+            type: integer
+    """
+
+    version: int = Field(2, description="配置版本号（固定为 2）")
+    id: str = Field(..., description="表 ID（稳定标识）")
+    name: str = Field(..., description="表名（展示/校验/数据文件发现使用）")
+    source: SourceSpec | None = Field(None, description="数据源描述（为空时根据 name 自动发现）")
+    sheet: str | None = Field(None, description="Excel 工作表名称")
+    columns: list[ColumnSpec] = Field(default_factory=list, description="列定义列表")
+    constraints: list[ConstraintItem] = Field(
+        default_factory=list,
+        description="内嵌约束列表（可直接在 schema.yaml 中定义，无需独立文件）",
+    )
+    script_checks: list[dict[str, Any]] = Field(default_factory=list, description="脚本化检查")
+
+    @model_validator(mode="after")
+    def _validate_source_sheet_compatibility(self) -> TableSchemaFile:
+        """@methoddesc 验证 source.sheet 和 sheet 字段的一致性
+
+        业务规则：
+        - source.sheet 和 sheet 字段表示同一个含义（Excel 工作表名）
+        - 如果两者同时指定且值不同，会导致歧义，不知道以哪个为准
+        - 校验逻辑：如果同时存在且不一致，抛出 ValueError
+
+        为什么需要这个校验？
+        - 防止用户在两个地方写了不同的工作表名，导致数据读取错误
+        - 建议：优先使用 source.sheet，sheet 字段为兼容保留
+
+        示例:
+            # 合法：只在一个地方声明
+            source:
+              sheet: Sheet1
+
+            # 合法：两处声明一致
+            source:
+              sheet: Sheet1
+            sheet: Sheet1
+
+            # 非法：两处声明不一致（会抛出 ValueError）
+            source:
+              sheet: Sheet1
+            sheet: Sheet2
+        """
+        if self.source and self.sheet:
+            source_sheet = self.source.sheet
+            if source_sheet and source_sheet != self.sheet:
+                raise ValueError(
+                    f"source.sheet ('{source_sheet}') 与 sheet ('{self.sheet}') 不一致。请只在一个位置声明 sheet 名称。"
+                )
+        return self
+
+    @model_validator(mode="after")
+    def _validate_columns_unique(self) -> TableSchemaFile:
+        """@methoddesc 验证列 ID 和列名的唯一性
+
+        业务规则：
+        - 同一表内的所有列 ID 必须唯一（用于内部引用）
+        - 同一表内的所有列名必须唯一（用于数据访问和展示）
+
+        校验逻辑：
+        1. 提取所有列的 id 列表
+        2. 使用 set 去重后比较长度，如果不相等说明有重复
+        3. 同样方式检查 name 列表
+
+        为什么需要这个校验？
+        - 列 ID 用于约束和正则节点中引用列，重复会导致引用歧义
+        - 列名用于数据加载时的列识别，重复会导致数据覆盖
+
+        示例:
+            # 合法：列 ID 和列名都唯一
+            columns:
+              - id: col_1, name: id
+              - id: col_2, name: name
+
+            # 非法：列 ID 重复（会抛出 ValueError）
+            columns:
+              - id: col_1, name: id
+              - id: col_1, name: name
+
+            # 非法：列名重复（会抛出 ValueError）
+            columns:
+              - id: col_1, name: email
+              - id: col_2, name: email
+        """
+        ids = [c.id for c in self.columns]
+        if len(set(ids)) != len(ids):
+            raise ValueError("columns.id 必须唯一")
+
+        names = [c.name for c in self.columns]
+        if len(set(names)) != len(names):
+            raise ValueError("columns.name 必须唯一")
+
+        return self
+
+    @model_validator(mode="after")
+    def _validate_constraints_unique(self) -> TableSchemaFile:
+        """@methoddesc 验证约束 ID 的唯一性
+
+        业务规则：
+        - 同一表内的所有约束 ID 必须唯一
+
+        校验逻辑：
+        1. 提取所有约束的 id 列表
+        2. 使用 set 去重后比较长度，如果不相等说明有重复
+
+        为什么需要这个校验？
+        - 约束 ID 用于错误报告中标识具体的约束规则
+        - 重复的约束 ID 会导致无法区分是哪个约束触发了错误
+
+        示例:
+            # 合法：约束 ID 唯一
+            constraints:
+              - id: not_null_email, type: NotNull, column: email
+              - id: unique_name, type: Unique, columns: [name]
+
+            # 非法：约束 ID 重复（会抛出 ValueError）
+            constraints:
+              - id: check_email, type: NotNull, column: email
+              - id: check_email, type: Unique, column: email
+        """
+        constraint_ids = [c.id for c in self.constraints]
+        if len(set(constraint_ids)) != len(constraint_ids):
+            raise ValueError("constraints.id 必须唯一")
+
+        return self