precis-cli 0.1.3__py3-none-any.whl

app/shared/domain/constraints/composite.py

@@ -0,0 +1,174 @@
+# 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 复合约束模块
+
+功能概述:
+- 将多个子约束组织为一个逻辑单元，按策略聚合校验结果
+- 支持三种逻辑策略：all（全部通过）、any（至少一个通过）、none（全部失败）
+- 子约束在配置文件中以内嵌列表形式存储，不生成独立文件
+
+架构设计:
+- 继承 Constraint 基类，遵循统一的 validate() 接口
+- 递归调用子约束的 validate()，收集结果后按 logic 策略聚合
+- 子约束通过工厂递归创建，保持与独立约束相同的运行时类型
+
+输入示例:
+    CompositeConstraint(
+        sub_constraints=[
+            UniqueConstraint(table="users", column=["email"]),
+            NotNullConstraint(table="users", column="name"),
+        ],
+        logic="all",
+        refs={"table_id": "users"},
+    )
+
+输出示例:
+    result = composite.validate(datasets)
+    # logic="all" 时，返回所有子约束错误的并集
+    # logic="any" 时，若至少一个子约束无错则返回空错误列表
+    # logic="none" 时，若全部子约束有错则返回空错误列表
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from .base import Constraint
+
+
+class CompositeConstraint(Constraint):
+    """@classdesc 复合约束
+
+    包含多个子约束，按指定的逻辑策略聚合校验结果。
+
+    字段说明:
+        - sub_constraints: 子约束实例列表
+        - logic: 聚合策略 ("all" | "any" | "none")
+        - refs: 引用区（通常包含 table_id 等）
+        - enabled: 是否启用（继承属性）
+    """
+
+    def __init__(
+        self,
+        sub_constraints: list[Constraint],
+        logic: str = "all",
+        refs: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ):
+        self.sub_constraints = sub_constraints
+        self.logic = logic
+        self.refs = refs or {}
+        # 兼容基类中可能存在的 table 属性访问
+        self.table = self.refs.get("table_id")
+
+    def validate(self, datasets: dict[str, pd.DataFrame], **kwargs: Any) -> dict[str, Any]:
+        """@methoddesc 执行复合约束验证
+
+        遍历所有子约束，递归调用 validate()，然后按 logic 策略聚合结果。
+
+        参数:
+            datasets: 数据集字典
+            **kwargs: 透传给子约束的额外参数（如 allow_unsafe_eval）
+
+        返回:
+            {"errors": [...], "info": {...}}
+        """
+        # 如果没有子约束，直接视为通过
+        if not self.sub_constraints:
+            return {"errors": [], "info": {}}
+
+        sub_results: list[dict[str, Any]] = []
+        for sub in self.sub_constraints:
+            # 跳过未启用的子约束（若子约束有 enabled 属性）
+            if not getattr(sub, "enabled", True):
+                continue
+            result = sub.validate(datasets, **kwargs)
+            sub_results.append(result)
+
+        # 如果没有启用的子约束，视为通过
+        if not sub_results:
+            return {"errors": [], "info": {}}
+
+        all_errors: list[dict[str, Any]] = []
+        # 回归 D7: 复合约束自身的 info(含 constraint_type/description)不应被子约束覆盖。
+        # 原实现 all_info.update(info) 让最后一个子约束的 constraint_type 覆盖复合约束,
+        # 导致报告中复合约束被错标为"最后一个子约束的类型"。先以复合约束自身 info 为基底,
+        # 再聚合子约束信息,但标识类字段(constraint_type/description/logic 等)不被覆盖。
+        all_info: dict[str, Any] = self.get_constraint_info()
+        protected_keys = {"constraint_type", "description", "logic", "sub_constraint_count", "table"}
+        passed_count = 0
+
+        for result in sub_results:
+            errors = result.get("errors", [])
+            info = result.get("info", {})
+            for k, v in info.items():
+                if k not in protected_keys:
+                    all_info[k] = v
+            if not errors:
+                passed_count += 1
+            else:
+                all_errors.extend(errors)
+
+        # 根据 logic 策略决定最终错误列表
+        final_errors: list[dict[str, Any]] = []
+
+        if self.logic == "all":
+            # 所有子约束都必须通过：返回所有错误的并集
+            final_errors = all_errors
+
+        elif self.logic == "any":
+            # 至少一个子约束通过即算通过
+            if passed_count == 0:
+                final_errors = [
+                    {
+                        "error_type": "CompositeConstraint",
+                        "message": (
+                            f"复合约束（logic=any）要求至少一个子约束通过，但全部 {len(sub_results)} 个子约束均失败"
+                        ),
+                        "table": self.table,
+                    }
+                ]
+
+        elif self.logic == "none":
+            # 所有子约束都必须失败才算通过（反向校验）
+            if passed_count > 0:
+                final_errors = [
+                    {
+                        "error_type": "CompositeConstraint",
+                        "message": (f"复合约束（logic=none）要求全部子约束失败，但有 {passed_count} 个子约束通过"),
+                        "table": self.table,
+                    }
+                ]
+
+        else:
+            # 未知逻辑策略，回退到 all 行为
+            final_errors = all_errors
+
+        return {"errors": final_errors, "info": all_info}
+
+    def get_constraint_info(self) -> dict[str, Any]:
+        """@methoddesc 获取复合约束的元信息"""
+        info = super().get_constraint_info()
+        info["logic"] = self.logic
+        info["sub_constraint_count"] = len(self.sub_constraints)
+        return info
+
+    def _get_description(self) -> str:
+        """@methoddesc 获取描述信息"""
+        return f"Composite 约束（logic={self.logic}，包含 {len(self.sub_constraints)} 个子约束）"

app/shared/domain/constraints/condition_registry.py

@@ -0,0 +1,130 @@
+# 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 条件注册表模块
+
+功能概述:
+- 维护全局 CONDITION_REGISTRY 字典，管理条件判断函数
+- 提供 register_condition 装饰器，支持通过字符串名称注册和引用条件函数
+- 内置常用条件函数：is_not_empty、is_positive_number 等
+- 供 ConditionalConstraint 引用已注册的条件函数
+
+架构设计:
+- 装饰器注册模式: 通过 @register_condition("name") 将函数注册到全局字典
+- 运行时可覆盖: 重复注册时发出警告并覆盖
+
+输入示例:
+    @register_condition("is_adult")
+    def is_adult(value):
+        return value >= 18
+
+    # 在约束配置中通过 "is_adult" 引用
+
+输出示例:
+    CONDITION_REGISTRY = {"is_not_empty": <function>, "is_adult": <function>}
+"""
+
+from __future__ import annotations
+
+# 1. 标准库导入
+import logging
+from collections.abc import Callable
+from typing import Any
+
+# 2. 第三方库导入
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+# ============================================================================
+# 全局条件注册表
+# ============================================================================
+# CONDITION_REGISTRY 是一个全局字典，用于存储所有已注册的条件判断函数。
+# 键为条件名称（字符串），值为对应的判断函数（接收任意参数，返回布尔值）。
+# ConditionalConstraint 可以通过字符串名称引用这里注册的条件函数。
+CONDITION_REGISTRY: dict[str, Callable[[Any], bool]] = {}
+
+
+def register_condition(name: str) -> Callable[[Callable[[Any], bool]], Callable[[Any], bool]]:
+    r"""
+    @functiondesc 条件函数注册装饰器
+
+    用于将条件判断函数注册到 CONDITION_REGISTRY 中。
+    支持通过字符串引用已注册的条件函数，实现配置的灵活性。
+
+    参数:
+        name: 条件函数名称，后续可通过此名称引用
+
+    返回:
+        装饰器函数，接收原始函数并返回原始函数
+
+    副作用:
+        修改全局 CONDITION_REGISTRY 字典
+
+    示例:
+        @register_condition("is_adult")
+        def is_adult(value):
+            return value >= 18
+
+        # 之后可以通过 CONDITION_REGISTRY["is_adult"](20) 调用
+    """
+
+    def decorator(func: Callable[[Any], bool]) -> Callable[[Any], bool]:
+        # 如果名称已存在，发出警告并覆盖
+        if name in CONDITION_REGISTRY:
+            logger.warning(f"警告: 正在覆盖已注册的条件 '{name}'")
+        CONDITION_REGISTRY[name] = func
+        return func
+
+    return decorator
+
+
+@register_condition("is_not_empty")
+def _is_not_empty(value: Any) -> bool:
+    """
+    @functiondesc 判断值是否非空
+
+    判断逻辑: 不是 NaN(通过 pandas.notna 判断) 且不是空字符串
+
+    参数:
+        value: 任意类型的值
+
+    返回:
+        True 表示值非空，False 表示值为空（None、NaN、空字符串）
+    """
+
+    return bool(pd.notna(value)) and value != ""
+
+
+@register_condition("is_positive_number")
+def _is_positive_number(value: Any) -> bool:
+    """
+    @functiondesc 判断值是否为正数
+
+    尝试将值转换为浮点数并判断是否大于 0。
+    转换失败时返回 False（这是保守策略，避免误判）。
+
+    参数:
+        value: 任意类型的值
+
+    返回:
+        True 表示值是正数，False 表示值不是正数或无法转换为数字
+    """
+
+    try:
+        return float(value) > 0
+    except (ValueError, TypeError):
+        return False