precis-cli 0.1.3__py3-none-any.whl

app/shared/core/data_source/loaders/converter.py

@@ -0,0 +1,337 @@
+# 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 TypeConverter 类型转换器
+
+功能概述:
+- 实现数据类型转换功能
+- 支持整数、浮点数、布尔值、字符串等类型转换
+- 提供统一的类型转换接口
+
+架构设计:
+- 独立的转换器类，职责单一
+- 支持批量转换和单个值转换
+- 完善的错误处理
+
+输入示例:
+    records = [{"id": "1", "amount": "12.5", "active": "true"}]
+    dtype = {"id": "int", "amount": "float", "active": "bool"}
+
+输出示例:
+    [{"id": 1, "amount": 12.5, "active": True}]
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from decimal import Decimal, InvalidOperation
+from typing import Any
+
+
+class TypeConverter:
+    """
+    @classdesc 数据类型转换器
+
+    ============================================================================
+    功能说明
+    ============================================================================
+    将数据记录中的指定列转换为目标类型。
+    支持的类型：int, integer, float, decimal, bool, str, string, date, datetime
+
+    ============================================================================
+    支持的类型
+    ============================================================================
+    - int/integer: 整数类型
+    - float: 浮点数类型（科学计算）
+    - decimal: 高精度小数类型（财务计算，使用 decimal.Decimal，避免 float 精度丢失）
+    - bool/boolean: 布尔类型
+    - str/string: 字符串类型
+    - date/datetime/timestamp: 日期/日期时间类型（datetime.date / datetime.datetime）
+
+    ============================================================================
+    业务场景
+    ============================================================================
+    - 数据清洗和类型规范化
+    - CSV/JSON 数据类型统一
+    - 数据导入前的类型预处理
+
+    ============================================================================
+    使用示例
+    ============================================================================
+    >>> converter = TypeConverter()
+    >>>
+    >>> records = [
+    ...     {"id": "1", "amount": "12.5", "active": "true"},
+    ...     {"id": "2", "amount": "23.7", "active": "false"}
+    ... ]
+    >>> dtype = {"id": "int", "amount": "decimal", "active": "bool"}
+    >>>
+    >>> result = converter.convert(records, dtype)
+    >>> # [{"id": 1, "amount": Decimal('12.5'), "active": True},
+    >>> #  {"id": 2, "amount": Decimal('23.7'), "active": False}]
+    """
+
+    TYPE_MAPPING = {
+        "int": "int",
+        "integer": "int",
+        "float": "float",
+        "decimal": "decimal",
+        "bool": "bool",
+        "boolean": "bool",
+        "str": "str",
+        "string": "str",
+        "date": "date",
+        "datetime": "datetime",
+        "timestamp": "datetime",
+    }
+
+    def __init__(self) -> None:
+        """
+        @methoddesc 初始化类型转换器
+
+        创建转换器实例，内置常见类型映射规则（int/integer、float/decimal、bool/boolean、str/string）。
+        """
+        pass
+
+    def convert(self, records: list[dict], dtype: dict[str, str]) -> list[dict]:
+        """
+        @methoddesc 批量转换数据记录的类型
+
+        ============================================================================
+        处理逻辑
+        ============================================================================
+        1. 遍历每条记录
+        2. 对每条记录，根据 dtype 配置转换指定列
+        3. 保留原始值，如果转换失败则保留原值
+
+        Args:
+            records: 数据记录列表
+            dtype: 类型配置字典，键为列名，值为目标类型
+
+        Returns:
+            转换后的数据记录列表
+
+        示例:
+            >>> records = [{"id": "1", "name": "Alice"}]
+            >>> dtype = {"id": "int"}
+            >>> result = converter.convert(records, dtype)
+            >>> # [{"id": 1, "name": "Alice"}]
+        """
+        if not records or not dtype:
+            return records
+
+        result = []
+        for record in records:
+            converted = self._convert_record(record, dtype)
+            result.append(converted)
+
+        return result
+
+    def _convert_record(self, record: dict, dtype: dict[str, str]) -> dict:
+        """
+        @methoddesc 转换单条记录
+
+        Args:
+            record: 单条数据记录
+            dtype: 类型配置
+
+        Returns:
+            转换后的记录
+        """
+        converted = record.copy()
+
+        for col, type_str in dtype.items():
+            if col in converted:
+                converted[col] = self._convert_value(converted[col], type_str)
+
+        return converted
+
+    def _convert_value(self, value: Any, type_str: str) -> Any:
+        """
+        @methoddesc 转换单个值
+
+        Args:
+            value: 要转换的值
+            type_str: 目标类型字符串
+
+        Returns:
+            转换后的值（如果转换失败，返回原始值）
+
+        Raises:
+            ValueError: 不支持的类型
+        """
+        if value is None:
+            return None
+
+        normalized_type = self.TYPE_MAPPING.get(type_str.lower())
+        if not normalized_type:
+            return value
+
+        try:
+            if normalized_type == "int":
+                return self._to_int(value)
+            elif normalized_type == "float":
+                return self._to_float(value)
+            elif normalized_type == "decimal":
+                return self._to_decimal(value)
+            elif normalized_type == "bool":
+                return self._to_bool(value)
+            elif normalized_type == "str":
+                return str(value)
+            elif normalized_type == "date":
+                return self._to_date(value)
+            elif normalized_type == "datetime":
+                return self._to_datetime(value)
+            return value
+        except (ValueError, TypeError, InvalidOperation):
+            # InvalidOperation 继承 ArithmeticError（非 ValueError），非法 decimal 值同样回退原值
+            return value
+
+    def _to_int(self, value: Any) -> int:
+        """
+        @methoddesc 转换为整数
+
+        Args:
+            value: 要转换的值
+
+        Returns:
+            整数
+        """
+        if isinstance(value, (int, float)):
+            return int(value)
+        return int(str(value).strip())
+
+    def _to_float(self, value: Any) -> float:
+        """
+        @methoddesc 转换为浮点数
+
+        Args:
+            value: 要转换的值
+
+        Returns:
+            浮点数
+        """
+        if isinstance(value, (int, float)):
+            return float(value)
+        return float(str(value).strip())
+
+    def _to_decimal(self, value: Any) -> Decimal:
+        """
+        @methoddesc 转换为高精度 Decimal
+
+        用于财务数据等需要精确十进制表示的场景，避免 float 的二进制精度丢失。
+        始终通过 str() 中转以避免 float -> Decimal 的二进制误差（如 Decimal(0.1) != 0.1）。
+
+        Args:
+            value: 要转换的值
+
+        Returns:
+            Decimal 对象
+        """
+        if isinstance(value, Decimal):
+            return value
+        if isinstance(value, bool):
+            # bool 是 int 子类，需先转 int 再转 Decimal，避免直接 str(True)="True" 报错
+            return Decimal(int(value))
+        if isinstance(value, (int, float)):
+            return Decimal(str(value))
+        return Decimal(str(value).strip())
+
+    def _to_date(self, value: Any) -> date:
+        """
+        @methoddesc 转换为日期（date，不含时间分量）
+
+        优先解析 ISO 8601 格式（YYYY-MM-DD），失败则尝试常见替代格式。
+
+        Args:
+            value: 要转换的值
+
+        Returns:
+            datetime.date 对象
+        """
+        if isinstance(value, datetime):
+            return value.date()
+        if isinstance(value, date):
+            return value
+        return date.fromisoformat(str(value).strip())
+
+    def _to_datetime(self, value: Any) -> datetime:
+        """
+        @methoddesc 转换为日期时间（datetime，含时间分量）
+
+        优先解析 ISO 8601 格式，失败则尝试常见替代格式。
+
+        Args:
+            value: 要转换的值
+
+        Returns:
+            datetime.datetime 对象
+        """
+        if isinstance(value, datetime):
+            return value
+        if isinstance(value, date):
+            return datetime(value.year, value.month, value.day)
+        return datetime.fromisoformat(str(value).strip())
+
+    def _to_bool(self, value: Any) -> bool:
+        """
+        @methoddesc 转换为布尔值
+
+        处理多种布尔值表示：
+        - 字符串: "true", "false", "1", "0", "yes", "no"
+        - 数字: 1, 0
+
+        Args:
+            value: 要转换的值
+
+        Returns:
+            布尔值
+        """
+        if isinstance(value, bool):
+            return value
+
+        if isinstance(value, (int, float)):
+            return bool(value)
+
+        if isinstance(value, str):
+            lower = value.lower().strip()
+            if lower in ("true", "1", "yes", "on"):
+                return True
+            if lower in ("false", "0", "no", "off"):
+                return False
+
+        return bool(value)
+
+    def convert_single(self, value: Any, type_str: str) -> Any:
+        """
+        @methoddesc 转换单个值
+
+        这是 convert 方法的单值版本，适用于单个值的类型转换。
+
+        Args:
+            value: 要转换的值
+            type_str: 目标类型
+
+        Returns:
+            转换后的值
+
+        示例:
+            >>> converter.convert_single("123", "int")
+            123
+            >>> converter.convert_single("true", "bool")
+            True
+        """
+        return self._convert_value(value, type_str)

app/shared/core/data_source/loaders/csv_loader.py

@@ -0,0 +1,252 @@
+# 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 CSV 数据源加载器模块
+
+功能概述:
+- 加载标准 CSV 文件为 pandas DataFrame
+- 自动检测文件编码（支持 fallback 编码列表）
+- 使用 utf-8-sig 去除 UTF-8 BOM，防止第一列名损坏（B12）
+- 空文件提前检查，给出清晰的 DataLoadError（B13）
+- 支持自定义分隔符、引号字符、转义字符、跳行、限制行数
+
+架构设计:
+- 继承 DataSourceLoader[CSVSourceSpec]，通过注册表自动发现
+- 编码解析由 _resolve_encoding() 完成（父类提供）
+- 读取参数根据 spec 动态构建，未配置项不传入 pandas
+
+输入示例:
+    spec = CSVSourceSpec(
+        path="data/users.csv",
+        header_row=0,
+        delimiter=",",
+        encoding="auto",
+        fallback_encodings=["gbk", "latin1"]
+    )
+    loader = CSVLoader(spec)
+
+输出示例:
+    df = loader.load()
+    # 返回 pandas.DataFrame，列名已根据 header_row 解析
+    # 若 header_enabled=False，列名自动生成为 col_0, col_1, ...
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+
+from ..specs.csv_source import CSVSourceSpec
+from .base import DataLoadError, DataSourceLoader
+from .registry import register_loader
+
+logger = logging.getLogger(__name__)
+
+
+def build_csv_read_kwargs(
+    *,
+    header_row: int | None,
+    encoding: str,
+    delimiter: str,
+    quotechar: str = '"',
+    on_bad_lines: str = "error",  # 与 CSVSourceSpec 默认同口径（fail-closed）
+    escapechar: str | None = None,
+    skip_rows: int = 0,
+) -> dict[str, Any]:
+    """@methoddesc 构建 pandas read_csv 参数（标准加载与分块加载共用，A2）
+
+    标准 CSVLoader 与分块校验路径（chunked_loader）必须使用同一套参数构造，
+    否则同一文件在两条路径下解析结果不一致。统一行为：
+    - 编码 utf-8 升级为 utf-8-sig 自动去除 BOM（B12），避免首列名变 \\ufeffxxx
+    - quotechar/on_bad_lines 始终透传（与 pandas 默认值显式对齐）
+    - escapechar/skiprows 仅在配置时传入
+
+    注意: CSVOptions 无 nrows 字段，两侧 CSV 均不支持 nrows，由调用方按需追加。
+
+    参数:
+        header_row: 表头行号（None 表示无表头，由调用方决定语义）
+        encoding: 文件编码（"utf-8" 会被升级为 "utf-8-sig"）
+        delimiter: 字段分隔符
+        quotechar: 引号字符
+        on_bad_lines: 坏行处理策略（error/warn/skip）
+        escapechar: 转义字符（可选）
+        skip_rows: 跳过的数据行数（>0 时生效）
+
+    返回:
+        pandas read_csv 关键字参数字典
+    """
+    # B12: utf-8 升级为 utf-8-sig 自动去除 UTF-8 BOM
+    if encoding == "utf-8":
+        encoding = "utf-8-sig"
+
+    read_kwargs: dict[str, Any] = {
+        "header": header_row,
+        "encoding": encoding,
+        "sep": delimiter,
+        "quotechar": quotechar,
+        "on_bad_lines": on_bad_lines,
+    }
+    if escapechar:
+        read_kwargs["escapechar"] = escapechar
+    if skip_rows > 0:
+        read_kwargs["skiprows"] = skip_rows
+    return read_kwargs
+
+
+@register_loader("csv")
+class CSVLoader(DataSourceLoader[CSVSourceSpec]):
+    """
+    @classdesc CSV 文件加载器
+
+    支持标准 CSV 文件，提供自动编码检测功能。
+    """
+
+    spec_class = CSVSourceSpec
+
+    def load(self) -> pd.DataFrame:
+        """
+        @methoddesc 加载 CSV 文件
+
+        Returns:
+            DataFrame
+
+        Raises:
+            DataLoadError: 加载失败时抛出
+        """
+        try:
+            # 空文件提前检查，给出清晰错误（B13）
+            path = Path(self.spec.path)
+            if path.exists() and path.stat().st_size == 0:
+                raise DataLoadError(f"CSV 文件为空: {self.spec.path}", self.spec)
+
+            # 确定编码
+            encoding = self._resolve_encoding()
+            # 使用 utf-8-sig 自动去除 UTF-8 BOM，避免第一列名损坏（B12，含在 build_csv_read_kwargs 内）
+            # 构建读取参数（与分块加载路径共用构造逻辑，A2）
+            read_kwargs = build_csv_read_kwargs(
+                header_row=self.spec.header_row if self.spec.header_enabled else None,
+                encoding=encoding,
+                delimiter=self.spec.delimiter,
+                quotechar=self.spec.quotechar,
+                on_bad_lines=self.spec.on_bad_lines,
+                escapechar=self.spec.escapechar,
+                skip_rows=self.spec.skip_rows,
+            )
+
+            # nrows 仅标准加载器支持（分块路径用 chunksize 流式读取，不叠加行数限制）
+            if self.spec.nrows:
+                read_kwargs["nrows"] = self.spec.nrows
+
+            # 读取数据
+            df = pd.read_csv(self.spec.path, **read_kwargs)
+
+            # 如果没有表头，生成默认列名
+            if not self.spec.header_enabled:
+                df.columns = [f"col_{i}" for i in range(len(df.columns))]
+
+            return df
+
+        except FileNotFoundError as e:
+            raise DataLoadError(f"文件不存在: {self.spec.path}", self.spec, e)
+        except UnicodeDecodeError as e:
+            raise DataLoadError(
+                f"编码错误: 无法使用 {self.spec.encoding} 编码读取文件，尝试的编码: {self.spec.fallback_encodings}",
+                self.spec,
+                e,
+            )
+        except Exception as e:
+            raise DataLoadError(f"CSV 加载失败: {e}", self.spec, e)
+
+    def _resolve_encoding(self) -> str:
+        """
+        @methoddesc 确定文件编码
+
+        如果启用自动检测，尝试多个编码；
+        否则直接使用配置的编码。
+
+        Returns:
+            确定的编码名称
+
+        Raises:
+            UnicodeDecodeError: 所有编码都失败时抛出
+        """
+        # 回归 #1 修复:用户配置 default_encoding="auto"(文档称自动检测)时,data_loader
+        # 路径会把 "auto" 原样透传到 spec.encoding。"auto" 不是 Python 可用编码名,
+        # 原样喂给 open() 会触发 LookupError(本方法仅 except UnicodeDecodeError,未捕获)→
+        # 报误导性的 "unknown encoding: auto" 且该路径所有 CSV 加载失败。
+        # 此处将 "auto" 归一化为回退编码列表的首项(utf-8),使其符合"自动检测"语义。
+        # fallback_encodings 默认 ["utf-8","gbk","latin1"],首项为 utf-8。
+        configured = self.spec.encoding
+        if configured == "auto":
+            configured = self.spec.fallback_encodings[0] if self.spec.fallback_encodings else "utf-8"
+
+        if not self.spec.encoding_detection:
+            return configured
+
+        # 尝试的编码列表
+        encodings = [configured] + [e for e in self.spec.fallback_encodings if e != configured]
+
+        last_error = None
+
+        for encoding in encodings:
+            try:
+                # 尝试读取前 64KB 来验证编码（B11）
+                # 之前只读 2 行，ASCII 表头 + 非 ASCII 数据会导致检测通过但后续读取失败
+                with open(self.spec.path, encoding=encoding) as f:
+                    f.read(65536)
+                return encoding
+            except UnicodeDecodeError as e:
+                last_error = e
+                continue
+
+        # 所有编码都失败
+        if last_error:
+            raise last_error
+
+        return self.spec.encoding
+
+    def validate(self) -> list[str]:
+        """
+        @methoddesc 验证 CSV 文件配置和文件本身。
+
+        检查项：
+        - 文件是否存在
+        - 文件扩展名是否为 .csv（如果不是则发出警告）
+
+        Returns:
+            错误信息列表，空列表表示验证通过
+
+        示例:
+            >>> errors = loader.validate()
+            >>> if errors:
+            ...     print("验证失败:", errors)
+        """
+        errors = []
+        path = Path(self.spec.path)
+
+        if not path.exists():
+            errors.append(f"文件不存在: {self.spec.path}")
+            return errors
+
+        # B19 修复：扩展名不符只是警告，不应作为错误返回（过去调用方按 errors 非空判定为失败）。
+        # 非 .csv 扩展名的文件仍可能合法（如 .tsv/.txt 导出的 CSV），仅记录日志。
+        if path.suffix.lower() != ".csv":
+            logger.warning(f"CSV 加载器收到的文件扩展名不是 .csv: {path.suffix}（路径: {path}），仍按 CSV 尝试解析")
+
+        return errors