from __future__ import annotations

from typing import Any, Dict, Iterable, List, Sequence, Union, Optional


_路径类型 = Union[str, Sequence[Any]]

def 取值_路径(
    数据: Any,
    键路径: _路径类型,
    默认值: Any = None,
    分隔符: str = ".",
    键转字符串: bool = True,
) -> Any:
    """根据“键路径”从嵌套结构中安全取值（dict/list 混合），失败返回默认值。

    功能说明:
        - 这个函数用于根据“键路径”从嵌套结构中安全取值（dict/list 混合），失败返回默认值。
        - 它适合处理多层嵌套字典或字典与列表混合的数据，省得自己一层一层判断。
        - 当输入不符合要求时，函数会返回约定好的兜底结果，避免程序因为异常中断。

    Args:
        数据 (Any): 任意输入对象，通常为 dict/list 的嵌套结构。
        键路径 (str | Sequence[Any]): 路径字符串或路径序列。
        默认值 (Any): 失败时返回值，默认 None。
        分隔符 (str): 当键路径为字符串时的分隔符，默认 "."。
        键转字符串 (bool): 当走 dict 取值时，是否将键统一转换为 str。默认 True。

    Returns:
        Any:
        - 成功：返回路径命中的值
        - 失败：返回默认值"""
    try:
        # 1) 归一化路径
        if isinstance(键路径, str):
            if 键路径 == "":
                return 默认值
            路径列表: List[Any] = 键路径.split(分隔符)
        elif isinstance(键路径, (list, tuple)):
            if len(键路径) == 0:
                return 默认值
            路径列表 = list(键路径)
        else:
            return 默认值

        当前 = 数据

        # 2) 逐段向下取值
        for 段 in 路径列表:
            if isinstance(当前, dict):
                键 = str(段) if 键转字符串 else 段
                if 键 in 当前:
                    当前 = 当前[键]
                else:
                    return 默认值

            elif isinstance(当前, (list, tuple)):
                # 允许 "0" / 0 两种写法
                try:
                    索引 = 段 if isinstance(段, int) else int(str(段))
                except Exception:
                    return 默认值

                if 0 <= 索引 < len(当前):
                    当前 = 当前[索引]
                else:
                    return 默认值
            else:
                return 默认值

        return 当前

    except Exception:
        return 默认值


if __name__ == "__main__":
    print("===== 示例1：基础用法 =====")
    数据 = {"用户": {"信息": [{"城市": "上海", "年龄": 18}]}}
    键路径 = "用户.信息.0.城市"
    默认值 = "默认值"
    分隔符 = "."
    键转字符串 = True
    print("结果:", 取值_路径(数据, 键路径, 默认值, 分隔符, 键转字符串))
    print("数据:", 数据)

    print("\n===== 示例2：常见变体 =====")
    数据 = {"用户": {"信息": [{"城市": "北京"}]}}
    键路径 = ["用户", "信息", 0, "城市"]
    默认值 = "未找到"
    分隔符 = "."
    键转字符串 = True
    print("结果:", 取值_路径(数据, 键路径, 默认值, 分隔符, 键转字符串))
    print("数据:", 数据)

    print("\n===== 示例3：边界情况 =====")
    数据 = {}
    键路径 = ""
    默认值 = "空"
    分隔符 = "."
    键转字符串 = True
    print("结果:", 取值_路径(数据, 键路径, 默认值, 分隔符, 键转字符串))
    print("数据:", 数据)

    print("\n===== 示例4：异常情况 =====")
    数据 = []
    键路径 = "用户.信息.5.城市"
    默认值 = "失败"
    分隔符 = "."
    键转字符串 = True
    print("结果:", 取值_路径(数据, 键路径, 默认值, 分隔符, 键转字符串))
    print("数据:", 数据)

    print("\n===== 示例5：特殊值情况 =====")
    数据 = {"用户": {"信息": [{"城市": None, "标签": ""}]}}
    键路径 = "用户.信息.0.标签"
    默认值 = 0
    分隔符 = "."
    键转字符串 = False
    print("结果:", 取值_路径(数据, 键路径, 默认值, 分隔符, 键转字符串))
    print("数据:", 数据)

    print("\n===== 示例6：应用场景-整理业务字典 =====")
    数据 = {"订单": {"收货信息": [{"城市": "杭州", "联系人": "张三"}]}}
    键路径 = "订单.收货信息.0.联系人"
    默认值 = "未知状态"
    分隔符 = "."
    键转字符串 = True
    print("结果:", 取值_路径(数据, 键路径, 默认值, 分隔符, 键转字符串))
    print("数据:", 数据)
