precis-cli 0.1.3__py3-none-any.whl

app/shared/domain/transforms/date_format.py

@@ -0,0 +1,81 @@
+# 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 DateFormat 转换运行器
+
+功能概述:
+- 将日期字符串从一种格式转换为另一种格式
+- 支持解析失败时的容错处理
+
+参数:
+    input_format: 输入日期格式（默认 "%Y-%m-%d"）
+    output_format: 输出日期格式（默认 "%Y/%m/%d"）
+    errors: 错误处理策略（"coerce" 转为 NaT, "raise" 抛出异常, "ignore" 保留原值）
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from .base import TransformRunner
+
+
+class DateFormatRunner(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
+        """
+        input_format = params.get("input_format", "%Y-%m-%d")
+        output_format = params.get("output_format", "%Y/%m/%d")
+        errors = params.get("errors", "coerce")
+
+        if input_column not in df.columns:
+            raise ValueError(f"输入列不存在: {input_column}")
+
+        if not output_columns:
+            raise ValueError("DateFormat 需要至少一个 output_columns")
+
+        output_col = output_columns[0]
+
+        parsed = pd.to_datetime(df[input_column], format=input_format, errors=errors)
+        formatted = parsed.dt.strftime(output_format)
+        formatted = formatted.where(parsed.notna(), None)
+        df[output_col] = formatted
+
+        return df

app/shared/domain/transforms/digits.py

@@ -0,0 +1,77 @@
+# 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 Digits 转换运行器
+
+功能概述:
+- 将字符串的每个字符拆分为逗号分隔的数字字符串
+- 保持行数不变，输出单列字符串（如 "1,1,0,1,0,1"）
+
+参数:
+    无
+
+输入输出:
+    输入: "11010119900307889"（字符串）
+    输出: "1,1,0,1,0,1,1,9,9,0,0,3,0,7,8,8,9"（逗号分隔）
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from .base import TransformRunner, stringify_preserve_null
+
+
+class DigitsRunner(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
+        """
+        if input_column not in df.columns:
+            raise ValueError(f"输入列不存在: {input_column}")
+
+        output_col = output_columns[0] if output_columns else "digits"
+
+        # 将每个字符用逗号连接，保持行数不变
+        # 空值透传为 None，不产生 "nan" 拆位
+        df[output_col] = stringify_preserve_null(df[input_column]).apply(
+            lambda s: None if s is None else ",".join(list(s))
+        )
+
+        return df

app/shared/domain/transforms/drop_duplicates.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 DropDuplicates 转换运行器
+
+功能概述:
+- 对 DataFrame 进行去重
+- 支持指定子集列（逗号分隔）或全列去重
+- 支持保留策略：first（保留第一条）、last（保留最后一条）、false（全部删除）
+
+参数:
+    subset: 去重列名，支持逗号分隔字符串或列表，留空则基于全部列去重
+    keep: 保留策略 ("first"|"last"|"false")
+
+说明:
+    - input_column 被忽略（操作整行而非单列）
+    - output_columns 被忽略（不产生新列，保留所有原始列）
+    - 输出 DataFrame 索引重置为连续 0-based
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from .base import TransformRunner
+
+
+class DropDuplicatesRunner(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
+        """
+        keep = params.get("keep", "first")
+        subset_raw = params.get("subset", "")
+
+        # 解析 subset：兼容逗号分隔字符串与列表两种格式
+        # 前端 tags 产出的是数组，旧配置/手写 YAML 可能是逗号分隔字符串
+        subset = None
+        if subset_raw:
+            if isinstance(subset_raw, list):
+                parsed = [str(col).strip() for col in subset_raw if str(col).strip()]
+            else:
+                parsed = [col.strip() for col in str(subset_raw).split(",") if col.strip()]
+            # §1.16: 拼错列名报配置错误——原实现静默剔除后走全列去重，
+            # 去重结果比预期多、下游统计偏大且无提示。空 subset（未配置）保持全列去重。
+            missing = [col for col in parsed if col not in df.columns]
+            if missing:
+                raise ValueError(f"subset 列不存在: {missing}（表列: {list(df.columns)}）")
+            if parsed:
+                subset = parsed
+
+        # pandas 的 keep 参数：keep=False 表示全部删除
+        keep_param: str | bool = keep
+        if keep == "false":
+            keep_param = False
+
+        result = df.drop_duplicates(subset=subset, keep=keep_param).reset_index(drop=True)
+        return result

app/shared/domain/transforms/fill_na.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 FillNA 转换运行器
+
+功能概述:
+- 填充空值（NaN/None）
+- 支持多种填充策略：固定值、前向填充、后向填充、均值、中位数
+
+参数:
+    strategy: 填充策略 ("value"|"ffill"|"bfill"|"mean"|"median")
+    value: 当 strategy=="value" 时的填充值
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from .base import TransformRunner
+
+
+class FillNARunner(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
+        """
+        strategy = params.get("strategy", "value")
+
+        if input_column not in df.columns:
+            raise ValueError(f"输入列不存在: {input_column}")
+
+        if not output_columns:
+            raise ValueError("FillNA 需要至少一个 output_columns")
+
+        output_col = output_columns[0]
+        series = df[input_column].copy()
+
+        if strategy == "value":
+            fill_value = params.get("value", "")
+            series = series.fillna(fill_value)
+        elif strategy == "ffill":
+            series = series.ffill()
+        elif strategy == "bfill":
+            series = series.bfill()
+        elif strategy in ("mean", "median"):
+            # §1.6: 只填真正的空值，非空非数值值保留原样——原实现整列 coerce 后 fillna，
+            # "abc" 这类非空脏值被顺带清洗成均值（用户没要求清洗，原始信息无声丢失）。
+            # 均值只对"能转数值的非空值"计算；填充后输出列为 object（混合类型）是预期。
+            numeric_series = pd.to_numeric(series, errors="coerce")
+            stat = numeric_series.mean() if strategy == "mean" else numeric_series.median()
+            filled = series.copy()
+            filled[series.isna()] = stat
+            series = filled
+        else:
+            raise ValueError(f"不支持的 FillNA 策略: {strategy}")
+
+        df[output_col] = series
+        return df

app/shared/domain/transforms/filter_rows.py

@@ -0,0 +1,97 @@
+# 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 FilterRows 转换运行器
+
+功能概述:
+- 按条件过滤行，返回满足条件的行子集
+- 支持多条件组合（AND/OR 逻辑）
+- 支持 eq/ne/gt/gte/lt/lte/contains/startswith/endswith/in/not_in/is_null/is_not_null 操作符
+
+参数:
+    conditions: 条件列表 [{column, op, value}]
+    logic: 条件组合逻辑 ("and"|"or")
+
+说明:
+    - input_column 被忽略（操作整行而非单列）
+    - output_columns 被忽略（不产生新列，保留所有原始列）
+    - 输出 DataFrame 索引重置为连续 0-based
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from .base import TransformRunner, evaluate_condition
+
+
+class FilterRowsRunner(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
+        """
+        conditions = params.get("conditions", [])
+        # logic 归一大小写不敏感（"OR"/"And" 均合法），未知值 fail-fast——不再静默按 AND 组合
+        raw_logic = params.get("logic", "and")
+        logic = str(raw_logic).lower()
+        if logic not in ("and", "or"):
+            raise ValueError(f"未知的 logic '{raw_logic}'，支持的值为: and, or")
+
+        if not conditions:
+            # 无条件时保留所有行
+            return df.reset_index(drop=True)
+
+        # 逐个评估条件，生成布尔掩码
+        masks = []
+        for cond in conditions:
+            mask = evaluate_condition(df, cond)
+            masks.append(mask)
+
+        # 组合条件
+        if logic == "or":
+            combined = masks[0]
+            for m in masks[1:]:
+                combined = combined | m
+        else:
+            combined = masks[0]
+            for m in masks[1:]:
+                combined = combined & m
+
+        result = df.loc[combined].reset_index(drop=True)
+        return result

app/shared/domain/transforms/lookup.py

@@ -0,0 +1,78 @@
+# 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 Lookup 转换运行器
+
+功能概述:
+- 根据映射表精确替换列值
+- 支持默认值回退
+
+参数:
+    mapping: 字典映射 {旧值: 新值}
+    default: 未匹配时的默认值（默认 None）
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from .base import TransformRunner
+
+
+class LookupRunner(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
+        """
+        mapping = params.get("mapping", {})
+        default = params.get("default", None)
+
+        if input_column not in df.columns:
+            raise ValueError(f"输入列不存在: {input_column}")
+
+        if not output_columns:
+            raise ValueError("Lookup 需要至少一个 output_columns")
+
+        output_col = output_columns[0]
+
+        df[output_col] = df[input_column].map(mapping)
+        if default is not None:
+            df[output_col] = df[output_col].fillna(default)
+
+        return df

app/shared/domain/transforms/lower_case.py

@@ -0,0 +1,70 @@
+# 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 LowerCase 转换运行器
+
+功能概述:
+- 将字符串转换为小写
+
+参数:
+    无
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from .base import TransformRunner, stringify_preserve_null
+
+
+class LowerCaseRunner(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
+        """
+        if input_column not in df.columns:
+            raise ValueError(f"输入列不存在: {input_column}")
+
+        if not output_columns:
+            raise ValueError("LowerCase 需要至少一个 output_columns")
+
+        output_col = output_columns[0]
+        df[output_col] = stringify_preserve_null(df[input_column]).str.lower()
+
+        return df

app/shared/domain/transforms/map_value.py

@@ -0,0 +1,90 @@
+# 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 MapValue 转换运行器
+
+功能概述:
+- 以上游值作为索引，查表映射到对应元素
+- 索引越界或无法解析时保留原值
+
+参数:
+    mapping: 映射数组（如 ["1","0","X","9","8","7","6","5","4","3","2"]）
+
+输入输出:
+    输入: 2
+    输出: "X"（mapping[2]）
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from .base import TransformRunner
+
+
+class MapValueRunner(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
+        """
+        mapping = params.get("mapping", [])
+        if not mapping:
+            raise ValueError("MapValue 需要 mapping 参数")
+
+        if input_column not in df.columns:
+            raise ValueError(f"输入列不存在: {input_column}")
+
+        output_col = output_columns[0] if output_columns else "mapped"
+
+        mapping_arr = list(mapping)
+        numeric_idx = pd.to_numeric(df[input_column], errors="coerce")
+        # §1.24: 非整数索引报错——原实现 int(1.9) 向下截断当 1 查表，
+        # 用户预期"非整数索引无效"却拿到 mapping[1] 的值，错得毫无迹象
+        non_integer_mask = numeric_idx.notna() & (numeric_idx != numeric_idx.round())
+        if non_integer_mask.any():
+            first_idx = numeric_idx.index[non_integer_mask][0]
+            raise ValueError(f"map_value 索引 '{df[input_column][first_idx]}'（第 {first_idx} 行）不是整数，无法查表")
+        in_range = numeric_idx.notna() & (numeric_idx >= 0) & (numeric_idx < len(mapping_arr))
+        idx_int = numeric_idx.where(in_range)
+        mapped = idx_int.apply(
+            lambda x: mapping_arr[int(x)] if pd.notna(x) and 0 <= int(x) < len(mapping_arr) else None
+        )
+        df[output_col] = mapped.where(in_range, df[input_column])
+
+        return df