precis-cli 0.1.3__py3-none-any.whl

app/shared/domain/transforms/math_expr.py

@@ -0,0 +1,112 @@
+# 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 MathExpr 转换运行器
+
+功能概述:
+- 使用 simpleeval 沙箱计算数学表达式（B-sec5: 替代原 pandas.DataFrame.eval，消除注入面）
+- 支持引用现有列作为变量
+
+参数:
+    expression: 数学表达式字符串，如 "@col_a + @col_b * 2" 或 "col_a + col_b * 2"
+               （支持 @列名 语法，会自动转换为列名引用）
+    output_type: 输出类型（int, float, 默认保持原样）
+
+安全说明:
+    - B-sec5: 原实现用 pandas.DataFrame.eval，其 @语法可访问局部变量/可调用对象，
+      在不同 pandas 版本/引擎下存在逃逸面；表达式来自用户写入的 transforms/*.yaml，
+      构成存储型代码注入风险。现改用 simpleeval（与 Scripted 约束同一沙箱），
+      仅允许 SAFE_FUNCTIONS 白名单内的纯函数，禁用属性访问与 dunder。
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import pandas as pd
+
+from app.shared.domain.eval_sandbox import make_sandbox_evaluator
+
+from .base import TransformRunner
+
+
+class MathExprRunner(TransformRunner):
+    """@classdesc 数学表达式转换运行器"""
+
+    def execute(
+        self,
+        df: pd.DataFrame,
+        input_column: str,
+        params: dict[str, Any],
+        output_columns: list[str],
+    ) -> pd.DataFrame:
+        """
+        @methoddesc 执行 数学表达式转换
+
+        业务用途:
+        - TransformRunner 协议的标准入口，由 transform 节点调用
+        - 读取 params 中的转换参数，对 input_column 应用转换，输出到 output_columns
+
+        参数:
+            df: 源 DataFrame
+            input_column: 输入列名
+            params: 转换参数字典
+            output_columns: 目标输出列名列表
+
+        返回:
+            转换后的 DataFrame
+        """
+        expression = params.get("expression", "")
+        output_type = params.get("output_type", None)
+
+        if not expression:
+            raise ValueError("MathExpr 需要 expression 参数")
+
+        if not output_columns:
+            raise ValueError("MathExpr 需要至少一个 output_columns")
+
+        output_col = output_columns[0]
+
+        # 支持 @列名 语法：simpleeval 的变量绑定即列名字面量，故去除 @ 前缀。
+        eval_expression = re.sub(r"@(\w+)", r"\1", expression)
+
+        # B-sec5: 逐行用 simpleeval 沙箱求值（替代 df.eval 的注入面）。
+        # names 注入该行所有列值（col_name -> cell_value），表达式如 "a + b" 直接引用列名。
+        results: list[Any] = []
+        # to_dict("records") 比 iterrows 快，且每行独立绑定避免跨行状态泄漏。
+        for record in df.to_dict("records"):
+            try:
+                value = make_sandbox_evaluator(names=record).eval(eval_expression)
+            except Exception as e:
+                raise ValueError(f"数学表达式计算失败: {expression}, 错误: {e}")
+            results.append(value)
+
+        result_series = pd.Series(results, index=df.index)
+
+        if output_type == "int":
+            try:
+                df[output_col] = pd.to_numeric(result_series, errors="coerce").astype("Int64")
+            except (TypeError, ValueError):
+                # 小数结果（如 7 / 2）无法安全转可空整数，保留 float 结果；
+                # 原实现此处抛未捕获 TypeError，一行小数即炸整条转换。
+                df[output_col] = pd.to_numeric(result_series, errors="coerce")
+        elif output_type == "float":
+            df[output_col] = pd.to_numeric(result_series, errors="coerce")
+        else:
+            df[output_col] = result_series
+
+        return df

app/shared/domain/transforms/modulo.py

@@ -0,0 +1,82 @@
+# 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 Modulo 转换运行器
+
+功能概述:
+- 对数值列取模运算
+
+参数:
+    divisor: 除数（模数），默认 1
+
+输入输出:
+    输入: 266
+    输出: 2 (266 % 11)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from .base import TransformRunner
+
+
+class ModuloRunner(TransformRunner):
+    """@classdesc 取模转换运行器"""
+
+    def execute(
+        self,
+        df: pd.DataFrame,
+        input_column: str,
+        params: dict[str, Any],
+        output_columns: list[str],
+    ) -> pd.DataFrame:
+        """
+        @methoddesc 执行 取模转换
+
+        业务用途:
+        - TransformRunner 协议的标准入口，由 transform 节点调用
+        - 读取 params 中的转换参数，对 input_column 应用转换，输出到 output_columns
+
+        参数:
+            df: 源 DataFrame
+            input_column: 输入列名
+            params: 转换参数字典
+            output_columns: 目标输出列名列表
+
+        返回:
+            转换后的 DataFrame
+        """
+        divisor = params.get("divisor", 1)
+        if divisor == 0:
+            raise ValueError("Modulo 的 divisor 不能为 0")
+
+        if input_column not in df.columns:
+            raise ValueError(f"输入列不存在: {input_column}")
+
+        output_col = output_columns[0] if output_columns else "modulo_result"
+
+        df[output_col] = pd.to_numeric(df[input_column], errors="coerce") % divisor
+        try:
+            df[output_col] = df[output_col].astype("Int64")
+        except (TypeError, ValueError):
+            # 小数余数（如 2.5 % 2 = 0.5）无法安全转可空整数，保留 float 结果；
+            # 原实现此处抛未捕获 TypeError，一行小数即炸整条转换。
+            pass
+
+        return df

app/shared/domain/transforms/regex_extract.py

@@ -0,0 +1,103 @@
+# 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 RegexExtract 转换运行器
+
+功能概述:
+- 使用正则表达式从字符串中提取捕获组
+- 输出多个新列（每个捕获组一列）
+
+参数:
+    pattern: 正则表达式模式（必须包含捕获组）
+    flags: 正则标志（如 "i" 表示忽略大小写）
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import pandas as pd
+
+from .base import TransformRunner, stringify_preserve_null
+
+
+class RegexExtractRunner(TransformRunner):
+    """@classdesc 正则提取转换运行器"""
+
+    def execute(
+        self,
+        df: pd.DataFrame,
+        input_column: str,
+        params: dict[str, Any],
+        output_columns: list[str],
+    ) -> pd.DataFrame:
+        """
+        @methoddesc 执行 正则提取转换
+
+        业务用途:
+        - TransformRunner 协议的标准入口，由 transform 节点调用
+        - 读取 params 中的转换参数，对 input_column 应用转换，输出到 output_columns
+
+        参数:
+            df: 源 DataFrame
+            input_column: 输入列名
+            params: 转换参数字典
+            output_columns: 目标输出列名列表
+
+        返回:
+            转换后的 DataFrame
+        """
+        pattern = params.get("pattern", "")
+        flags_str = params.get("flags", "")
+
+        if not pattern:
+            raise ValueError("RegexExtract 需要 pattern 参数")
+
+        if input_column not in df.columns:
+            raise ValueError(f"输入列不存在: {input_column}")
+
+        # flags 整词匹配（与 regex 约束/reader 同一套 token 语义），不得子串包含
+        _flag_short_map = {"i": re.IGNORECASE, "m": re.MULTILINE, "s": re.DOTALL}
+        flag_values = 0
+        for tok in [t for t in re.split(r"[,\s]+", str(flags_str).strip()) if t]:
+            if all(ch in _flag_short_map for ch in tok.lower()):
+                for ch in tok.lower():
+                    flag_values |= _flag_short_map[ch]
+
+        compiled = re.compile(pattern, flag_values)
+
+        def _extract(text: str | None) -> list[str | None]:
+            if text is None:
+                # 空值不参与提取（原 astype(str) 把空值字符串化为 "nan" 参与匹配）
+                return [None] * len(output_columns)
+            m = compiled.search(text)
+            if not m:
+                return [None] * len(output_columns)
+            groups = m.groups()
+            result: list[str | None] = []
+            for i in range(len(output_columns)):
+                if i < len(groups):
+                    result.append(groups[i])
+                else:
+                    result.append(None)
+            return result
+
+        extracted = stringify_preserve_null(df[input_column]).apply(_extract)
+        for i, col_name in enumerate(output_columns):
+            df[col_name] = extracted.apply(lambda x: x[i] if x else None)
+
+        return df

app/shared/domain/transforms/registry.py

@@ -0,0 +1,95 @@
+# 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 运行器注册表
+
+功能概述:
+- 将 TransformFile.type 映射到对应的 TransformRunner 类
+- 提供统一的 create_runner(type_name) 工厂函数
+
+使用示例:
+    runner = create_runner("StringSplit")
+    df = runner.execute(df, "name", {"delimiter": " "}, ["first_name", "last_name"])
+"""
+
+from __future__ import annotations
+
+from .aggregate import AggregateRunner
+from .base import TransformRunner
+from .cast_type import CastTypeRunner
+from .concat import ConcatRunner
+from .conditional_assign import ConditionalAssignRunner
+from .date_format import DateFormatRunner
+from .digits import DigitsRunner
+from .drop_duplicates import DropDuplicatesRunner
+from .fill_na import FillNARunner
+from .filter_rows import FilterRowsRunner
+from .lookup import LookupRunner
+from .lower_case import LowerCaseRunner
+from .map_value import MapValueRunner
+from .math_expr import MathExprRunner
+from .modulo import ModuloRunner
+from .regex_extract import RegexExtractRunner
+from .replace import ReplaceRunner
+from .sort_rows import SortRowsRunner
+from .string_split import StringSplitRunner
+from .strip import StripRunner
+from .substring import SubstringRunner
+from .upper_case import UpperCaseRunner
+from .weighted_sum import WeightedSumRunner
+
+TRANSFORM_REGISTRY: dict[str, type[TransformRunner]] = {
+    "StringSplit": StringSplitRunner,
+    "RegexExtract": RegexExtractRunner,
+    "MathExpr": MathExprRunner,
+    "DateFormat": DateFormatRunner,
+    "Lookup": LookupRunner,
+    "Strip": StripRunner,
+    "UpperCase": UpperCaseRunner,
+    "LowerCase": LowerCaseRunner,
+    "Replace": ReplaceRunner,
+    "FillNA": FillNARunner,
+    "CastType": CastTypeRunner,
+    "Concat": ConcatRunner,
+    "Substring": SubstringRunner,
+    "ConditionalAssign": ConditionalAssignRunner,
+    "Digits": DigitsRunner,
+    "WeightedSum": WeightedSumRunner,
+    "Modulo": ModuloRunner,
+    "MapValue": MapValueRunner,
+    "FilterRows": FilterRowsRunner,
+    "DropDuplicates": DropDuplicatesRunner,
+    "Aggregate": AggregateRunner,
+    "SortRows": SortRowsRunner,
+}
+
+
+def create_runner(type_name: str) -> TransformRunner:
+    """@methoddesc 根据类型名称创建 TransformRunner 实例
+
+    参数:
+        type_name: Transform 类型名称（如 "StringSplit"）
+
+    返回:
+        TransformRunner 实例
+
+    异常:
+        ValueError: 类型名称未注册
+    """
+    runner_class = TRANSFORM_REGISTRY.get(type_name)
+    if not runner_class:
+        raise ValueError(f"未注册的 Transform 类型: {type_name}，支持类型: {list(TRANSFORM_REGISTRY.keys())}")
+    return runner_class()

app/shared/domain/transforms/replace.py

@@ -0,0 +1,88 @@
+# 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 Replace 转换运行器
+
+功能概述:
+- 将字符串中的指定内容替换为新内容
+- 支持控制替换次数
+
+参数:
+    old: 要被替换的内容（必填）
+    new: 替换后的新内容（默认空字符串）
+    count: 最大替换次数（默认 -1，替换所有）
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from .base import TransformRunner, stringify_preserve_null
+
+
+class ReplaceRunner(TransformRunner):
+    """@classdesc 字符串替换转换运行器"""
+
+    def execute(
+        self,
+        df: pd.DataFrame,
+        input_column: str,
+        params: dict[str, Any],
+        output_columns: list[str],
+    ) -> pd.DataFrame:
+        """
+        @methoddesc 执行 字符串替换转换
+
+        业务用途:
+        - TransformRunner 协议的标准入口，由 transform 节点调用
+        - 读取 params 中的转换参数，对 input_column 应用转换，输出到 output_columns
+
+        参数:
+            df: 源 DataFrame
+            input_column: 输入列名
+            params: 转换参数字典
+            output_columns: 目标输出列名列表
+
+        返回:
+            转换后的 DataFrame
+        """
+        old = params.get("old")
+        new = params.get("new", "")
+        count = params.get("count", -1)
+
+        # §1.17: old 缺省/显式空串报配置错误——原实现 "" 兜底触发 str.replace("", "X")
+        # 的逐字符插入，输出列变 "XaXbXcX" 垃圾数据。new 缺省 "" 是合法删除语义，保持。
+        if old is None or old == "":
+            raise ValueError("Replace 转换缺少必填参数 old（被替换内容不能为空）")
+
+        if input_column not in df.columns:
+            raise ValueError(f"输入列不存在: {input_column}")
+
+        if not output_columns:
+            raise ValueError("Replace 需要至少一个 output_columns")
+
+        output_col = output_columns[0]
+        # 空值透传为 None，替换不作用于空值
+        series = stringify_preserve_null(df[input_column])
+
+        if count == -1:
+            df[output_col] = series.str.replace(old, new, regex=False)
+        else:
+            df[output_col] = series.str.replace(old, new, n=count, regex=False)
+
+        return df

app/shared/domain/transforms/sort_rows.py

@@ -0,0 +1,94 @@
+# 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 SortRows 转换运行器
+
+功能概述:
+- 对 DataFrame 按指定列和方向排序
+- 支持多列排序
+
+参数:
+    sort_by: 排序规则列表 [{column, order}]
+        - column: 排序列名
+        - order: 排序方向 ("asc"|"desc")
+
+说明:
+    - input_column 被忽略（操作整行而非单列）
+    - output_columns 被忽略（不产生新列，保留所有原始列）
+    - 输出 DataFrame 索引重置为连续 0-based
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from .base import TransformRunner
+
+
+class SortRowsRunner(TransformRunner):
+    """@classdesc 排序转换运行器"""
+
+    def execute(
+        self,
+        df: pd.DataFrame,
+        input_column: str,
+        params: dict[str, Any],
+        output_columns: list[str],
+    ) -> pd.DataFrame:
+        """
+        @methoddesc 执行 排序转换
+
+        业务用途:
+        - TransformRunner 协议的标准入口，由 transform 节点调用
+        - 读取 params 中的转换参数，对 input_column 应用转换，输出到 output_columns
+
+        参数:
+            df: 源 DataFrame
+            input_column: 输入列名
+            params: 转换参数字典
+            output_columns: 目标输出列名列表
+
+        返回:
+            转换后的 DataFrame
+        """
+        sort_by = params.get("sort_by", [])
+
+        if not sort_by:
+            # 无排序规则时保持原序
+            return df.reset_index(drop=True)
+
+        # 解析排序规则
+        columns = []
+        ascending = []
+        for rule in sort_by:
+            col = rule.get("column", "")
+            if col not in df.columns:
+                raise ValueError(f"排序列不存在: {col}")
+            columns.append(col)
+            # order 归一大小写不敏感（"ASC"/"Desc" 均合法），未知值 fail-fast——不再静默按降序
+            raw_order = rule.get("order", "asc")
+            order = str(raw_order).lower()
+            if order == "asc":
+                ascending.append(True)
+            elif order == "desc":
+                ascending.append(False)
+            else:
+                raise ValueError(f"未知的排序方向 '{raw_order}'，支持的值为: asc, desc")
+
+        result = df.sort_values(by=columns, ascending=ascending).reset_index(drop=True)
+        return result

app/shared/domain/transforms/string_split.py

@@ -0,0 +1,84 @@
+# 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 StringSplit 转换运行器
+
+功能概述:
+- 按分隔符或固定位置切割字符串
+- 输出多个新列
+
+参数:
+    delimiter: 分隔符字符串（默认 " "）
+    maxsplit: 最大分割次数（默认 -1，不限制）
+    expand: 是否展开为多列（默认 True）
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from .base import TransformRunner, stringify_preserve_null
+
+
+class StringSplitRunner(TransformRunner):
+    """@classdesc 字符串切割转换运行器"""
+
+    def execute(
+        self,
+        df: pd.DataFrame,
+        input_column: str,
+        params: dict[str, Any],
+        output_columns: list[str],
+    ) -> pd.DataFrame:
+        """
+        @methoddesc 执行 字符串分割转换
+
+        业务用途:
+        - TransformRunner 协议的标准入口，由 transform 节点调用
+        - 读取 params 中的转换参数，对 input_column 应用转换，输出到 output_columns
+
+        参数:
+            df: 源 DataFrame
+            input_column: 输入列名
+            params: 转换参数字典
+            output_columns: 目标输出列名列表
+
+        返回:
+            转换后的 DataFrame
+        """
+        delimiter = params.get("delimiter", " ")
+        maxsplit = params.get("maxsplit", -1)
+
+        if input_column not in df.columns:
+            raise ValueError(f"输入列不存在: {input_column}")
+
+        # 空值透传为 None：原 astype(str) 把空值字符串化为 "nan" 参与切分
+        series = stringify_preserve_null(df[input_column])
+
+        if maxsplit == -1:
+            split_df = series.str.split(delimiter, expand=True)
+        else:
+            split_df = series.str.split(delimiter, n=maxsplit, expand=True)
+
+        for i, col_name in enumerate(output_columns):
+            if i < split_df.shape[1]:
+                df[col_name] = split_df[i]
+            else:
+                df[col_name] = None
+
+        return df