from __future__ import annotations

from typing import Any, List, Sequence, Union


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


def 设置值_路径(
    数据: Any,
    键路径: _路径类型,
    值: Any,
    分隔符: str = ".",
    键转字符串: bool = True,
) -> bool:
    """根据路径把值写入嵌套字典或列表中。

    功能说明:
        - 这个函数用于根据路径把值写入嵌套字典或列表中。
        - 当中间层还不存在时，它会自动帮你补出需要的字典或列表结构。
        - 它适合处理接口组装、配置写入、动态生成多层业务数据这类场景。

    Args:
        数据: 通常为 dict 或 list 的嵌套结构。
        键路径: 路径字符串或路径序列。
            - 字符串示例： "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

        if not isinstance(数据, (dict, list)):
            return False

        当前 = 数据

        for 索引位置, 段 in enumerate(路径列表):
            是否最后一段 = 索引位置 == len(路径列表) - 1
            下一段 = None if 是否最后一段 else 路径列表[索引位置 + 1]

            if isinstance(当前, dict):
                键名 = str(段) if 键转字符串 else 段

                if 是否最后一段:
                    当前[键名] = 值
                    return True

                if 键名 not in 当前:
                    try:
                        需要列表 = not isinstance(下一段, bool) and (
                            isinstance(下一段, int) or str(下一段).isdigit()
                        )
                    except Exception:
                        需要列表 = False
                    当前[键名] = [] if 需要列表 else {}

                if not isinstance(当前[键名], (dict, list)):
                    return False

                当前 = 当前[键名]
                continue

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

                if 目标索引 < 0:
                    return False

                while len(当前) <= 目标索引:
                    当前.append(None)

                if 是否最后一段:
                    当前[目标索引] = 值
                    return True

                if 当前[目标索引] is None:
                    try:
                        需要列表 = not isinstance(下一段, bool) and (
                            isinstance(下一段, int) or str(下一段).isdigit()
                        )
                    except Exception:
                        需要列表 = False
                    当前[目标索引] = [] if 需要列表 else {}

                if not isinstance(当前[目标索引], (dict, list)):
                    return False

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

            return False

        return False
    except Exception:
        return False


if __name__ == "__main__":
    print("===== 示例1：基础用法 =====")
    数据 = {}
    print("结果:", 设置值_路径(数据, "用户.信息.0.城市", "上海"))
    print("数据:", 数据)

    print("\n===== 示例2：使用列表路径 =====")
    数据 = {}
    print("结果:", 设置值_路径(数据, ["用户", "信息", 0, "年龄"], 18))
    print("数据:", 数据)

    print("\n===== 示例3：边界情况-空路径 =====")
    数据 = {}
    print("结果:", 设置值_路径(数据, "", "上海"))
    print("数据:", 数据)

    print("\n===== 示例4：异常情况-数据不是字典或列表 =====")
    数据 = "不是字典"
    print("结果:", 设置值_路径(数据, "用户.信息.0.城市", "上海"))
    print("数据:", 数据)

    print("\n===== 示例5：特殊值情况-覆盖已有值 =====")
    数据 = {"用户": {"信息": [{"城市": "北京"}]}}
    print("结果:", 设置值_路径(数据, "用户.信息.0.城市", None))
    print("数据:", 数据)

    print("\n===== 示例6：应用场景-写入订单收货人信息 =====")
    数据 = {}
    print("结果:", 设置值_路径(数据, "订单.收货信息.0.联系人", "张三"))
    print("数据:", 数据)
