from __future__ import annotations

from typing import Any, List, Sequence, Union


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


def 是否存在路径(
    数据: Any,
    键路径: _路径类型,
    分隔符: str = ".",
    键转字符串: bool = True,
) -> bool:
    """判断嵌套字典或列表中的某条路径是否存在。

    功能说明:
        - 这个函数用于判断嵌套字典或列表中的某条路径是否存在。
        - 当你不确定多层结构里有没有某个字段时，可以直接先用它判断，再决定后面要不要继续取值。
        - 它适合处理接口返回值、配置项、表单数据这类可能缺字段的结构。

    Args:
        数据: 任意输入对象，通常为 dict、list、tuple 的嵌套结构。
        键路径: 路径字符串或路径序列。
            - 字符串示例： "a.b.0.c"
            - 列表示例： ["a", "b", 0, "c"]
        分隔符: 字符串路径的分隔符，默认 "."。
        键转字符串: 当走 dict 路径时，是否将键统一转为 str。默认 True。

    Returns:
        路径存在时返回 ``True``；不存在时返回 ``False``。
    """
    try:
        if isinstance(键路径, str):
            if 键路径 == "":
                return False
            路径列表: List[Any] = 键路径.split(分隔符)
        elif isinstance(键路径, (list, tuple)):
            if len(键路径) == 0:
                return False
            路径列表 = list(键路径)
        else:
            return False

        当前 = 数据

        for 段 in 路径列表:
            if isinstance(当前, dict):
                键名 = str(段) if 键转字符串 else 段
                if 键名 not in 当前:
                    return False
                当前 = 当前[键名]
                continue

            if isinstance(当前, (list, tuple)):
                try:
                    目标索引 = 段 if isinstance(段, int) else int(str(段))
                except Exception:
                    return False

                if 目标索引 < 0 or 目标索引 >= len(当前):
                    return False

                当前 = 当前[目标索引]
                continue

            return False

        return True
    except Exception:
        return False


if __name__ == "__main__":
    print("===== 示例1：基础用法 =====")
    数据 = {"用户": {"信息": [{"城市": "上海", "年龄": 18}]}}
    print("结果:", 是否存在路径(数据, "用户.信息.0.城市"))

    print("\n===== 示例2：使用列表路径 =====")
    数据 = {"用户": {"信息": [{"城市": "北京"}]}}
    print("结果:", 是否存在路径(数据, ["用户", "信息", 0, "城市"]))

    print("\n===== 示例3：边界情况-空路径 =====")
    数据 = {"用户": {"信息": [{"城市": "上海"}]}}
    print("结果:", 是否存在路径(数据, ""))

    print("\n===== 示例4：异常情况-数据结构不对 =====")
    数据 = "不是字典"
    print("结果:", 是否存在路径(数据, "用户.信息.0.城市"))

    print("\n===== 示例5：特殊值情况-值为 None 也算存在 =====")
    数据 = {"用户": {"信息": [{"城市": None}]}}
    print("结果:", 是否存在路径(数据, "用户.信息.0.城市"))

    print("\n===== 示例6：应用场景-检查订单联系人字段是否齐全 =====")
    数据 = {"订单": {"收货信息": [{"联系人": "张三", "电话": "123456"}]}}
    print("结果:", 是否存在路径(数据, "订单.收货信息.0.联系人"))
