precis-cli 0.1.3__py3-none-any.whl

app/shared/core/data_source/loaders/strategies/lines_parser.py

@@ -0,0 +1,355 @@
+# 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 LinesParser 策略类
+
+功能概述:
+- 实现 JSON Lines 格式的解析器策略
+- 支持逐行解析 JSON Lines 格式数据
+- 自动检测 JSON Lines 格式
+
+架构设计:
+- 实现 JSONParserStrategy Protocol 接口
+- 可被 ParserStrategyRegistry 注册管理
+- 独立的解析策略，便于扩展和维护
+
+输入示例:
+    '{"a": 1}\n{"a": 2}\n{"b": "test"}\n'
+
+输出示例:
+    [
+        {"a": 1},
+        {"a": 2},
+        {"b": "test"}
+    ]
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class JSONParserStrategy(Protocol):
+    """
+    @classdesc JSON 解析策略协议
+
+    定义 JSON 解析器必须实现的接口。
+
+    接口要求:
+        - parse: 解析 JSON 内容
+        - can_parse: 检测是否能解析给定内容
+    """
+
+    def parse(self, content: str) -> list[dict]:
+        """
+        @methoddesc 解析 JSON 内容
+
+        Args:
+            content: JSON 内容字符串
+
+        Returns:
+            解析后的字典列表
+
+        Raises:
+            JSONDecodeError: 解析失败时抛出
+        """
+        ...
+
+    def can_parse(self, content: str) -> bool:
+        """
+        @methoddesc 检测是否能解析给定内容
+
+        Args:
+            content: 待检测的内容字符串
+
+        Returns:
+            是否能解析
+        """
+        ...
+
+
+class LinesParser:
+    """
+    @classdesc JSON Lines 格式解析器
+
+    ============================================================================
+    功能说明
+    ============================================================================
+    专门用于解析 JSON Lines 格式（又称 newline-delimited JSON）的策略类。
+    JSON Lines 格式中，每一行都是一个独立的、有效的 JSON 对象，以换行符分隔。
+
+    格式示例:
+        {"name": "Alice", "age": 30}
+        {"name": "Bob", "age": 25}
+        {"name": "Charlie", "age": 35}
+
+    ============================================================================
+    业务场景
+    ============================================================================
+    - 日志文件处理：每行一条日志记录
+    - 数据导入导出：适合大文件流式处理
+    - 配置文件：多行配置的便捷格式
+    - 增量数据同步：每次变更作为一行
+
+    ============================================================================
+    使用示例
+    ============================================================================
+    >>> parser = LinesParser()
+    >>> content = '{"a": 1}\\n{"a": 2}\\n{"a": 3}'
+    >>> result = parser.parse(content)
+    >>> print(result)
+    [{'a': 1}, {'a': 2}, {'a': 3}]
+
+    >>> # 检测格式
+    >>> parser.can_parse('{"key": "value"}')  # True
+    >>> parser.can_parse('[1, 2, 3]')        # False
+    """
+
+    def parse(self, content: str) -> list[dict]:
+        """
+        @methoddesc 解析 JSON Lines 格式内容
+
+        ============================================================================
+        处理逻辑
+        ============================================================================
+        1. 按换行符分割内容
+        2. 跳过空行和纯空白行
+        3. 逐行解析为 JSON 对象
+        4. 返回字典列表
+
+        Args:
+            content: JSON Lines 格式内容
+
+        Returns:
+            解析后的字典列表
+
+        Raises:
+            json.JSONDecodeError: 当某一行无法解析为有效 JSON 时抛出
+                                 错误信息包含行号便于定位问题
+        """
+        if not content:
+            return []
+
+        records: list[dict] = []
+        lines = content.split("\n")
+
+        for line_num, line in enumerate(lines, start=1):
+            stripped_line = line.strip()
+            if not stripped_line:
+                continue
+
+            try:
+                parsed = json.loads(stripped_line)
+                # 保留非 dict 条目并包装为 {"value": ...}，避免静默丢弃数据（B19）
+                if isinstance(parsed, dict):
+                    records.append(parsed)
+                else:
+                    records.append({"value": parsed})
+            except json.JSONDecodeError as e:
+                raise json.JSONDecodeError(f"第 {line_num} 行 JSON 解析失败: {e.msg}", e.doc, e.pos) from e
+
+        return records
+
+    def can_parse(self, content: str) -> bool:
+        """
+        @methoddesc 检测内容是否为 JSON Lines 格式
+
+        ============================================================================
+        检测规则
+        ============================================================================
+        JSON Lines 格式的特征：
+        1. 包含多行内容（至少一行非空行）
+        2. 每行（非空行）都是独立的有效 JSON 对象
+        3. 对象类型必须是字典（而非数组或原始类型）
+
+        检测策略：
+        - 采样前 N 行进行检测（默认 5 行）
+        - 如果采样行中非空行都是有效的 JSON 对象字典，则认为是 JSON Lines
+        - 单行 JSON 数组或普通 JSON 对象会被判定为非 JSON Lines
+
+        Args:
+            content: 待检测的内容字符串
+
+        Returns:
+            是否为 JSON Lines 格式
+        """
+        if not content:
+            return False
+
+        lines = content.split("\n")
+        non_empty_lines = [line.strip() for line in lines if line.strip()]
+
+        if not non_empty_lines:
+            return False
+
+        if len(non_empty_lines) == 1:
+            return False
+
+        sample_lines = non_empty_lines[:5]
+
+        for line in sample_lines:
+            try:
+                parsed = json.loads(line)
+                if not isinstance(parsed, dict):
+                    return False
+            except (json.JSONDecodeError, ValueError):
+                return False
+
+        return True
+
+
+class StandardJSONParser:
+    """
+    @classdesc 标准 JSON 格式解析器
+
+    ============================================================================
+    功能说明
+    ============================================================================
+    解析标准 JSON 格式（数组形式）的策略类。
+    适用于 JSON 数组格式：[{"a": 1}, {"a": 2}]
+
+    ============================================================================
+    与 LinesParser 的区别
+    ============================================================================
+    - LinesParser: 每行一个 JSON 对象，适合流式处理
+    - StandardJSONParser: 完整的 JSON 数组，一次性解析
+    """
+
+    def parse(self, content: str) -> list[dict]:
+        """
+        @methoddesc 解析标准 JSON 数组格式
+
+        Args:
+            content: JSON 数组字符串
+
+        Returns:
+            解析后的字典列表
+
+        Raises:
+            json.JSONDecodeError: 解析失败时抛出
+        """
+        if not content:
+            return []
+
+        data = json.loads(content)
+
+        if isinstance(data, list):
+            return [item for item in data if isinstance(item, dict)]
+        elif isinstance(data, dict):
+            return [data]
+        else:
+            raise json.JSONDecodeError(f"不支持的 JSON 根类型: {type(data).__name__}", content, 0)
+
+    def can_parse(self, content: str) -> bool:
+        """
+        @methoddesc 检测是否为标准 JSON 格式
+
+        Args:
+            content: 待检测的内容
+
+        Returns:
+            是否为标准 JSON 格式
+        """
+        if not content:
+            return False
+
+        content = content.strip()
+
+        if not content:
+            return False
+
+        if content.startswith("[") and content.endswith("]"):
+            return True
+
+        try:
+            parsed = json.loads(content)
+            return isinstance(parsed, dict) and len(content.split("\n")) <= 1
+        except (json.JSONDecodeError, ValueError):
+            return False
+
+
+class ParserStrategyRegistry:
+    """
+    @classdesc 解析器策略注册表
+
+    ============================================================================
+    功能说明
+    ============================================================================
+    管理和注册各种 JSON 解析策略，支持自动选择最优解析器。
+    按优先级顺序尝试各策略，返回第一个能成功解析的策略结果。
+
+    ============================================================================
+    使用示例
+    ============================================================================
+    >>> registry = ParserStrategyRegistry()
+    >>> registry.register(LinesParser(), priority=10)
+    >>> registry.register(StandardJSONParser(), priority=5)
+
+    >>> content = '{"a": 1}\\n{"a": 2}'
+    >>> parser = registry.get_parser(content)
+    >>> result = parser.parse(content)
+    """
+
+    def __init__(self) -> None:
+        """
+        @methoddesc 初始化解析策略注册表
+
+        创建空的策略列表，后续通过 register() 方法注册解析策略。
+        """
+        self._strategies: list[tuple[int, JSONParserStrategy]] = []
+
+    def register(self, strategy: JSONParserStrategy, priority: int = 0) -> None:
+        """
+        @methoddesc 注册解析策略
+
+        Args:
+            strategy: 解析策略实例
+            priority: 优先级，数值越大优先级越高
+        """
+        self._strategies.append((priority, strategy))
+        self._strategies.sort(key=lambda x: x[0], reverse=True)
+
+    def get_parser(self, content: str) -> JSONParserStrategy | None:
+        """
+        @methoddesc 获取适合内容的解析器
+
+        Args:
+            content: 待解析的内容
+
+        Returns:
+            匹配的解析器，未找到返回 None
+        """
+        for _, strategy in self._strategies:
+            if strategy.can_parse(content):
+                return strategy
+        return None
+
+    def parse(self, content: str) -> list[dict] | None:
+        """
+        @methoddesc 自动解析内容
+
+        Args:
+            content: 待解析的内容
+
+        Returns:
+            解析结果，解析失败返回 None
+        """
+        parser = self.get_parser(content)
+        if parser:
+            return parser.parse(content)
+        return None

app/shared/core/data_source/loaders/strategies/object_parser.py

@@ -0,0 +1,278 @@
+# 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 ObjectParser 策略类
+
+功能概述:
+- 实现嵌套对象格式的 JSON 解析器策略
+- 支持递归查找最深层的数组作为数据源
+- 处理没有数组时的单条记录转换
+
+架构设计:
+- 实现 JSONParserStrategy Protocol 接口
+- 可被 ParserStrategyRegistry 注册管理
+- 独立的解析策略，便于扩展和维护
+
+输入示例:
+    '{"data": [{"a": 1}, {"a": 2}]}'
+    '{"users": {"items": [{"id": 1}, {"id": 2}]}}'
+    '{"name": "test"}'
+
+输出示例:
+    [{"a": 1}, {"a": 2}]
+    [{"id": 1}, {"id": 2}]
+    [{"name": "test"}]
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class JSONParserStrategy(Protocol):
+    """
+    @classdesc JSON 解析策略协议
+
+    定义 JSON 解析器必须实现的接口。
+
+    接口要求:
+        - parse: 解析 JSON 内容
+        - can_parse: 检测是否能解析给定内容
+    """
+
+    def parse(self, content: str) -> list[dict]:
+        """
+        @methoddesc 解析 JSON 内容
+
+        Args:
+            content: JSON 内容字符串
+
+        Returns:
+            解析后的字典列表
+
+        Raises:
+            JSONDecodeError: 解析失败时抛出
+        """
+        ...
+
+    def can_parse(self, content: str) -> bool:
+        """
+        @methoddesc 检测是否能解析给定内容
+
+        Args:
+            content: 待检测的内容字符串
+
+        Returns:
+            是否能解析
+        """
+        ...
+
+
+class ObjectParser:
+    """
+    @classdesc 嵌套对象格式解析器
+
+    ============================================================================
+    功能说明
+    ============================================================================
+    专门用于解析嵌套对象格式 JSON 的策略类。
+    能够自动查找嵌套结构中最深层的数组作为数据源。
+    如果没有找到数组，则将字典转换为单条记录。
+
+    格式示例:
+        - 单层嵌套: {"data": [{"a": 1}, {"a": 2}]}
+        - 多层嵌套: {"users": {"items": [{"id": 1}, {"id": 2}]}}
+        - 深度嵌套: {"result": {"data": {"records": [{"x": 1}]}}}
+        - 单对象: {"name": "test", "value": 123}
+
+    ============================================================================
+    业务场景
+    ============================================================================
+    - API 响应数据：大多数 REST API 返回嵌套的 JSON 对象
+    - 配置文件：包含嵌套结构的配置文件
+    - 导出数据：某些工具导出的嵌套格式数据
+
+    ============================================================================
+    使用示例
+    ============================================================================
+    >>> parser = ObjectParser()
+    >>> content = '{"data": [{"a": 1}, {"a": 2}]}'
+    >>> result = parser.parse(content)
+    >>> print(result)
+    [{'a': 1}, {'a': 2}]
+
+    >>> # 单对象转换为单条记录
+    >>> content = '{"name": "test"}'
+    >>> result = parser.parse(content)
+    >>> print(result)
+    [{'name': 'test'}]
+    """
+
+    def parse(self, content: str) -> list[dict]:
+        """
+        @methoddesc 解析嵌套对象格式的 JSON 内容
+
+        ============================================================================
+        处理逻辑
+        ============================================================================
+        1. 解析 JSON 字符串为 Python 对象
+        2. 递归查找最深层的数组
+        3. 如果找到数组，返回数组内容（每个元素转换为字典）
+        4. 如果没有找到数组，将根对象包装为单元素列表
+        5. 使用 pandas.json_normalize 扁平化嵌套字段
+
+        Args:
+            content: 嵌套对象格式的 JSON 内容
+
+        Returns:
+            解析后的字典列表
+
+        Raises:
+            json.JSONDecodeError: JSON 格式错误时抛出
+            ValueError: 内容不符合策略解析条件时抛出
+        """
+        if not content or not content.strip():
+            return []
+
+        try:
+            data = json.loads(content)
+        except json.JSONDecodeError as e:
+            raise json.JSONDecodeError(f"JSON 解析失败: {e.msg}", e.doc, e.pos) from e
+
+        if isinstance(data, list):
+            return [item if isinstance(item, dict) else {"value": item} for item in data]
+
+        if isinstance(data, dict):
+            arrays = self._find_deepest_arrays(data)
+            if arrays:
+                return [item if isinstance(item, dict) else {"value": item} for item in arrays]
+            return [data]
+
+        return [{"value": data}]
+
+    def can_parse(self, content: str) -> bool:
+        """
+        @methoddesc 检测内容是否为嵌套对象格式
+
+        ============================================================================
+        检测规则
+        ============================================================================
+        嵌套对象格式的特征：
+        1. 以花括号开头（表示 JSON 对象）
+        2. 包含嵌套结构（至少一层嵌套）
+        3. 可能包含数组作为某个属性的值
+        4. 不是以数组直接开头的格式
+
+        检测策略：
+        - 首先尝试 JSON 解析
+        - 解析成功且结果为字典（非数组）时返回 True
+        - 如果以数组开头或为空则返回 False
+
+        Args:
+            content: 待检测的内容字符串
+
+        Returns:
+            是否为嵌套对象格式
+        """
+        if not content:
+            return False
+
+        content = content.strip()
+
+        if content.startswith("["):
+            return False
+
+        if not content.startswith("{"):
+            return False
+
+        try:
+            data = json.loads(content)
+            return isinstance(data, dict)
+        except (json.JSONDecodeError, ValueError):
+            return False
+
+    def _find_deepest_arrays(self, obj: Any, current_depth: int = 0) -> list[Any]:
+        """
+        @methoddesc 递归查找最深层的数组
+
+        ============================================================================
+        算法说明
+        ============================================================================
+        使用深度优先搜索（DFS）遍历对象结构：
+        1. 如果当前对象是数组，记录当前位置并继续深入查找
+        2. 如果数组元素是字典，继续在数组元素中查找更深的数组
+        3. 返回最深层的数组作为数据源
+
+        特殊情况处理：
+        - 空数组：忽略，继续查找
+        - 非字典数组元素：保留，由上层调用方统一包装
+        - 混合类型数组：整体返回，由上层调用方统一包装
+
+        Args:
+            obj: 当前检查的对象
+            current_depth: 当前递归深度
+
+        Returns:
+            如果找到最深层的数组，返回数组内容；否则返回空列表
+        """
+        if isinstance(obj, list):
+            if not obj:
+                return []
+
+            result = []
+            for item in obj:
+                if isinstance(item, dict):
+                    nested = self._find_deepest_arrays(item, current_depth + 1)
+                    if nested:
+                        return nested
+                    result.append(item)
+
+            return result if result else obj[:1] if obj else []
+
+        if isinstance(obj, dict):
+            arrays_found: list[tuple[int, list[Any]]] = []
+
+            for key, value in obj.items():
+                if isinstance(value, list):
+                    if not value:
+                        continue
+
+                    # 优先查找列表元素中是否包含更深的数组
+                    deeper_arrays: list[list[Any]] = []
+                    for item in value:
+                        if isinstance(item, dict):
+                            nested = self._find_deepest_arrays(item, current_depth + 1)
+                            if nested:
+                                deeper_arrays.append(nested)
+
+                    if deeper_arrays:
+                        for nested in deeper_arrays:
+                            arrays_found.append((current_depth + 2, nested))
+                    else:
+                        # 当前列表本身即是最深层数组，整体返回
+                        arrays_found.append((current_depth + 1, list(value)))
+
+                elif isinstance(value, dict):
+                    nested = self._find_deepest_arrays(value, current_depth + 1)
+                    if nested:
+                        arrays_found.append((current_depth + 1, nested))
+
+            if arrays_found:
+                return max(arrays_found, key=lambda x: x[0])[1]
+
+        return []

app/shared/core/data_source/schema_info.py

@@ -0,0 +1,50 @@
+# 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 数据源 Schema 信息 DTO
+
+功能概述:
+- 为 core 层数据加载器提供与 domain 解耦的最小 Schema 信息
+- 仅包含加载数据文件所需的字段，避免 core.data_source.loader 直接依赖 domain.TableSchema
+
+架构设计:
+- 纯数据 DTO: 使用 dataclass，只读语义，无业务逻辑
+- 上层服务负责将 domain.TableSchema 或 core.TableSchemaFile 转换为 DataSourceInfo
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class DataSourceInfo:
+    """@classdesc 数据加载器使用的 Schema 信息 DTO
+
+    字段说明:
+        - schema_id: 表/Schema 的唯一标识，作为加载结果字典的键
+        - name: 表名（可选，用于日志展示）
+        - sheet_name: Excel 工作表名（可选）
+        - header_row: 表头行索引，默认 0
+        - source_config: 加载器相关配置（如 delimiter、encoding、format 等）
+    """
+
+    schema_id: str
+    name: str | None = None
+    sheet_name: str | None = None
+    header_row: int = 0
+    source_config: dict[str, Any] = field(default_factory=dict)