函数功能概述

• 将嵌套的映射（Mapping，如 dict）和列表按路径“扁平化”为单层字典。
• 路径通过分隔符拼接各级键/索引（默认“.”），可选起始前缀 parent_key。
• 支持按键排序以获得稳定输出次序。
• 可通过 max_depth 限制展开深度；超过深度的子对象将作为整体保留为值。

参数详细说明（Google 风格） Args: data (Mapping[str, Any]): 待扁平化的数据。顶层必须是映射类型（如 dict）。嵌套处可包含映射或列表，其他类型被视为叶子值。 parent_key (str, optional): 起始路径前缀，最终键会在其后继续拼接。默认 "" 不添加前缀。 sep (str, optional): 路径分隔符，用于连接各级键/索引。默认 "."。不能为空字符串。 max_depth (Optional[int], optional): 最大展开深度（从 0 起算）。当递归深度 depth > max_depth 时，不再继续下钻，当前对象作为值保留。默认 None 表示无限展开。 sort_keys (bool, optional): 是否对映射的键进行排序后再遍历，保证确定性输出顺序。默认 True。

返回值说明 Returns: dict[str, Any]: 扁平化后的字典。键为用分隔符连接的路径（映射键与列表下标），值为对应的叶子值或在达到深度上限时的未展开子对象。

使用示例

• 基本用法（嵌套字典与列表）: from pprint import pprint

  data = {"a": {"b": 1, "c": [10, 20]}, "d": 2} result = flatten_dict(data) pprint(result)

  {'a.b': 1, 'a.c.0': 10, 'a.c.1': 20, 'd': 2}

• 限制展开深度（max_depth=1，仅展开一层路径， deeper 保留为整体）: result = flatten_dict({"a": {"b": 1, "c": [10, 20]}, "d": 2}, max_depth=1) pprint(result)

  {'a.b': 1, 'a.c': [10, 20], 'd': 2}

• 使用起始前缀与自定义分隔符: result = flatten_dict({"a": {"b": 1}, "d": 2}, parent_key="root", sep="/") pprint(result)

  {'root/a/b': 1, 'root/d': 2}

注意事项

• 列表会被展开为以下标命名的路径段（如 "items.0", "items.1"）。
• 分隔符 sep 不会对原键名进行转义；若原始键中包含分隔符，可能导致路径歧义与键碰撞。
• 键碰撞时，后遍历到的条目会覆盖先前的值；开启 sort_keys=True 可使覆盖顺序稳定但不能避免碰撞。
• max_depth 的判断基于 “当前递归深度 depth > max_depth 即停止”；例如 max_depth=1 时，"a.b" 会被展开为键，但 "a.c" 下的列表将整体保留为值。
• 该函数使用递归实现；在极深的嵌套结构上可能触发 RecursionError。
• 当 sort_keys=True 且映射的键类型不可比较（如混合不同类型的键）时，排序可能失败。

相关异常说明 Raises: TypeError: 当 data 不是 Mapping 时抛出；或在 sort_keys=True 时，若键不可比较导致排序失败时由底层 sorted 抛出。 ValueError: 当 sep 为空字符串时抛出。