precis-cli 0.1.3__py3-none-any.whl

app/shared/domain/data_types_parts/base.py

@@ -0,0 +1,204 @@
+# 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 数据类型基类模块
+
+功能概述:
+- 定义数据类型抽象基类 (DataType)
+- 所有具体数据类型都继承自此基类
+- 提供统一的验证 (validate) 和解析 (parse) 接口
+
+架构设计:
+- 抽象基类: 使用 ABC 定义抽象方法
+- 双重接口: validate() + parse()
+- 子类必须实现两个抽象方法才能实例化
+
+输入示例:
+    # 子类使用
+    class IntegerType(DataType):
+        def validate(self, value): ...
+        def parse(self, value): ...
+
+输出示例:
+    # validate(value: Any) -> Tuple[bool, Any]
+    #   - 验证值是否符合类型要求
+    #   - 返回: (是否有效, 错误信息)
+    #   - 成功: (True, None)
+    #   - 失败: (False, "错误描述")
+
+    # parse(value: Any) -> Any
+    #   - 将值转换为目标类型
+    #   - 返回转换后的值
+
+继承体系:
+    DataType (抽象基类)
+        ├── IntegerType     # 整数类型
+        ├── StringType      # 字符串类型
+        ├── FloatType       # 浮点数类型
+        ├── BooleanType     # 布尔类型
+        ├── ExpressionType  # 表达式类型
+        ├── ExtractedType   # 提取类型
+        ├── SequenceType    # 序列类型
+        └── CompositeConditionType  # 复合条件类型
+"""
+
+from __future__ import annotations
+
+# 1. 标准库导入
+from abc import ABC, abstractmethod
+from typing import Any
+
+# 2. 第三方库导入
+import pandas as pd
+
+
+class DataType(ABC):
+    """
+    @classdesc 数据类型抽象基类
+
+    所有具体数据类型的基类，定义统一的数据类型接口。
+    子类必须实现 validate() 和 parse() 方法，否则无法实例化。
+
+    使用场景:
+    - 作为 IntegerType、StringType、FloatType 等具体类型的基类
+    - 在 ColumnSchema 中定义列的数据类型
+    - 在数据引擎 process_dataframe 中执行类型验证和转换
+    """
+
+    @abstractmethod
+    def validate(self, value: Any) -> tuple[bool, Any]:
+        """
+        @methoddesc 验证值是否符合类型要求
+
+        子类必须实现此方法，对单个原始值进行类型合规性检查。
+        验证逻辑应专注于格式和语义正确性，不涉及空值判断（空值由调用方处理）。
+
+        Args:
+            value: 要验证的原始值，可能为字符串、数字、日期对象等任意类型
+
+        Returns:
+            tuple[bool, Any]: 二元组，结构固定为 (is_valid, error_message)
+                - is_valid (bool): True 表示值符合该数据类型的格式和语义要求；False 表示验证失败
+                - error_message (Any): 验证失败时返回描述性错误信息（通常为 str）；验证通过时必须返回 None
+
+        Raises:
+            NotImplementedError: 抽象方法，直接调用基类方法会抛出此异常，强制子类实现
+
+        示例:
+            >>> dtype = IntegerType()
+            >>> dtype.validate(123)
+            (True, None)
+            >>> dtype.validate("abc")
+            (False, "'abc' 不是一个严格格式的整数（只允许数字和可选的负号）。")
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def parse(self, value: Any) -> Any:
+        """
+        @methoddesc 将值转换为目标类型
+
+        子类必须实现此方法，将已通过 validate() 验证的原始值转换为该数据类型的标准 Python 对象。
+        调用方应确保在调用 parse() 前先调用 validate() 确认值有效。
+
+        Args:
+            value: 要转换的原始值，通常为字符串或从数据源读取的原始格式
+
+        Returns:
+            Any: 转换后的目标类型值，如 int、float、datetime 对象等，具体类型由子类定义
+
+        Raises:
+            NotImplementedError: 抽象方法，直接调用基类方法会抛出此异常，强制子类实现
+
+        示例:
+            >>> dtype = IntegerType()
+            >>> dtype.parse("123")
+            123
+        """
+        raise NotImplementedError
+
+    def process_column(self, series: pd.Series, col_name: str, nullable: bool = True) -> tuple[pd.Series, list[dict]]:
+        """
+        @methoddesc 对整列数据进行验证和解析（向量化入口）
+
+        提供逐元素验证 + 解析的默认实现，作为子类覆写前的基线行为。
+        处理流程按优先级分为四个分支：非空违反 -> 空值透传 -> 类型验证失败 -> 解析成功。
+        子类可覆写此方法以提供更高效的向量化实现（如使用 pandas 的 apply/vectorized 操作）。
+
+        Args:
+            series: 待处理的 pandas Series，包含从数据源读取的原始列数据
+            col_name: 列名，用于构造错误信息中的标识和描述
+            nullable: 是否允许空值（None/NaN/空字符串）。False 表示该列不允许为空，遇到空值时记录 NotNullViolation 错误
+
+        Returns:
+            tuple[pd.Series, list[dict]]: 处理结果二元组
+                - parsed_series (pd.Series): 解析后的 Series，索引与输入一致；验证失败或空值位置填充为 None
+                - errors_list (list[dict]): 错误字典列表，每个字典包含 row_index、column、value、error_type、error_message，格式与 data_engine 保持一致
+        """
+        # 收集整列处理过程中发现的所有错误
+        errors: list[dict] = []
+        # 收集逐元素解析后的值，最终组装为新的 Series
+        parsed_values: list[Any] = []
+        # 预先计算整列的空值掩码，避免在循环中重复判断，提升性能
+        is_na = series.isna()
+
+        for index, value in series.items():
+            # 分支 1：非空约束检查
+            # 当 nullable=False 时，拒绝任何空值（pandas NaN 或空字符串）
+            if not nullable and (is_na[index] or str(value).strip() == ""):
+                errors.append(
+                    {
+                        "row_index": index,  # 数据行索引，与原始 DataFrame 对齐
+                        "column": col_name,  # 当前处理的列名，用于定位错误位置
+                        "value": value,  # 原始空值，保留用于调试和展示
+                        "error_type": "NotNullViolation",  # 错误类型标识，与前端错误分类对应
+                        "error_message": f"列 '{col_name}' 不允许为空",  # 面向用户的错误描述
+                    }
+                )
+                # 非空违反时，解析结果置为 None，保持 Series 长度与索引一致
+                parsed_values.append(None)
+                # 进入下一个元素，跳过后续的 validate/parse
+                continue
+
+            # 分支 2：空值透传
+            # 当列允许为空（nullable=True）且当前值为空时，直接透传 None，不执行类型验证
+            if is_na[index]:
+                parsed_values.append(None)
+                continue
+
+            # 分支 3：类型验证
+            # 对非空值调用子类实现的 validate() 进行格式和语义检查
+            is_valid, error_message = self.validate(value)
+            if not is_valid:
+                errors.append(
+                    {
+                        "row_index": index,
+                        "column": col_name,
+                        "value": value,  # 记录原始无效值，便于用户排查数据问题
+                        "error_type": "TypeValidationError",  # 类型验证失败的统一错误标识
+                        "error_message": error_message,  # 由具体子类提供的详细错误描述
+                    }
+                )
+                # 验证失败时，解析结果置为 None，避免将无效数据流入下游处理
+                parsed_values.append(None)
+                continue
+
+            # 分支 4：解析成功
+            # 值已通过 validate() 验证，调用子类实现的 parse() 转换为目标类型
+            parsed_values.append(self.parse(value))
+
+        # 使用原始索引构建新的 Series，确保与输入 DataFrame 的行对齐
+        return pd.Series(parsed_values, index=series.index), errors

app/shared/domain/data_types_parts/composite.py

@@ -0,0 +1,250 @@
+# 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 复合数据类型模块
+
+功能概述:
+- 定义复合数据类型 (如复合条件)
+- 支持逻辑组合 (AND/OR) 的条件表达式
+
+架构设计:
+- 继承基类: 继承自 DataType 基类
+- 条件解析: 使用正则表达式分割复合条件
+- 注册表匹配: 使用 registry 匹配子条件
+
+输入示例:
+    # 复合条件表达式
+    value = "age > 18 AND status = 'active'"
+
+    # logical_op = "and" 时，使用 " AND " 分割
+    # logical_op = "or" 时，使用 " OR " 分割
+
+输出示例:
+    # validate() 返回
+    (True, None)    # 所有子条件都有效
+    (False, "复合条件中的子句 'xxx' 不匹配任何已知的模式。")
+
+    # parse() 返回解析后的条件列表
+    [
+        {"field": "age", "operator": ">", "value": 18},
+        {"field": "status", "operator": "=", "value": "active"}
+    ]
+"""
+
+from __future__ import annotations
+
+# 1. 标准库导入
+import re
+from typing import Any
+
+# 2. 项目内部导入
+from app.shared.domain.data_types_parts.base import DataType
+from app.shared.domain.expression_system import ExpressionRegistry
+
+
+class CompositeConditionType(DataType):
+    """
+    @classdesc 复合条件类型
+
+    支持逻辑组合（AND/OR）的条件表达式类型。
+    将复合条件字符串按逻辑运算符分割为原子条件，逐个验证。
+
+    使用场景:
+    - 验证包含多个子条件的复合条件表达式
+    - 如 "age > 18 AND status = 'active'"
+    """
+
+    def __init__(self, registry: ExpressionRegistry, logical_op: str = "and") -> None:
+        """
+        @methoddesc 初始化复合条件类型
+
+        参数:
+            registry: 表达式注册表，用于匹配原子条件
+            logical_op: 逻辑运算符，"and" 或 "or"
+        """
+        self.registry = registry
+        self.splitter = re.compile(r"\s+" + re.escape(logical_op) + r"\s+")
+
+    def validate(self, value: Any) -> tuple[bool, Any]:
+        """
+        @methoddesc 验证复合条件表达式
+
+        将表达式按逻辑运算符分割为原子条件，逐个使用注册表匹配验证。
+
+        参数:
+            value: 条件表达式字符串
+
+        返回:
+            元组 (is_valid, error_message)
+        """
+        if not isinstance(value, str):
+            return False, f"期望是字符串, 但得到了 {type(value).__name__}。"
+        if not value.strip():
+            return True, None
+        atomic_conditions = self.splitter.split(value)
+        for i, atomic_str in enumerate(atomic_conditions):
+            atomic_str = atomic_str.strip()
+            if not atomic_str:
+                return False, f"在第 {i} 个 '{self.splitter.pattern}' 分割符附近发现了空的条件表达式。"
+            match_result = self.registry.find_match(atomic_str)
+            if not match_result:
+                return False, f"复合条件中的子句 '{atomic_str}' 不匹配任何已知的模式。"
+            pattern, match = match_result
+            try:
+                pattern.parser_func(match.groupdict())
+            except (ValueError, KeyError) as e:
+                return False, f"子句 '{atomic_str}' 验证失败: {e}"
+        return True, None
+
+    def parse(self, value: Any) -> list[dict[str, Any]]:
+        """
+        @methoddesc 解析复合条件表达式
+
+        将表达式按逻辑运算符分割为原子条件，逐个解析为结构化数据。
+
+        参数:
+            value: 条件表达式字符串
+
+        返回:
+            解析后的条件列表，每个元素是包含 type 和 value 的字典
+        """
+        if not isinstance(value, str) or not value.strip():
+            return []
+        parsed_conditions = []
+        atomic_conditions = self.splitter.split(value)
+        for atomic_str in atomic_conditions:
+            atomic_str = atomic_str.strip()
+            if not atomic_str:
+                continue
+            find_result = self.registry.find_match(atomic_str)
+            if find_result is None:
+                raise ValueError(f"子条件 '{atomic_str}' 不匹配任何已注册的表达式模式")
+            pattern, match = find_result
+            parsed_value = pattern.parser_func(match.groupdict())
+            parsed_conditions.append({"type": pattern.name, "value": parsed_value})
+        return parsed_conditions
+
+
+class SpecificCompositeConditionType(DataType):
+    """
+    @classdesc 特定复合条件类型
+
+    针对单一模式的精确复合条件类型。
+    初始化时指定具体模式名称，验证时仅匹配该模式。
+
+    使用场景:
+    - 需要限制复合条件中只能使用特定模式时
+    """
+
+    def __init__(self, registry: ExpressionRegistry, pattern: str, logical_op: str = "and") -> None:
+        """
+        @methoddesc 初始化特定复合条件类型
+
+        参数:
+            registry: 表达式注册表
+            pattern: 指定的模式名称
+            logical_op: 逻辑运算符，"and" 或 "or"
+
+        抛出:
+            ValueError: 当注册表中未找到指定模式时抛出
+        """
+        self.registry = registry
+        self.pattern_name = pattern
+        self.specific_pattern = None
+        for p in registry._patterns:
+            if p.name == pattern:
+                self.specific_pattern = p
+                break
+        if self.specific_pattern is None:
+            raise ValueError(f"在注册表中未找到指定的模式: '{pattern}'")
+        self.splitter = re.compile(r"\s+" + re.escape(logical_op) + r"\s+")
+
+    def validate(self, value: Any) -> tuple[bool, Any]:
+        """
+        @methoddesc 验证特定复合条件表达式
+
+        与通用 CompositeConditionType 不同，本方法不仅要求子句能被注册表匹配，
+        还要求匹配到的模式与初始化时指定的 specific_pattern 一致。
+        过去本方法忽略了 specific_pattern，导致限定模式后仍接受其他子句。
+
+        参数:
+            value: 条件表达式字符串
+
+        返回:
+            元组 (is_valid, error_message)
+        """
+        specific = self.specific_pattern
+        if specific is None:
+            return False, "内部错误：specific_pattern 未初始化"
+        if not isinstance(value, str):
+            return False, f"期望是字符串, 但得到了 {type(value).__name__}。"
+        if not value.strip():
+            return True, None
+        atomic_conditions = self.splitter.split(value)
+        for i, atomic_str in enumerate(atomic_conditions):
+            atomic_str = atomic_str.strip()
+            if not atomic_str:
+                return False, f"在第 {i} 个 '{self.splitter.pattern}' 分割符附近发现了空的条件表达式。"
+            match_result = self.registry.find_match(atomic_str)
+            if not match_result:
+                return False, f"复合条件中的子句 '{atomic_str}' 不匹配任何已知的模式。"
+            pattern, match = match_result
+            # 校验匹配到的模式必须与 specific_pattern 一致
+            if pattern is None or pattern.name != specific.name:
+                return (
+                    False,
+                    f"子句 '{atomic_str}' 匹配的模式 '{getattr(pattern, 'name', '?')}' 与限定模式 "
+                    f"'{specific.name}' 不一致，本类型只允许使用限定模式。",
+                )
+            try:
+                pattern.parser_func(match.groupdict())
+            except (ValueError, KeyError) as e:
+                return False, f"子句 '{atomic_str}' 验证失败: {e}"
+        return True, None
+
+    def parse(self, value: Any) -> list[dict[str, Any]]:
+        """
+        @methoddesc 解析特定复合条件表达式
+
+        仅解析与 specific_pattern 匹配的子句，忽略其他模式（与 validate 语义一致）。
+
+        参数:
+            value: 条件表达式字符串
+
+        返回:
+            解析后的条件列表，每个元素是包含 type 和 value 的字典
+        """
+        if not isinstance(value, str) or not value.strip():
+            return []
+        specific = self.specific_pattern
+        if specific is None:
+            return []
+        parsed_conditions = []
+        atomic_conditions = self.splitter.split(value)
+        for atomic_str in atomic_conditions:
+            atomic_str = atomic_str.strip()
+            if not atomic_str:
+                continue
+            match_result = self.registry.find_match(atomic_str)
+            if not match_result:
+                continue
+            pattern, match = match_result
+            # 仅解析与 specific_pattern 一致的子句
+            if pattern is None or pattern.name != specific.name:
+                continue
+            parsed_value = pattern.parser_func(match.groupdict())
+            parsed_conditions.append({"type": pattern.name, "value": parsed_value})
+        return parsed_conditions

app/shared/domain/data_types_parts/expression.py

@@ -0,0 +1,202 @@
+# 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.
+r"""
+@fileoverview 表达式数据类型模块
+
+功能概述:
+- 定义 ExpressionType 支持从注册表匹配和验证表达式格式
+- 定义 SpecificExpressionType 针对单一模式的精确匹配
+- 提供 validate() 和 parse() 方法用于表达式校验与解析
+
+架构设计:
+- 继承基类: 继承自 DataType 基类，遵循统一的数据类型接口
+- 注册表驱动: 使用 ExpressionRegistry 匹配表达式模式
+- 解析委托: 将具体解析逻辑委托给 pattern.parser_func
+
+输入示例:
+    # 注册表中的表达式模式
+    registry = ExpressionRegistry(patterns=[
+        Pattern(name="add", pattern=r"add\({a},{b}\)", parser_func=...)
+    ])
+
+    # 验证表达式
+    ExpressionType(registry).validate("add(1,2)")    # (True, None)
+    ExpressionType(registry).validate("unknown(1,2)") # (False, "不匹配任何已注册的表达式格式")
+
+输出示例:
+    # validate() 返回
+    (True, None)   # 表达式有效
+    (False, "表达式 'xxx' 格式正确但内容无效: ...")  # 表达式格式错
+
+    # parse() 返回
+    {
+        "type": "add",
+        "value": {"a": 1, "b": 2}
+    }
+"""
+
+from __future__ import annotations
+
+# 1. 标准库导入
+from typing import Any
+
+# 2. 项目内部导入
+from app.shared.domain.data_types_parts.base import DataType
+from app.shared.domain.expression_system import ExpressionPattern, ExpressionRegistry
+
+
+class ExpressionType(DataType):
+    """
+    @classdesc 表达式类型
+
+    支持从注册表匹配和验证表达式格式的数据类型。
+    使用 ExpressionRegistry 查找匹配的表达式模式，常用于验证手机号、邮箱等格式。
+
+    使用场景:
+    - 验证数据是否符合预定义的表达式模式
+    - 将符合模式的字符串解析为结构化数据
+    """
+
+    name = "Expr"
+
+    def __init__(self, registry: ExpressionRegistry) -> None:
+        """
+        @methoddesc 初始化表达式类型
+
+        参数:
+            registry: 表达式注册表，包含所有可用的表达式模式
+        """
+        self.registry = registry
+
+    def validate(self, value: Any) -> tuple[bool, Any]:
+        """
+        @methoddesc 验证表达式字符串
+
+        在注册表中查找匹配的模式，并调用模式的解析函数验证内容。
+
+        参数:
+            value: 要验证的字符串
+
+        返回:
+            元组 (is_valid, error_message)
+        """
+        if not isinstance(value, str):
+            return False, f"期望是字符串, 但得到了 {type(value).__name__}。"
+        match_result = self.registry.find_match(value)
+        if not match_result:
+            return False, f"'{value}' 不匹配任何已注册的表达式格式。"
+        pattern, match = match_result
+        try:
+            pattern.parser_func(match.groupdict())
+            return True, None
+        except (ValueError, KeyError) as e:
+            return False, f"表达式 '{value}' 格式正确但内容无效: {e}"
+
+    def parse(self, value: Any) -> dict[str, Any]:
+        """
+        @methoddesc 解析表达式字符串
+
+        在注册表中查找匹配的模式，并调用解析函数生成结构化数据。
+
+        参数:
+            value: 要解析的字符串
+
+        返回:
+            包含 type 和 value 的字典
+        """
+        find_result = self.registry.find_match(value)
+        if find_result is None:
+            raise ValueError(f"值 '{value}' 不匹配任何已注册的表达式模式")
+        pattern, match = find_result
+        return {"type": pattern.name, "value": pattern.parser_func(match.groupdict())}
+
+
+class SpecificExpressionType(DataType):
+    """
+    @classdesc 特定表达式类型
+
+    针对单一模式的精确表达式类型。
+    初始化时指定具体模式名称，验证时仅匹配该模式。
+
+    使用场景:
+    - 需要限制列只能使用特定表达式模式时
+    """
+
+    def __init__(self, registry: ExpressionRegistry, pattern: str) -> None:
+        """
+        @methoddesc 初始化特定表达式类型
+
+        参数:
+            registry: 表达式注册表
+            pattern: 指定的模式名称
+
+        抛出:
+            ValueError: 当注册表中未找到指定模式时抛出
+        """
+        self.registry = registry
+        self.pattern_name = pattern
+        specific_pattern: ExpressionPattern | None = None
+        for p in registry._patterns:
+            if p.name == pattern:
+                specific_pattern = p
+                break
+        if specific_pattern is None:
+            raise ValueError(f"在注册表中未找到指定的模式: '{pattern}'")
+        if isinstance(specific_pattern.regex, str):
+            import re
+
+            specific_pattern.regex = re.compile(specific_pattern.regex)
+        self.specific_pattern = specific_pattern
+
+    def validate(self, value: Any) -> tuple[bool, Any]:
+        """
+        @methoddesc 验证特定表达式字符串
+
+        使用指定的模式进行精确匹配。
+
+        参数:
+            value: 要验证的字符串
+
+        返回:
+            元组 (is_valid, error_message)
+        """
+        if not isinstance(value, str):
+            return False, f"期望是字符串, 但得到了 {type(value).__name__}。"
+        match = self.specific_pattern.regex.fullmatch(value.strip())
+        if not match:
+            return False, f"'{value}' 不匹配指定的表达式格式 '{self.pattern_name}'。"
+        try:
+            self.specific_pattern.parser_func(match.groupdict())
+            return True, None
+        except (ValueError, KeyError) as e:
+            return False, f"表达式 '{value}' 格式正确但内容无效: {e}"
+
+    def parse(self, value: Any) -> dict[str, Any]:
+        """
+        @methoddesc 解析特定表达式字符串
+
+        使用指定的模式进行精确匹配并解析。
+
+        参数:
+            value: 要解析的字符串
+
+        返回:
+            包含 type 和 value 的字典
+        """
+        match = self.specific_pattern.regex.fullmatch(value.strip())
+        if not match:
+            return {"type": self.specific_pattern.name, "value": None}
+        return {"type": self.specific_pattern.name, "value": self.specific_pattern.parser_func(match.groupdict())}