precis-cli 0.1.3__py3-none-any.whl

app/shared/domain/schema/builder.py

@@ -0,0 +1,223 @@
+# 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 类型构建器
+
+功能概述:
+- 提供从配置文件构建数据类型实例的工厂函数
+- 管理类型注册表（TYPE_REGISTRY）
+
+架构设计:
+- 类型注册表: 将配置中的类型名称映射到 Python 类型对象
+- 工厂函数: build_type_from_config 根据配置递归构建 DataType 实例
+
+约束注册表已迁移至 app.shared.core.project.constraint.registry
+"""
+
+from typing import Any, cast
+
+# 1. 项目内部导入
+from app.shared.domain.data_types import (
+    BooleanType,
+    CompositeConditionType,
+    DataType,
+    DateType,
+    DecimalType,
+    ExpressionType,
+    ExtractedType,
+    FloatType,
+    IntegerType,
+    JsonArrayType,
+    JsonNullType,
+    JsonObjectType,
+    SequenceType,
+    StringType,
+)
+from app.shared.domain.expression_system import (
+    ExpressionRegistry,
+)
+
+# ============================================================================
+# 类型注册表
+# ============================================================================
+# 将配置中的类型名称映射到 Python 类型对象
+# 使用示例：
+#   "int" -> IntegerType()
+#   "string" -> StringType()
+#   "Expr" -> ExpressionType (类，非实例)
+
+TYPE_REGISTRY: dict[str, Any] = {
+    "Int": IntegerType(),
+    "Str": StringType(),
+    "Float": FloatType(),
+    "Decimal": DecimalType(),
+    "Boolean": BooleanType(),
+    "Date": DateType(),
+    "int": IntegerType(),
+    "integer": IntegerType(),
+    "string": StringType(),
+    "str": StringType(),
+    "float": FloatType(),
+    "decimal": DecimalType(),
+    "boolean": BooleanType(),
+    "bool": BooleanType(),
+    "date": DateType(),
+    "Expr": ExpressionType,
+    "CompositeExpr": CompositeConditionType,
+    "Sequence": SequenceType,
+    "Extracted": ExtractedType,
+    "JsonObject": JsonObjectType(),
+    "json_object": JsonObjectType(),
+    "JsonArray": JsonArrayType(),
+    "json_array": JsonArrayType(),
+    "JsonNull": JsonNullType(),
+    "json_null": JsonNullType(),
+    # JSON-Schema 规范类型名别名（用户手写或旧版序列化器可能直接使用这些名字）
+    # 与前端 toJsonBackendType 的映射保持一致，避免直接读取此类文件时报错
+    "number": FloatType(),
+    "object": JsonObjectType(),
+    "array": JsonArrayType(),
+    "null": JsonNullType(),
+}
+
+
+def build_type_from_config(config: Any, registries: dict[str, ExpressionRegistry] | None = None) -> DataType:
+    """
+    从配置构建数据类型实例。
+
+    ============================================================================
+    配置文件示例 (本函数处理的配置文件长这样)
+    ============================================================================
+    本函数处理以下格式的类型配置：
+
+    ```yaml
+    # 方式1: 字符串形式（简单类型）
+    column:
+      type: "int"  # 或 "string", "float", "decimal"
+
+    # 方式2: 字典形式（带参数的类型）
+    column:
+      type:
+        name: "Sequence"                    # 类型名称
+        item_type: "string"                # 元素类型
+        delimiter: ","                      # 分隔符
+
+    # 方式3: 字典形式（带表达式的类型）
+    column:
+      type:
+        name: "Expr"                      # 表达式类型
+        registry: "patterns"               # 注册表名称
+    ```
+
+    ============================================================================
+    业务场景 (什么情况下会调用这个函数)
+    ============================================================================
+    - 场景1: 从配置文件加载 Schema 时
+      读取 *.schema.yaml 文件后，需要将配置中的类型字符串转换为实际的类型对象。
+
+    - 场景2: 运行时动态创建类型
+      根据用户输入动态创建数据类型实例。
+
+    ============================================================================
+    数据流 (输入如何变成输出)
+    ============================================================================
+    输入参数:
+      - config: Any，类型配置
+        示例值: "int" 或 {"name": "Sequence", "item_type": "string", "delimiter": ","}
+      - registries: Dict[str, ExpressionRegistry]，表达式注册表（可选）
+        示例值: {"patterns": ExpressionRegistry(...)}
+
+    处理步骤:
+      ┌─────────────────────────────────────────────────────────────┐
+      │ Step 1: 判断配置类型                                    │
+      ├─────────────────────────────────────────────────────────────┤
+      │ 输入: config                                           │
+      │ 操作: 检查是字符串还是字典                              │
+      │ 输出: 配置类型                                          │
+      └─────────────────────────────────────────────────────────────┘
+
+      ┌─────────────────────────────────────────────────────────────┤
+      │ Step 2: 字符串形式处理                                  │
+      ├─────────────────────────────────────────────────────────────┤
+      │ 输入: config = "int"                                    │
+      │ 操作: 从 TYPE_REGISTRY 查找类型                         │
+      │ 输出: IntegerType() 实例                               │
+      └─────────────────────────────────────────────────────────────┘
+
+      ┌─────────────────────────────────────────────────────────────┤
+      │ Step 3: 字典形式处理                                    │
+      ├─────────────────────────────────────────────────────────────┤
+      │ 输入: config = {"name": "Sequence", ...}                │
+      │ 操作: 提取 name，从 REGISTRY 查找类                     │
+      │       递归处理 item_type、registry 参数                 │
+      │ 输出: SequenceType(StringType(), ",") 实例             │
+      └─────────────────────────────────────────────────────────────┘
+
+    最终输出: DataType 实例
+      示例:
+        build_type_from_config("int")  # 返回 IntegerType() 实例
+        build_type_from_config({"name": "Sequence", "item_type": "string"})
+        # 返回 SequenceType(StringType(), ";")
+
+    ============================================================================
+    边界情况处理
+    ============================================================================
+    - 未知类型名称: 抛出 ValueError
+    - 无效的配置格式: 抛出 TypeError
+    - 缺失的 registry: 抛出 ValueError
+
+    :param config: 类型配置（字符串或字典）
+    :param registries: 表达式注册表字典
+    :return: DataType 实例
+    :raises ValueError: 类型名称不存在或 registry 缺失
+    :raises TypeError: 配置格式无效
+    """
+    if isinstance(config, str):
+        type_name = config
+        if type_name not in TYPE_REGISTRY:
+            raise ValueError(f"未知的类型名称: '{type_name}'")
+        return cast(DataType, TYPE_REGISTRY[type_name])
+
+    elif isinstance(config, dict):
+        type_name = cast(str, config.get("name"))
+        if not type_name or type_name not in TYPE_REGISTRY:
+            raise ValueError(f"类型配置字典中缺少或包含未知的类型名称: {config}")
+
+        type_class = TYPE_REGISTRY[type_name]
+        params = config.copy()
+        params.pop("name")
+
+        if "item_type" in params:
+            params["item_type"] = build_type_from_config(params["item_type"], registries)
+
+        if "registry" in params and isinstance(params["registry"], str):
+            registry_name = params["registry"]
+            if registries and registry_name in registries:
+                params["registry"] = registries[registry_name]
+            else:
+                raise ValueError(f"名为 '{registry_name}' 的表达式注册中心未提供。")
+
+        if "atomic_registry" in params and isinstance(params["atomic_registry"], str):
+            registry_name = params["atomic_registry"]
+            if registries and registry_name in registries:
+                params["registry"] = registries[registry_name]
+            else:
+                raise ValueError(f"名为 '{registry_name}' 的表达式注册中心未提供。")
+
+        return cast(DataType, type_class(**params))
+
+    else:
+        raise TypeError(f"无效的类型配置格式: {type(config)}")

app/shared/domain/schema/models.py

@@ -0,0 +1,339 @@
+# 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 模型模块
+
+功能概述:
+- 定义数据集的结构（表、字段、约束）
+
+架构设计:
+- 本模块只定义 Schema 模型类（ColumnSchema/TableSchema/DataSetSchema）
+- TYPE_REGISTRY 与工厂函数 build_type_from_config 的单一事实源在 builder.py
+- 本模块 re-export TYPE_REGISTRY 仅用于保持向后兼容的导入路径
+
+输入示例:
+    from app.shared.domain.dataset_schema import DataSetSchema, TableSchema, ColumnSchema
+
+    col1 = ColumnSchema(name="user_id", data_type=IntegerType(), is_primary_key=True)
+    table = TableSchema(name="users", columns=[col1, col2], source_file="data/users.xlsx")
+    schema = DataSetSchema(tables={"users": table}, constraints=[])
+
+输出示例:
+    schema: 完整的数据集 Schema 对象，可用于驱动 process_dataframe 和约束校验
+"""
+
+from typing import Any
+
+from app.shared.domain.constraints.base import Constraint
+from app.shared.domain.data_types import DataType
+
+# 1. 项目内部导入
+# TYPE_REGISTRY 的单一事实源在 builder.py，此处 re-export 以保持向后兼容的导入路径。
+# 过去本模块维护了一份独立副本，导致与 builder.py 漂移（如 JSON-Schema 别名缺失）。
+from app.shared.domain.schema.builder import TYPE_REGISTRY  # noqa: F401
+
+
+class ColumnSchema:
+    """
+    字段 Schema 定义。
+
+    ============================================================================
+    配置文件示例 (这个类对应哪种配置)
+    ============================================================================
+    本类对应 *.schema.yaml 中的 columns 列表项：
+
+    ```yaml
+    columns:
+      - id: user_id
+        name: user_id
+        type: int
+        primary_key: true
+        expand: false
+
+      - id: email
+        name: email
+        type: string
+        primary_key: false
+    ```
+
+    ============================================================================
+    字段映射说明
+    ============================================================================
+    | YAML 字段 | Python 属性 | 数据类型 | 说明 | 示例值 |
+    |----------|------------|---------|------|-------|
+    | id | (自动生成) | str | 列 ID | "user_id" |
+    | name | name | str | 列名 | "user_id" |
+    | type | data_type | DataType | 数据类型 | IntegerType() |
+    | primary_key | is_primary_key | bool | 是否主键 | true |
+    | expand | expand | bool | 是否展开 | false |
+
+    ============================================================================
+    业务场景 (什么情况下会使用这个类)
+    ============================================================================
+    - 场景1: 定义表的列结构
+      创建表时定义每一列的名称、类型、是否主键等。
+
+    - 场景2: 数据校验
+      根据 ColumnSchema 对数据列进行类型验证。
+
+    ============================================================================
+    使用示例
+    ============================================================================
+    【创建实例】
+    ```python
+    from app.shared.domain.dataset_schema import ColumnSchema
+    from app.shared.domain.data_types import IntegerType, StringType
+
+    col = ColumnSchema(
+        name="user_id",
+        data_type=IntegerType(),
+        is_primary_key=True,
+        expand=False
+    )
+    ```
+
+    【从配置创建】
+    ```python
+    config = {"name": "user_id", "type": "int", "primary_key": True}
+    data_type = build_type_from_config(config["type"])
+    col = ColumnSchema(name=config["name"], data_type=data_type)
+    ```
+    """
+
+    def __init__(
+        self,
+        name: str,
+        data_type: DataType,
+        is_primary_key: bool = False,
+        expand: bool = False,
+        nullable: bool = True,
+        id: str | None = None,
+        json_path: str | None = None,
+        children: list["ColumnSchema"] | None = None,
+    ):
+        self.name = name
+        self.data_type = data_type
+        self.is_primary_key = is_primary_key
+        self.expand = expand
+        self.nullable = nullable
+        self.id = id
+        self.json_path = json_path
+        self.children = children
+
+
+class TableSchema:
+    """
+    表 Schema 定义。
+
+    ============================================================================
+    配置文件示例 (这个类对应哪种配置)
+    ============================================================================
+    本类对应 *.schema.yaml 文件的主体：
+
+    ```yaml
+    id: users
+    name: users
+    source:
+      mode: relative_file
+      path: data/users.xlsx
+      sheet: Sheet1
+      header_row: 0
+    columns:
+      - name: user_id
+        type: int
+        primary_key: true
+      - name: email
+        type: string
+    ```
+
+    ============================================================================
+    字段映射说明
+    ============================================================================
+    | YAML 字段 | Python 属性 | 数据类型 | 说明 | 示例值 |
+    |----------|------------|---------|------|-------|
+    | id | (表名) | str | 表 ID | "users" |
+    | name | name | str | 表名 | "users" |
+    | source.path | source_file | str | 数据文件路径 | "data/users.xlsx" |
+    | source.sheet | sheet_name | str | Excel sheet | "Sheet1" |
+    | source.header_row | header_row | int | 表头行 | 0 |
+    | columns | columns | Dict[str, ColumnSchema] | 列定义字典 | {"user_id": ColumnSchema(...)} |
+
+    ============================================================================
+    业务场景 (什么情况下会使用这个类)
+    ============================================================================
+    - 场景1: 定义单张表的结构
+      定义表的名称、列定义、数据源位置等。
+
+    - 场景2: 加载数据文件
+      根据 TableSchema 的 source_file、sheet_name 等信息加载数据。
+
+    ============================================================================
+    使用示例
+    ============================================================================
+    【创建实例】
+    ```python
+    from app.shared.domain.dataset_schema import TableSchema, ColumnSchema
+    from app.shared.domain.data_types import IntegerType, StringType
+
+    table = TableSchema(
+        name="users",
+        columns=[
+            ColumnSchema(name="user_id", data_type=IntegerType(), is_primary_key=True),
+            ColumnSchema(name="email", data_type=StringType())
+        ],
+        source_file="data/users.xlsx",
+        sheet_name="Sheet1"
+    )
+
+    # 访问列
+    col = table.get_column("user_id")
+    print(col.is_primary_key)  # True
+    ```
+    """
+
+    def __init__(
+        self,
+        id: str | None = None,
+        name: str | None = None,
+        columns: list[ColumnSchema] | None = None,
+        source_file: str | None = None,
+        sheet_name: str | None = None,
+        header_row: int = 0,
+        script_checks: list[dict] | None = None,
+        source_config: dict[str, Any] | None = None,
+    ):
+        self.id = id
+        self.name = name
+        self.columns: dict[str, ColumnSchema] = {col.name: col for col in (columns or [])}
+        self.source_file = source_file
+        self.sheet_name = sheet_name
+        self.header_row = header_row
+        self.script_checks = script_checks or []
+        self.source_config = source_config or {}
+
+    def get_column(self, name: str) -> ColumnSchema | None:
+        """
+        @methoddesc 根据列名获取列定义
+
+        参数:
+            name: 列名
+
+        返回:
+            ColumnSchema 实例，如果列不存在则返回 None
+        """
+        return self.columns.get(name)
+
+
+class DataSetSchema:
+    """
+    数据集 Schema 定义。
+
+    ============================================================================
+    配置文件示例 (这个类对应哪种配置)
+    ============================================================================
+    本类是整个数据集的顶层结构：
+
+    ```yaml
+    # 表定义
+    tables:
+      users:
+        name: users
+        columns:
+          - name: user_id
+            type: int
+          - name: email
+            type: string
+      orders:
+        name: orders
+        columns:
+          - name: order_id
+            type: int
+
+    # 约束定义（独立文件）
+    constraints:
+      - type: Unique
+        table: users
+        column: email
+      - type: ForeignKey
+        from_table: orders
+        from_column: user_id
+        to_table: users
+        to_column: user_id
+    ```
+
+    ============================================================================
+    字段映射说明
+    ============================================================================
+    | 概念 | Python 属性 | 数据类型 | 说明 |
+    |------|------------|---------|------|
+    | 多个表 | tables | Dict[str, TableSchema] | 表名 -> 表定义 |
+    | 约束列表 | constraints | List[Constraint] | 全局约束列表 |
+
+    ============================================================================
+    业务场景 (什么情况下会使用这个类)
+    ============================================================================
+    - 场景1: 定义完整的数据集结构
+      包含多张表及其之间的约束关系。
+
+    - 场景2: 执行完整校验
+      DataSetSchema 是 validate_full_dataset 的核心输入。
+
+    ============================================================================
+    使用示例
+    ============================================================================
+    【创建实例】
+    ```python
+    from app.shared.domain.dataset_schema import DataSetSchema, TableSchema, ColumnSchema
+    from app.shared.domain.data_types import IntegerType, StringType
+    from app.shared.domain.validation_constraints import UniqueConstraint
+
+    # 创建表
+    users_table = TableSchema(
+        name="users",
+        columns=[
+            ColumnSchema(name="user_id", data_type=IntegerType()),
+            ColumnSchema(name="email", data_type=StringType())
+        ]
+    )
+
+    orders_table = TableSchema(
+        name="orders",
+        columns=[
+            ColumnSchema(name="order_id", data_type=IntegerType()),
+            ColumnSchema(name="user_id", data_type=IntegerType())
+        ]
+    )
+
+    # 创建约束
+    constraints = [
+        UniqueConstraint(table="users", column="email")
+    ]
+
+    # 创建数据集 Schema
+    schema = DataSetSchema(
+        tables={"users": users_table, "orders": orders_table},
+        constraints=constraints
+    )
+
+    # 访问
+    print(schema.tables.keys())  # dict_keys(['users', 'orders'])
+    print(len(schema.constraints))  # 1
+    ```
+    """
+
+    def __init__(self, tables: dict[str, TableSchema], constraints: list[Constraint]):
+        self.tables = tables
+        self.constraints = constraints

app/shared/domain/transforms/__init__.py

@@ -0,0 +1,28 @@
+# 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 Transform 运行器包
+
+导出:
+- TransformRunner: 抽象基类
+- create_runner: 工厂函数
+- TRANSFORM_REGISTRY: 注册表
+"""
+
+from .base import TransformRunner
+from .registry import TRANSFORM_REGISTRY, create_runner
+
+__all__ = ["TransformRunner", "TRANSFORM_REGISTRY", "create_runner"]