precis-cli 0.1.3__py3-none-any.whl

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

@@ -0,0 +1,268 @@
+# 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 JSONPathExtractor 数据提取器
+
+功能概述:
+- 实现 JSONPath 表达式的数据提取
+- 支持 $.key, $.key.subkey, $..key 递归查找等语法
+- 提取嵌套 JSON 数据中的特定路径
+
+架构设计:
+- 独立的提取器类，职责单一
+- 支持自定义错误处理
+- 可扩展的路径解析器
+
+输入示例:
+    data = {"users": [{"name": "Alice"}, {"name": "Bob"}]}
+    path = "$.users"
+
+输出示例:
+    [{"name": "Alice"}, {"name": "Bob"}]
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class JSONPathExtractor:
+    """
+    @classdesc JSONPath 数据提取器
+
+    ============================================================================
+    功能说明
+    ============================================================================
+    实现简单的 JSONPath 表达式解析和数据提取。
+    支持常用的 JSONPath 语法，适用于大多数数据提取场景。
+
+    ============================================================================
+    支持的语法
+    ============================================================================
+    - $.key - 访问对象属性
+    - $.key.subkey - 嵌套属性访问
+    - $..key - 递归查找（返回所有匹配的值）
+    - $.key[*] - 数组全部元素
+    - $.key[0] - 数组指定索引
+    - $ - 根节点
+
+    ============================================================================
+    业务场景
+    ============================================================================
+    - 从嵌套 JSON 中提取数据
+    - 处理 API 返回的复杂 JSON 结构
+    - 数据清洗和转换
+
+    ============================================================================
+    使用示例
+    ============================================================================
+    >>> extractor = JSONPathExtractor()
+    >>>
+    >>> # 基本提取
+    >>> data = {"users": [{"name": "Alice"}, {"name": "Bob"}]}
+    >>> result = extractor.extract(data, "$.users")
+    >>> # [{"name": "Alice"}, {"name": "Bob"}]
+    >>>
+    >>> # 递归查找
+    >>> data = {"a": {"b": {"c": 1}}, "d": 2}
+    >>> result = extractor.extract(data, "$..c")
+    >>> # [1]
+    """
+
+    def __init__(self) -> None:
+        """
+        @methoddesc 初始化 JSONPath 提取器
+
+        创建提取器实例，无需额外参数。
+        """
+        pass
+
+    def extract(self, data: Any, jsonpath: str) -> list[dict]:
+        """
+        @methoddesc 从 JSON 数据中提取指定路径的数据
+
+        ============================================================================
+        处理逻辑
+        ============================================================================
+        1. 规范化路径（移除 $ 前缀）
+        2. 根据路径类型选择提取策略
+           - 递归查找 (..key): 使用深度优先搜索
+           - 普通路径 (key.subkey): 逐层解析
+        3. 展平结果（如果是嵌套列表）
+
+        Args:
+            data: JSON 数据（字典或列表）
+            jsonpath: JSONPath 表达式
+
+        Returns:
+            提取后的数据列表
+
+        Raises:
+            ValueError: 路径不存在或格式错误
+        """
+        if not jsonpath or jsonpath == "$":
+            return data if isinstance(data, list) else [data]
+
+        normalized_path = self._normalize_path(jsonpath)
+
+        if normalized_path.startswith(".."):
+            return self._extract_recursive(data, normalized_path[2:])
+
+        return self._extract_by_path(data, normalized_path)
+
+    def _normalize_path(self, path: str) -> str:
+        """
+        @methoddesc 规范化 JSONPath
+
+        移除 $ 前缀，统一路径格式。
+
+        Args:
+            path: 原始路径
+
+        Returns:
+            规范化后的路径
+        """
+        if path.startswith("$."):
+            return path[2:]
+        elif path.startswith("$"):
+            return path[1:]
+        return path
+
+    def _extract_by_path(self, data: Any, path: str) -> list[dict]:
+        """
+        @methoddesc 根据路径提取数据
+
+        Args:
+            data: JSON 数据
+            path: 路径（不含 $ 前缀）
+
+        Returns:
+            提取后的数据列表
+        """
+        current = data
+        parts = self._parse_path(path)
+
+        for part in parts:
+            current = self._navigate_step(current, part)
+
+            if current is None:
+                return []
+
+        if isinstance(current, list):
+            return current
+        else:
+            return [current] if current is not None else []
+
+    def _parse_path(self, path: str) -> list[str | int]:
+        """
+        @methoddesc 解析路径为组成部分
+
+        Args:
+            path: 路径字符串
+
+        Returns:
+            路径部分列表（字符串或整数）
+        """
+        parts: list[str | int] = []
+        current = ""
+        i = 0
+
+        while i < len(path):
+            char = path[i]
+
+            if char == ".":
+                if current:
+                    parts.append(current)
+                    current = ""
+            elif char == "[":
+                if current:
+                    parts.append(current)
+                    current = ""
+                end = path.find("]", i)
+                if end != -1:
+                    key = path[i + 1 : end].strip("\"'")
+                    try:
+                        parts.append(int(key))
+                    except ValueError:
+                        parts.append(key)
+                    i = end
+            else:
+                current += char
+
+            i += 1
+
+        if current:
+            parts.append(current)
+
+        return parts
+
+    def _navigate_step(self, data: Any, step: str | int) -> Any:
+        """
+        @methoddesc 单步导航
+
+        根据当前数据类型（字典或列表）和路径步骤，
+        导航到下一层数据。
+
+        Args:
+            data: 当前数据
+            step: 路径部分（字符串键或整数索引）
+
+        Returns:
+            下一步的数据
+        """
+        if isinstance(data, dict):
+            return data.get(step)
+        elif isinstance(data, list):
+            if isinstance(step, int):
+                if 0 <= step < len(data):
+                    return data[step]
+                return None
+            elif step == "*":
+                return data
+            return None
+        return None
+
+    def _extract_recursive(self, data: Any, key: str) -> list[Any]:
+        """
+        @methoddesc 递归查找指定键的所有值
+
+        Args:
+            data: JSON 数据
+            key: 要查找的键名
+
+        Returns:
+            所有匹配的值列表
+        """
+        results: list[Any] = []
+
+        def search(obj: Any) -> None:
+            """
+            @methoddesc 递归搜索对象中的目标键值
+
+            参数:
+                obj: 当前搜索的对象（字典或列表）
+            """
+            if isinstance(obj, dict):
+                if key in obj:
+                    results.append(obj[key])
+                for value in obj.values():
+                    search(value)
+            elif isinstance(obj, list):
+                for item in obj:
+                    search(item)
+
+        search(data)
+        return results

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

@@ -0,0 +1,354 @@
+# 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 JSON 数据源加载器模块
+
+功能概述:
+- 加载 JSON / JSONL / NDJSON 文件为 pandas DataFrame
+- 使用策略模式自动识别 JSON 格式（array / lines / object / auto）
+- 支持 JSONPath 数据提取（B14: 空列表不再回退到原始未过滤数据）
+- 支持 record_path 通过 pd.json_normalize 展开嵌套数组（B15）
+- 加载后应用 dtype 转换（B17）
+- 自动解析器支持递归查找列表元素（B18）
+- JSON Lines 中非字典条目包装为 {"value": parsed}（B19）
+
+架构设计:
+- 继承 DataSourceLoader[JSONSourceSpec]，通过注册表自动发现
+- 解析逻辑委托给 strategies/ 下的策略类（AutoDetectParser、LinesParser 等）
+- 数据提取委托给 JSONPathExtractor
+- 类型转换委托给 TypeConverter
+
+输入示例:
+    spec = JSONSourceSpec(
+        path="data/users.json",
+        format="auto",
+        json_path="$.data.users",
+        record_path="orders",
+        dtype={"age": "int64"}
+    )
+    loader = JSONLoader(spec)
+
+输出示例:
+    df = loader.load()
+    # 返回 pandas.DataFrame，JSONPath 和 record_path 已应用
+    # 若 json_path 返回空列表则抛出 DataLoadError
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pandas as pd
+
+from ..specs.json_source import JSONSourceSpec
+from .base import DataLoadError, DataSourceLoader
+from .converter import TypeConverter
+from .extractor import JSONPathExtractor
+from .registry import register_loader
+from .strategies import JSONParserStrategy, get_parser
+
+
+@register_loader("json")
+class JSONLoader(DataSourceLoader[JSONSourceSpec]):
+    """
+    @classdesc JSON 文件加载器
+
+    ============================================================================
+    功能说明
+    ============================================================================
+    使用策略模式加载和解析 JSON 文件，支持多种格式。
+    核心职责是流程编排，实际解析逻辑委托给策略类和工具类。
+
+    ============================================================================
+    支持的 JSON 格式
+    ============================================================================
+    - 标准数组 (array): [{"a": 1}, {"a": 2}]
+    - JSON Lines (lines): 每行一个 JSON 对象
+    - 嵌套对象 (object): {"data": [{"a": 1}]}
+    - 自动检测 (auto): 自动识别最佳格式
+
+    ============================================================================
+    架构设计
+    ============================================================================
+    加载流程：
+    1. 读取文件内容
+    2. 使用 ParserStrategy 解析
+    3. 使用 JSONPathExtractor 提取数据
+    4. 使用 TypeConverter 转换类型
+    5. 转换为 DataFrame
+
+    ============================================================================
+    使用示例
+    ============================================================================
+    >>> from app.shared.core.data_source.loaders.json_loader import JSONLoader
+    >>> from app.shared.core.data_source.specs.json_source import JSONSourceSpec
+    >>>
+    >>> spec = JSONSourceSpec(path="data/users.json", format="auto")
+    >>> loader = JSONLoader(spec)
+    >>> df = loader.load()
+    """
+
+    spec_class = JSONSourceSpec
+
+    FORMAT_ARRAY = "array"
+    FORMAT_LINES = "lines"
+    FORMAT_OBJECT = "object"
+
+    def __init__(self, spec: JSONSourceSpec):
+        """
+        初始化 JSON 加载器
+
+        Args:
+            spec: JSON 数据源配置
+        """
+        super().__init__(spec)
+        self._parser: JSONParserStrategy | None = None
+        self._extractor = JSONPathExtractor()
+        self._converter = TypeConverter()
+
+    def load(self) -> pd.DataFrame:
+        """
+        @methoddesc 加载 JSON 文件并返回 DataFrame
+
+        ============================================================================
+        处理流程
+        ============================================================================
+        1. 读取文件内容
+        2. 使用策略模式解析 JSON
+        3. 应用 JSONPath 提取（如果配置了）
+        4. 转换数据类型（如果配置了）
+        5. 转换为 DataFrame 并扁平化
+
+        Returns:
+            加载的数据 DataFrame
+
+        Raises:
+            DataLoadError: 加载失败时抛出
+        """
+        try:
+            content = self._read_file()
+
+            if self.spec.json_path and self.spec.format in (self.FORMAT_OBJECT, self.FORMAT_ARRAY):
+                # 用户已通过 json_path 显式指定记录路径（object/array 格式均可），
+                # 无需走策略解析器（避免 D8 ArrayParser 对嵌套对象的启发式拒绝）。
+                # 直接解析原始 JSON，由 extractor 按 json_path 精确定位数据数组。
+                # 注：json_path 即显式消歧，无任何"取最长/取第一个数组"的猜测。
+                records = json.loads(content)
+                extracted = self._extractor.extract(records, self.spec.json_path)
+                # B14: 空列表是合法结果，不回退到未过滤数据。
+                # - extracted 为非空 list → 直接使用
+                # - extracted 为空 list   → 保持空（path 未命中，不回退原始数据）
+                # - extracted 为非 list（标量/字典）→ 包装为单元素列表
+                if isinstance(extracted, list):
+                    records = extracted
+                else:
+                    records = [extracted] if extracted is not None else []
+            else:
+                # 无 json_path（或 lines 格式）：走策略解析器。
+                # D8 对顶层数组/单条 dict 的处理 + 对嵌套对象的拒绝在此生效。
+                parser = self._get_parser()
+                records = parser.parse(content)
+
+            df = self._convert_to_dataframe(records)
+
+            if self.spec.flatten and self._has_nested_structure(df):
+                df = self._flatten_dataframe(df)
+
+            # dtype 转换在扁平化之后执行，确保列名匹配（B17）
+            dtype = getattr(self.spec, "dtype", None)
+            if dtype:
+                df = self._apply_dtype_to_dataframe(df, dtype)
+
+            return df
+
+        except FileNotFoundError as e:
+            raise DataLoadError(f"文件不存在: {self.spec.path}", self.spec, e)
+        except json.JSONDecodeError as e:
+            raise DataLoadError(f"JSON 解析错误 (行 {e.lineno}, 列 {e.colno}): {e.msg}", self.spec, e)
+        except DataLoadError:
+            raise
+        except Exception as e:
+            raise DataLoadError(f"JSON 加载失败: {e}", self.spec, e)
+
+    def _read_file(self) -> str:
+        """
+        @methoddesc 读取文件内容
+
+        Returns:
+            文件内容字符串
+        """
+        with open(self.spec.path, encoding=self.spec.encoding) as f:
+            return f.read()
+
+    def _get_parser(self) -> JSONParserStrategy:
+        """
+        @methoddesc 获取合适的 JSON 解析器
+
+        根据配置选择或自动检测合适的解析策略。
+
+        Returns:
+            JSON 解析策略实例
+        """
+        if self._parser:
+            return self._parser
+
+        # D8: format 必须由 spec 显式提供(auto 已废弃)。spec 层已强制 format 必填,
+        # 此处直接取 spec.format;若为 None(异常情况)由 get_parser 报错引导。
+        format_type = self.spec.format
+        if not format_type:
+            raise ValueError(
+                "JSON 数据源未指定 format。请显式指定:array(顶层数组)、"
+                "lines(JSON Lines)、或 object(嵌套对象,需配合 json_path)。"
+            )
+        self._parser = get_parser(format_type)
+        return self._parser
+
+    def _convert_to_dataframe(self, data: list[dict]) -> pd.DataFrame:
+        """
+        @methoddesc 将数据列表转换为 DataFrame
+
+        Args:
+            data: 数据字典列表
+
+        Returns:
+            DataFrame
+        """
+        if not data:
+            return pd.DataFrame()
+
+        standardized = []
+        for record in data:
+            if isinstance(record, dict):
+                standardized.append(record)
+            else:
+                standardized.append({"value": record})
+
+        # 支持 record_path 展开嵌套数组（B15）
+        # 设计说明：record_path 统一由 pd.json_normalize 处理，不再需要预标准化步骤。
+        # pd.json_normalize 的 record_path 参数会自动将嵌套数组展开为独立行，
+        # 与之前的手动 _apply_record_path 逻辑等价，且更可靠。
+        record_path = getattr(self.spec, "record_path", None)
+        if record_path:
+            meta_prefix = getattr(self.spec, "meta_prefix", "meta.")
+            sep = getattr(self.spec, "sep", ".")
+            df = pd.json_normalize(
+                standardized,
+                record_path=record_path,
+                meta_prefix=meta_prefix,
+                sep=sep,
+            )
+        else:
+            df = pd.json_normalize(standardized)
+        return df
+
+    def _has_nested_structure(self, df: pd.DataFrame) -> bool:
+        """
+        @methoddesc 检查 DataFrame 是否包含嵌套结构
+
+        Args:
+            df: DataFrame
+
+        Returns:
+            是否存在嵌套结构
+        """
+        for col in df.columns:
+            if df[col].dtype == "object":
+                sample = df[col].dropna().head(100)
+                for val in sample:
+                    if isinstance(val, (dict, list)):
+                        return True
+        return False
+
+    def _flatten_dataframe(self, df: pd.DataFrame) -> pd.DataFrame:
+        """
+        @methoddesc 扁平化 DataFrame 中的嵌套结构
+
+        Args:
+            df: 原始 DataFrame
+
+        Returns:
+            扁平化后的 DataFrame
+        """
+        if df.empty:
+            return df
+
+        records = df.to_dict("records")
+
+        flat_df = pd.json_normalize(records, sep=self.spec.sep, max_level=self.spec.max_depth)
+
+        return flat_df
+
+    def validate(self) -> list[str]:
+        """
+        @methoddesc 验证 JSON 文件配置和文件本身。
+
+        检查项：
+        - 文件是否存在
+        - 文件扩展名是否为 .json、.jsonl 或 .ndjson
+        - 前 5 行是否为有效的 JSON 格式（仅 JSON Lines 文件）
+
+        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
+
+        if path.suffix.lower() not in [".json", ".jsonl", ".ndjson"]:
+            errors.append(f"警告: 文件扩展名不是 .json/.jsonl/.ndjson: {path.suffix}")
+
+        try:
+            with open(path, encoding=self.spec.encoding) as f:
+                for _ in range(5):
+                    line = f.readline()
+                    if not line:
+                        break
+                    if path.suffix.lower() in [".jsonl", ".ndjson"]:
+                        json.loads(line.strip())
+        except json.JSONDecodeError as e:
+            errors.append(f"JSON 格式错误: {e.msg}")
+        except Exception as e:
+            errors.append(f"无法读取文件: {e}")
+
+        return errors
+
+    def _apply_dtype_to_dataframe(self, df: pd.DataFrame, dtype: dict[str, str]) -> pd.DataFrame:
+        """@methoddesc 对 DataFrame 的指定列进行类型转换（B17）。"""
+        if df.empty or not dtype:
+            return df
+        for col, type_str in dtype.items():
+            if col in df.columns:
+                df[col] = df[col].apply(lambda x: self._converter.convert_single(x, type_str))
+        return df
+
+    def get_schema(self) -> dict[str, str]:
+        """
+        @methoddesc 获取数据源的 schema
+
+        Returns:
+            列名到类型的映射
+        """
+        df = self.preview(nrows=100)
+        return {col: str(dtype) for col, dtype in df.dtypes.items()}

app/shared/core/data_source/loaders/registry.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 数据源加载器注册表模块
+
+功能概述:
+- 提供加载器的集中管理和发现机制
+- 实现装饰器 register_loader 用于自动注册加载器类
+- 支持按数据源类型获取加载器类或实例
+- 提供加载器存在性检测功能
+
+架构设计:
+- 全局字典 LOADER_REGISTRY 存储类型到加载器类的映射
+- 装饰器模式实现声明式注册
+- 支持按 discriminator_value 精确匹配
+- 与规格类的注册机制对称设计
+
+输入示例:
+    >>> @register_loader("json")
+    ... class JSONLoader(DataSourceLoader[JSONSourceSpec]):
+    ...     spec_class = JSONSourceSpec
+    ...     def load(self) -> pd.DataFrame:
+    ...         pass
+
+输出示例:
+    >>> loader_class = get_loader_class_for_type("json")
+    >>> loader_instance = get_loader_for_spec(spec)
+    >>> supports_source_type("csv")
+    True
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .base import DataSourceLoader
+
+
+LOADER_REGISTRY: dict[str, type[DataSourceLoader]] = {}
+
+
+def register_loader(spec_discriminator: str) -> Callable[[type[DataSourceLoader]], type[DataSourceLoader]]:
+    """
+    @methoddesc 装饰器：注册加载器到全局注册表
+
+    Args:
+        spec_discriminator: 数据源类型标识符，应与 Spec 类的 discriminator_value 一致
+
+    示例:
+        >>> @register_loader("json")
+        ... class JSONLoader(DataSourceLoader[JSONSpec]):
+        ...     pass
+    """
+
+    def decorator(loader_class: type[DataSourceLoader]) -> type[DataSourceLoader]:
+        """
+        @methoddesc 注册加载器类到全局注册表
+
+        参数:
+            loader_class: 要注册的加载器类，必须继承 DataSourceLoader
+
+        返回:
+            注册后的加载器类（便于装饰器链式使用）
+
+        异常:
+            ValueError: 如果该类型已注册则抛出
+        """
+        if spec_discriminator in LOADER_REGISTRY:
+            raise ValueError(f"加载器 '{spec_discriminator}' 已注册")
+        LOADER_REGISTRY[spec_discriminator] = loader_class
+        return loader_class
+
+    return decorator