precis-cli 0.1.3__py3-none-any.whl

app/shared/domain/constraints/foreign_key.py

@@ -0,0 +1,261 @@
+# 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 外键约束模块
+
+功能概述:
+- 实现 ForeignKeyConstraints 类
+- 验证外键列的值是否在目标表的对应列中存在
+- 确保引用完整性: 子表的值必须在父表中存在
+
+架构设计:
+- 继承基类: 继承自 Constraint 抽象类
+- 引用验证: 检查 from_column 的值是否在 to_column 中存在
+- 值规范化: 自动处理类型转换和空值
+
+输入示例:
+    # 约束配置: orders.user_id 必须存在于 users.id 中
+    constraint = ForeignKeyConstraints(
+        from_table="orders",
+        from_column="user_id",
+        to_table="users",
+        to_column="id"
+    )
+
+    # 数据集输入
+    datasets = {
+        "users": DataFrame({
+            "id": [1, 2, 3],
+            "username": ["alice", "bob", "charlie"]
+        }),
+        "orders": DataFrame({
+            "id": [1, 2, 3],
+            "user_id": [1, 2, 99]  # 99 不在 users.id 中
+        })
+    }
+
+输出示例:
+    # 验证通过
+    {"errors": [], "info": {...}}
+
+    # 验证失败 (第3行 user_id=99 在 users 表中不存在)
+    {
+        "errors": [
+            {
+                "error_type": "ForeignKeyViolation",
+                "table": "orders",
+                "row_index": 2,
+                "column": "user_id",
+                "value": 99,
+                "message": "外键冲突: 值 '99' 在目标表 'users' 的列 'id' 中不存在。"
+            }
+        ],
+        "info": {
+            "constraint_type": "ForeignKeyConstraints",
+            "table": "orders",
+            "description": "外键约束: orders.user_id -> users.id"
+        }
+    }
+
+原理说明:
+    值规范化处理:
+    - 字符串前后空格会被去除
+    - "123.0" 会被规范化为 "123"
+    - 空字符串、None、NaN 会被规范化为 None (不检查)
+    - 布尔值会被转换为 "True"/"False"
+    - 浮点数会去掉小数点后的 .0
+"""
+
+from __future__ import annotations
+
+# 1. 标准库导入
+from typing import Any
+
+# 2. 第三方库导入
+import pandas as pd
+
+# 3. 项目内部导入
+from app.shared.domain.constraints.base import Constraint
+from app.shared.domain.constraints.key_normalization import (
+    integral_number_to_str,
+    strip_trailing_decimal_zeros,
+)
+
+
+class ForeignKeyConstraints(Constraint):
+    """
+    @classdesc 外键约束
+
+    验证数据列中的值是否在目标表的列中存在。
+    通过值规范化处理，支持不同数据类型之间的匹配。
+    """
+
+    def __init__(self, from_table: str, from_column: str, to_table: str, to_column: str):
+        """
+        @methoddesc 初始化外键约束
+
+        参数:
+            from_table: 子表名（包含外键列的表）
+            from_column: 子表中的外键列名
+            to_table: 父表名（被引用的表）
+            to_column: 父表中被引用的列名
+        """
+        self.from_table = from_table
+        self.from_column = from_column
+        self.to_table = to_table
+        self.to_column = to_column
+
+    def _get_description(self) -> str:
+        """生成外键约束描述，格式为 "外键约束: from_table.from_column -> to_table.to_column"""
+        return f"外键约束: {self.from_table}.{self.from_column} -> {self.to_table}.{self.to_column}"
+
+    def validate(self, datasets: dict[str, pd.DataFrame], **kwargs: Any) -> dict[str, Any]:
+        """
+        @methoddesc 执行外键验证
+
+        参数:
+            datasets: 数据集字典，键为表名，值为 pandas DataFrame
+            **kwargs: 额外的关键字参数（本方法不使用）
+
+        返回:
+            验证结果字典，包含 errors（错误列表）和 info（约束信息）
+
+        逻辑说明:
+            1. 检查 from_table 和 to_table 是否都在数据集中
+            2. 检查 from_column 和 to_column 是否存在于各自表中
+            3. 对目标列（父表）的值进行规范化，生成有效键集合
+            4. 对源列（子表）的值进行规范化，检查是否都在有效键集合中
+            5. 为不存在的键生成错误记录
+        """
+        errors: list[dict[str, Any]] = []
+
+        def _normalize_fk_value(value: Any) -> Any:
+            """
+            规范化外键值，统一不同数据类型的表示形式
+
+            规则:
+                - None、NaN、空字符串 -> None（跳过检查）
+                - 字符串 -> 去除前后空格；"123.0" 转为 "123"
+                - 布尔值 -> "True" 或 "False"
+                - 整数 -> 字符串形式
+                - 浮点数 -> 去掉末尾的 .0 后转字符串
+                - 其他类型 -> 转字符串并去除空格
+
+            参数:
+                value: 原始值
+
+            返回:
+                规范化后的值，或 None（表示应跳过检查）
+            """
+            # 空值统一返回 None，空值不视为外键违规
+            if value is None or (isinstance(value, float) and pd.isna(value)) or pd.isna(value):
+                return None
+
+            # 字符串: 去除前后空格，十进制形式去尾随零（与 float/Decimal 侧对称）
+            if isinstance(value, str):
+                s = value.strip()
+                if s == "":
+                    return None
+                # 回归 D4: 支持负号；§1.10: "123.10"→"123.1" 与 float 侧 str(123.10)="123.1" 同构，
+                # 消除父 float 123.10 vs 子 str "123.10" 的双侧不对称误报
+                return strip_trailing_decimal_zeros(s)
+
+            # 布尔值转为字符串 "True" 或 "False"
+            if isinstance(value, bool):
+                return str(value)
+
+            # 整数转为字符串
+            if isinstance(value, int):
+                return str(value)
+
+            # 浮点数: 如果是整数形式（如 123.0），去掉 .0 后转字符串
+            if isinstance(value, float):
+                integral = integral_number_to_str(value)
+                if integral is not None:
+                    return integral
+                return strip_trailing_decimal_zeros(str(value))
+
+            # 回归 D4: Decimal 是项目一等类型(decimal data_type),应与 float 一致归一。
+            # §1.10: 非整 Decimal("123.10") 也走去尾随零，与字符串/float 侧对称。
+            try:
+                from decimal import Decimal
+
+                if isinstance(value, Decimal):
+                    integral = integral_number_to_str(value)
+                    if integral is not None:
+                        return integral
+                    return strip_trailing_decimal_zeros(str(value).strip())
+            except (TypeError, ValueError):
+                pass
+
+            # 其他类型: 转字符串并去除空格
+            s = str(value).strip()
+            return s if s != "" else None
+
+        # 检查两张表是否都在数据集中
+        if self.from_table not in datasets or self.to_table not in datasets:
+            errors.append(
+                {
+                    "error_type": "ConstraintConfigError",
+                    "table": self.from_table,
+                    "column": self.from_column,
+                    "message": f"外键约束失败: 表 '{self.from_table}' 或 '{self.to_table}' 不在提供的数据集中。",
+                }
+            )
+            return {"errors": errors, "info": self.get_constraint_info()}
+
+        from_df = datasets[self.from_table]
+        to_df = datasets[self.to_table]
+
+        # 检查两列是否存在于各自表中
+        if self.from_column not in from_df.columns or self.to_column not in to_df.columns:
+            errors.append(
+                {
+                    "error_type": "ConstraintConfigError",
+                    "table": self.from_table,
+                    "column": self.from_column,
+                    "message": f"外键约束失败: 列 '{self.from_column}' 或 '{self.to_column}' 在其对应的表中不存在。",
+                }
+            )
+            return {"errors": errors, "info": self.get_constraint_info()}
+
+        # 对目标列（父表）的值进行规范化，并去除空值，生成有效键集合
+        normalized_target_series = to_df[self.to_column].map(_normalize_fk_value).dropna()
+        valid_keys = set(normalized_target_series)
+
+        # 对源列（子表）的值进行规范化
+        normalized_keys = from_df[self.from_column].map(_normalize_fk_value)
+        # 找出非空且不在有效键集合中的值
+        invalid_mask = normalized_keys.notna() & (~normalized_keys.isin(valid_keys))
+        invalid_rows = from_df[invalid_mask]
+
+        # 为每个无效的外键值生成错误记录
+        for row_tuple in invalid_rows[[self.from_column]].itertuples(index=True, name=None):
+            index = row_tuple[0]
+            key_to_check = row_tuple[1]
+            row_index = int(index) if index is not None else 0
+            errors.append(
+                {
+                    "error_type": "ForeignKeyViolation",
+                    "table": self.from_table,
+                    "row_index": row_index,
+                    "column": self.from_column,
+                    "value": key_to_check,
+                    "message": f"外键冲突: 值 '{key_to_check}' 在目标表 '{self.to_table}' 的列 '{self.to_column}' 中不存在。",
+                }
+            )
+
+        return {"errors": errors, "info": self.get_constraint_info()}

app/shared/domain/constraints/key_normalization.py

@@ -0,0 +1,56 @@
+# 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 约束键值数值归一化（domain 纯逻辑，FK 与 AllowedValues 共用）
+
+口径（2026-09-18 拍板 §1.10/§1.11）：
+- 尾随零双侧对称去除：123.10 ≡ 123.1（字符串/float/Decimal 同一语义）
+- Decimal 整数值规整为整数字符串：Decimal("1.0") ≡ 1
+- 去尾随零用字符串操作而非 float 中转，避免 17 位以上键值丢精度
+"""
+
+from __future__ import annotations
+
+import re
+from decimal import Decimal
+
+# 十进制形式（含小数点）的字符串；科学计数/非数值不匹配，原样返回
+_DECIMAL_STR_RE = re.compile(r"(-?\d+)\.(\d+)")
+
+
+def strip_trailing_decimal_zeros(s: str) -> str:
+    """十进制字符串去尾随零（"123.10"→"123.1"、"123.00"→"123"），非十进制形式原样返回。
+
+    不做 strip/大小写处理——调用方自行决定前后空白语义。
+    """
+    m = _DECIMAL_STR_RE.fullmatch(s)
+    if not m:
+        return s
+    frac = m.group(2).rstrip("0")
+    if not frac:
+        return m.group(1)
+    return f"{m.group(1)}.{frac}"
+
+
+def integral_number_to_str(v: float | Decimal) -> str | None:
+    """可整化的 float/Decimal 规整为整数字符串；不可整化返回 None。
+
+    判据与 FK 归一（foreign_key.py）一致：v == v.to_integral_value() / float.is_integer()。
+    """
+    if isinstance(v, Decimal):
+        return str(int(v)) if v == v.to_integral_value() else None
+    if isinstance(v, float):
+        return str(int(v)) if v.is_integer() else None
+    return None

app/shared/domain/constraints/not_null.py

@@ -0,0 +1,185 @@
+# 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 非空约束模块
+
+功能概述:
+- 实现 NotNullConstraint 类
+- 验证指定列的值是否为空
+
+架构设计:
+- 继承基类: 继承自 Constraint 抽象类
+- 简单验证: 使用 pandas isnull() 检测空值
+
+输入示例:
+    # 约束配置
+    constraint = NotNullConstraint(table="users", column="username")
+
+    # 数据集输入
+    datasets = {
+        "users": DataFrame({
+            "id": [1, 2, 3],
+            "username": ["alice", "bob", None],  # 第3行为空
+            "email": ["a@test.com", "b@test.com", "c@test.com"]
+        })
+    }
+
+输出示例:
+    # 验证通过
+    {
+        "errors": [],
+        "info": {
+            "constraint_type": "NotNullConstraint",
+            "table": "users",
+            "description": "非空约束: users.username"
+        }
+    }
+
+    # 验证失败 (第3行 username 为空)
+    {
+        "errors": [
+            {
+                "error_type": "NotNullViolation",
+                "table": "users",
+                "row_index": 2,
+                "column": "username",
+                "value": None,
+                "message": "非空约束冲突: 列 'username' 的值不能为空。"
+            }
+        ],
+        "info": {...}
+    }
+
+    # 配置错误 (列不存在)
+    {
+        "errors": [
+            {
+                "error_type": "ConstraintConfigError",
+                "table": "users",
+                "column": "nonexistent_column",
+                "message": "非空约束失败: 列 'nonexistent_column' 在表 'users' 中不存在。"
+            }
+        ],
+        "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 NotNullConstraint(Constraint):
+    """
+    @classdesc 非空约束
+
+    验证指定列中的每个值都不为空。
+    空值包括: None、NaN、以及仅包含空白字符的字符串。
+    """
+
+    def __init__(self, table: str, column: str):
+        """
+        @methoddesc 初始化非空约束
+
+        参数:
+            table: 目标表名
+            column: 目标列名
+        """
+        self.table = table
+        self.column = column
+
+    def _get_description(self) -> str:
+        """生成非空约束描述"""
+        return f"非空约束: {self.table}.{self.column}"
+
+    def validate(self, datasets: dict[str, pd.DataFrame], **kwargs: Any) -> dict[str, Any]:
+        """
+        @methoddesc 执行非空验证
+
+        参数:
+            datasets: 数据集字典，键为表名，值为 pandas DataFrame
+            **kwargs: 额外的关键字参数（本方法不使用）
+
+        返回:
+            验证结果字典，包含 errors（错误列表）和 info（约束信息）
+
+        逻辑说明:
+            1. 检查目标表是否存在于数据集中
+            2. 检查目标列是否存在于目标表中
+            3. 使用 pandas isnull() 检测空值
+            4. 对于字符串类型的列，额外检测仅包含空白字符的值
+            5. 为每个空值行生成错误记录
+        """
+        errors: list[dict[str, Any]] = []
+
+        # 检查目标表是否存在
+        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()}
+
+        col = df[self.column]
+
+        # 使用 pandas isnull() 检测 None、NaN 等空值
+        is_null = col.isnull()
+
+        # 对于 object 类型（通常是字符串），额外检测仅包含空白字符的值
+        # 如 "  "、"\t\n" 等也应视为空值
+        if col.dtype == object:
+            is_null = is_null | (col.astype(str).str.strip() == "")
+
+        # 遍历所有空值行，生成错误记录
+        for index in df[is_null].index:
+            row_index = int(index) if index is not None else 0
+            errors.append(
+                {
+                    "error_type": "NotNullViolation",
+                    "table": self.table,
+                    "row_index": row_index,
+                    "column": self.column,
+                    "value": None,
+                    "message": f"非空约束冲突: 列 '{self.column}' 的值不能为空。",
+                }
+            )
+
+        return {"errors": errors, "info": self.get_constraint_info()}