precis-cli 0.1.3__py3-none-any.whl

app/shared/domain/constraints/range.py

@@ -0,0 +1,360 @@
+# 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 范围约束模块
+
+功能概述:
+- 实现 RangeConstraint 类
+- 验证数值列是否在指定范围内
+- 支持开区间和闭区间
+- 支持 pandas 数值类型和 Python Decimal 类型
+
+架构设计:
+- 继承基类: 继承自 Constraint 抽象类
+- 边界模式: inclusive (闭区间) / exclusive (开区间)
+- 类型检查: 验证列是否为数值类型（包括 float、int、Decimal）
+
+输入示例:
+    # 约束配置 - 闭区间 [0, 100]
+    constraint1 = RangeConstraint(
+        table="products",
+        column="price",
+        min_value=0,
+        max_value=100,
+        boundary_mode="inclusive"
+    )
+
+    # 约束配置 - 开区间 (0, 100)
+    constraint2 = RangeConstraint(
+        table="users",
+        column="age",
+        min_value=0,
+        max_value=150,
+        boundary_mode="exclusive"
+    )
+
+    # 约束配置 - 仅最小值
+    constraint3 = RangeConstraint(
+        table="orders",
+        column="quantity",
+        min_value=1
+    )
+
+    # 数据集输入
+    datasets = {
+        "products": DataFrame({
+            "id": [1, 2, 3],
+            "price": [50, -10, 150]  # -10 和 150 超出范围
+        })
+    }
+
+输出示例:
+    # 验证失败 (第2行 price=-10, 第3行 price=150)
+    {
+        "errors": [
+            {
+                "error_type": "RangeViolation",
+                "table": "products",
+                "row_index": 1,
+                "column": "price",
+                "value": -10,
+                "message": "区间约束冲突: 值 -10 不在范围 [0, 100] 内。"
+            },
+            {
+                "error_type": "RangeViolation",
+                "table": "products",
+                "row_index": 2,
+                "column": "price",
+                "value": 150,
+                "message": "区间约束冲突: 值 150 不在范围 [0, 100] 内。"
+            }
+        ],
+        "info": {...}
+    }
+"""
+
+from __future__ import annotations
+
+# 1. 标准库导入
+from typing import Any
+
+# 2. 第三方库导入
+import pandas as pd
+
+# 3. 项目内部导入
+from app.shared.domain.constraints.base import Constraint
+
+
+class RangeConstraint(Constraint):
+    """
+    @classdesc 区间约束
+
+    验证数值列的值是否在指定的范围内。
+    支持闭区间（包含边界）和开区间（不包含边界）两种模式。
+    """
+
+    def __init__(
+        self,
+        table: str,
+        column: str,
+        min_value: float | None = None,
+        max_value: float | None = None,
+        boundary_mode: str = "inclusive",
+    ):
+        """
+        @methoddesc 初始化区间约束
+
+        参数:
+            table: 目标表名
+            column: 目标列名
+            min_value: 最小值，None 表示不限制下限
+            max_value: 最大值，None 表示不限制上限
+            boundary_mode: 边界模式，"inclusive"（闭区间，包含边界）或 "exclusive"（开区间，不包含边界）
+
+        抛出:
+            ValueError: 当 boundary_mode 不是 "inclusive" 或 "exclusive" 时抛出
+            ValueError: 当 min_value 大于 max_value 时抛出
+        """
+        if boundary_mode not in ("inclusive", "exclusive"):
+            raise ValueError(f"boundary_mode 必须是 'inclusive' 或 'exclusive'，当前值: '{boundary_mode}'")
+
+        if min_value is not None and max_value is not None and min_value > max_value:
+            raise ValueError(f"min_value ({min_value}) 不能大于 max_value ({max_value})")
+
+        self.table = table
+        self.column = column
+        self.min_value = min_value
+        self.max_value = max_value
+        self.boundary_mode = boundary_mode
+
+    def _get_description(self) -> str:
+        """根据边界模式生成区间描述"""
+        if self.min_value is not None and self.max_value is not None:
+            boundary_desc = (
+                f"[{self.min_value}, {self.max_value}]"
+                if self.boundary_mode == "inclusive"
+                else f"({self.min_value}, {self.max_value})"
+            )
+            return f"区间约束: {self.table}.{self.column} 范围 {boundary_desc}"
+        if self.min_value is not None:
+            op = ">=" if self.boundary_mode == "inclusive" else ">"
+            return f"区间约束: {self.table}.{self.column} {op} {self.min_value}"
+        if self.max_value is not None:
+            op = "<=" if self.boundary_mode == "inclusive" else "<"
+            return f"区间约束: {self.table}.{self.column} {op} {self.max_value}"
+        return f"区间约束: {self.table}.{self.column}"
+
+    def _is_numeric_column(self, series: pd.Series) -> bool:
+        """检查列是否为数值类型（支持 pandas 数值类型和 Python Decimal）。
+
+        参数:
+            series: pandas Series
+
+        返回:
+            是否为数值类型
+        """
+        # 1. 检查是否为 pandas 数值类型
+        if pd.api.types.is_numeric_dtype(series):
+            return True
+
+        # 2. 检查是否为 Decimal 类型（object dtype 但包含 Decimal 值）
+        if series.dtype == object:
+            non_null_values = series.dropna()
+            if len(non_null_values) > 0:
+                from decimal import Decimal
+
+                first_value = non_null_values.iloc[0]
+                if isinstance(first_value, Decimal):
+                    return True
+
+        return False
+
+    def validate(self, datasets: dict[str, pd.DataFrame], **kwargs: Any) -> dict[str, Any]:
+        """
+        @methoddesc 执行区间验证
+
+        参数:
+            datasets: 数据集字典，键为表名，值为 pandas DataFrame
+            **kwargs: 额外的关键字参数（本方法不使用）
+
+        返回:
+            验证结果字典，包含 errors（错误列表）和 info（约束信息）
+
+        逻辑说明:
+            1. 检查目标表是否存在
+            2. 检查目标列是否存在
+            3. 检查列是否为数值类型
+            4. 根据边界模式构建布尔掩码，筛选出不在范围内的行
+            5. 排除空值（空值不视为违规）
+            6. 为每个违规行生成错误记录
+        """
+        errors: list[dict[str, Any]] = []
+
+        # 无边界视为配置错误：min/max 至少配置其一。
+        # 此前无边界会"静默全过"——调用方传错参数键名（如把 min_value 写成 min）
+        # 时约束形同虚设且无任何提示（E2E 曾因此误判校验通过）。
+        if self.min_value is None and self.max_value is None:
+            errors.append(
+                {
+                    "error_type": "ConstraintConfigError",
+                    "table": self.table,
+                    "column": self.column,
+                    "message": "区间约束失败: 未配置边界（min_value / max_value 至少其一）。",
+                }
+            )
+            return {"errors": errors, "info": self.get_constraint_info()}
+
+        # 检查目标表是否存在
+        if self.table not in datasets:
+            errors.append(
+                {
+                    "error_type": "ConstraintConfigError",
+                    "table": self.table,
+                    "column": self.column,
+                    "message": f"区间约束失败: 表 '{self.table}' 不在数据集中。",
+                }
+            )
+            return {"errors": errors, "info": self.get_constraint_info()}
+
+        df = datasets[self.table]
+
+        # 检查目标列是否存在
+        if self.column not in df.columns:
+            errors.append(
+                {
+                    "error_type": "ConstraintConfigError",
+                    "table": self.table,
+                    "column": self.column,
+                    "message": f"区间约束失败: 列 '{self.column}' 在表 '{self.table}' 中不存在。",
+                }
+            )
+            return {"errors": errors, "info": self.get_constraint_info()}
+
+        # 检查列是否为数值类型（支持 pandas 数值类型和 Python Decimal）。
+        # 产品约束：Range 不做字符串→数值强转——非数值字段使用 Range 校验
+        # 直接报告"数据格式不合规"，而不是强转后按数值比较。
+        if not self._is_numeric_column(df[self.column]):
+            errors.append(
+                {
+                    "error_type": "ConstraintConfigError",
+                    "table": self.table,
+                    "column": self.column,
+                    "message": (
+                        f"区间约束失败: 数据格式不合规——列 '{self.column}' 不是数值类型，"
+                        "非数值字段不能使用 Range 校验（不会做字符串到数值的隐式转换）。"
+                    ),
+                }
+            )
+            return {"errors": errors, "info": self.get_constraint_info()}
+
+        # 回归 D9: Decimal 列的大额值转 float64 会丢精度(float64 仅 ~15-17 位有效数字),
+        # 导致边界误判。检测到 Decimal 列时,把列值与边界都转 Decimal 后逐行比较,保持精度。
+        from decimal import Decimal, InvalidOperation
+
+        col_series = df[self.column]
+        is_decimal_col = False
+        if col_series.dtype == object:
+            non_null = col_series.dropna()
+            if len(non_null) > 0 and isinstance(non_null.iloc[0], Decimal):
+                is_decimal_col = True
+
+        if is_decimal_col:
+            # Decimal 空间比较,避免 float64 丢精度
+            min_dec = Decimal(str(self.min_value)) if self.min_value is not None else None
+            max_dec = Decimal(str(self.max_value)) if self.max_value is not None else None
+
+            def _in_range(v: Any) -> bool:
+                if v is None or (isinstance(v, float) and pd.isna(v)):
+                    return True  # 空值不视为违规(下方 dropna 也会处理)
+                # §1.4: 空串口径统一为"缺失值豁免"——空白串不参与 Decimal 判定，
+                # 否则 Decimal("") 抛 InvalidOperation 被误判"超出范围"（误导排查方向）
+                if isinstance(v, str) and v.strip() == "":
+                    return True
+                try:
+                    dv = v if isinstance(v, Decimal) else Decimal(str(v))
+                except (InvalidOperation, ValueError):
+                    return False
+                if min_dec is not None:
+                    if self.boundary_mode == "inclusive" and dv < min_dec:
+                        return False
+                    if self.boundary_mode == "exclusive" and dv <= min_dec:
+                        return False
+                if max_dec is not None:
+                    if self.boundary_mode == "inclusive" and dv > max_dec:
+                        return False
+                    if self.boundary_mode == "exclusive" and dv >= max_dec:
+                        return False
+                return True
+
+            mask = col_series.apply(_in_range)
+        else:
+            numeric_series = pd.to_numeric(col_series, errors="coerce")
+
+            # 初始化掩码: 所有行默认都在范围内（True）
+            mask = pd.Series([True] * len(df), index=df.index)
+
+            # 应用最小值约束
+            if self.min_value is not None:
+                if self.boundary_mode == "inclusive":
+                    mask = mask & (numeric_series >= self.min_value)
+                else:
+                    mask = mask & (numeric_series > self.min_value)
+
+            # 应用最大值约束
+            if self.max_value is not None:
+                if self.boundary_mode == "inclusive":
+                    mask = mask & (numeric_series <= self.max_value)
+                else:
+                    mask = mask & (numeric_series < self.max_value)
+
+        # 取反得到不在范围内的行，并排除空值
+        invalid_rows = df[~mask].dropna(subset=[self.column])
+
+        # 为每个违规行生成错误记录
+        for row_tuple in invalid_rows[[self.column]].itertuples(index=True, name=None):
+            index = row_tuple[0]
+            value = row_tuple[1]
+            row_index = int(index) if index is not None else 0
+
+            # 根据配置生成对应的错误消息
+            if self.min_value is not None and self.max_value is not None:
+                boundary_desc = (
+                    f"[{self.min_value}, {self.max_value}]"
+                    if self.boundary_mode == "inclusive"
+                    else f"({self.min_value}, {self.max_value})"
+                )
+                message = f"区间约束冲突: 值 {value} 不在范围 {boundary_desc} 内。"
+            elif self.min_value is not None:
+                op = ">=" if self.boundary_mode == "inclusive" else ">"
+                message = f"区间约束冲突: 值 {value} 不满足 {op} {self.min_value}。"
+            elif self.max_value is not None:
+                op = "<=" if self.boundary_mode == "inclusive" else "<"
+                message = f"区间约束冲突: 值 {value} 不满足 {op} {self.max_value}。"
+            else:
+                message = f"区间约束冲突: 值 {value} 超出指定范围。"
+
+            errors.append(
+                {
+                    "error_type": "RangeViolation",
+                    "table": self.table,
+                    "row_index": row_index,
+                    "column": self.column,
+                    "value": value,
+                    "message": message,
+                }
+            )
+
+        return {"errors": errors, "info": self.get_constraint_info()}

app/shared/domain/constraints/regex.py

@@ -0,0 +1,218 @@
+# 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 正则表达式约束模块
+
+功能概述:
+- 实现 RegexConstraint 类
+- 验证指定列的数据是否符合正则表达式模式
+- 支持全匹配(full)和搜索(search)两种匹配模式
+- 支持正则表达式标志配置(i/m/s)和大小写控制
+
+架构设计:
+- 继承基类: 继承自 Constraint 抽象类
+- 预编译优化: 预先编译正则表达式为 Pattern 对象
+- 防御式编程: 捕获 re.error 和类型转换错误
+
+输入示例:
+    constraint = RegexConstraint(
+        table="users",
+        column="email",
+        pattern=r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$",
+        match_mode="full",
+        flags="i",
+    )
+
+    datasets = {
+        "users": DataFrame({
+            "email": ["test@example.com", "invalid-email", None]
+        })
+    }
+
+输出示例:
+    {
+        "errors": [
+            {
+                "row_index": 1,
+                "column": "email",
+                "value": "invalid-email",
+                "message": "值 'invalid-email' 不符合正则表达式模式"
+            }
+        ],
+        "info": {...}
+    }
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import pandas as pd
+
+from app.shared.domain.constraints.base import Constraint
+from app.shared.domain.regex_flags import parse_regex_flags
+
+
+class RegexConstraint(Constraint):
+    """
+    @classdesc 正则表达式约束
+
+    验证指定列的数据是否符合正则表达式模式。
+    空值(NaN/None)跳过校验，不计入错误。
+
+    参数:
+        table: 表名
+        column: 列名
+        pattern: 正则表达式模式字符串
+        match_mode: 匹配模式，"full" 全匹配或 "search" 搜索匹配
+        flags: 正则表达式标志字符串（如 "i" 不区分大小写）
+        case_sensitive: 是否区分大小写
+    """
+
+    def __init__(
+        self,
+        table: str = "temp",
+        column: str = "",
+        pattern: str = "",
+        match_mode: str = "full",
+        flags: str = "",
+        case_sensitive: bool = True,
+    ):
+        self.table = table
+        self.column = column
+        self.pattern = pattern
+        self.match_mode = match_mode
+        self.flags = flags
+        self.case_sensitive = case_sensitive
+
+    def validate(self, datasets: dict[str, pd.DataFrame], **kwargs: Any) -> dict[str, Any]:
+        """执行正则表达式约束验证。"""
+        errors: list[dict[str, Any]] = []
+
+        df = datasets.get(self.table)
+        if df is None:
+            errors.append(
+                {
+                    "error_type": "ConstraintConfigError",
+                    "table": self.table,
+                    "column": self.column,
+                    "message": f"正则约束失败: 表 '{self.table}' 不在数据集中。",
+                }
+            )
+            return {"errors": errors, "info": self.get_constraint_info()}
+
+        if self.column not in df.columns:
+            errors.append(
+                {
+                    "error_type": "ConstraintConfigError",
+                    "table": self.table,
+                    "column": self.column,
+                    "message": f"正则约束失败: 列 '{self.column}' 在表 '{self.table}' 中不存在。",
+                }
+            )
+            return {"errors": errors, "info": self.get_constraint_info()}
+
+        if not self.pattern:
+            errors.append(
+                {
+                    "error_type": "ConstraintConfigError",
+                    "table": self.table,
+                    "column": self.column,
+                    "message": "正则约束失败: pattern 为空，未提供正则表达式。",
+                }
+            )
+            return {"errors": errors, "info": self.get_constraint_info()}
+
+        # §1.8: match_mode 归一大小写不敏感（"Full" 合法），未知值报配置错误——
+        # 原实现非 "full" 一律 search，"fullmatch"/"partial" 这类拼错被静默降级为子串匹配
+        mode = (self.match_mode or "full").lower()
+        if mode not in ("full", "search"):
+            errors.append(
+                {
+                    "error_type": "ConstraintConfigError",
+                    "table": self.table,
+                    "column": self.column,
+                    "message": f"正则约束配置错误: 未知的 match_mode '{self.match_mode}'，支持的值为: full, search。",
+                }
+            )
+            return {"errors": errors, "info": self.get_constraint_info()}
+
+        try:
+            # 解析正则表达式标志（整词匹配，防 "multiline" 的 'm/i/s' 字符集误开无关 flag）
+            re_flags = parse_regex_flags(self.flags)
+            if not self.case_sensitive:
+                re_flags |= re.IGNORECASE
+
+            regex = re.compile(self.pattern, re_flags)
+
+            for row_index, cell_value in df[self.column].items():
+                # §1.4: 空串口径统一为"缺失值豁免"——全空白串不参与正则判定（与 NotNull 同口径）
+                if pd.isna(cell_value) or cell_value is None or str(cell_value).strip() == "":
+                    continue
+
+                cell_value_str = str(cell_value)
+
+                try:
+                    if mode == "full":
+                        match_result = regex.fullmatch(cell_value_str)
+                    else:
+                        match_result = regex.search(cell_value_str)
+
+                    if not match_result:
+                        errors.append(
+                            {
+                                # 与其他 9 种约束的 <Type>Violation 命名风格保持一致
+                                "error_type": "RegexViolation",
+                                "row_index": row_index,
+                                "column": self.column,
+                                "value": cell_value_str,
+                                "message": f"值 '{cell_value_str}' 不符合正则表达式模式",
+                            }
+                        )
+                except (TypeError, ValueError) as e:
+                    errors.append(
+                        {
+                            # 命名风格对照 scripted 的 ScriptCheckExecutionError
+                            "error_type": "RegexExecutionError",
+                            "row_index": row_index,
+                            "column": self.column,
+                            "value": cell_value_str,
+                            "message": f"校验出错: {cell_value_str} ({type(e).__name__}: {e})",
+                        }
+                    )
+
+        except re.error as e:
+            errors.append(
+                {
+                    # 正则语法错误属于配置问题，与其他约束的配置错误条目一致
+                    "error_type": "ConstraintConfigError",
+                    "row_index": 0,
+                    "column": self.column,
+                    "value": None,
+                    "message": f"正则表达式语法错误: {e}",
+                }
+            )
+
+        # 返回结构与其他约束（conditional/scripted/charset/foreign_key 等）保持一致：
+        # 仅含 errors 和 info，不再输出冗余的 valid 字段（调用方统一通过 errors 是否为空判断）
+        return {
+            "errors": errors,
+            "info": self.get_constraint_info(),
+        }
+
+    def _get_description(self) -> str:
+        return f"正则约束: {self.table}.{self.column} pattern={self.pattern!r}"