如果列表是一行编号的框，则 Python 字典 是一组带标签的框。您通过名称而不是位置来询问您想要的内容，这就是为什么字典位于 JSON 数据、配置、缓存和 Python 本身的大部分内容后面。

本教程从基础知识开始，然后介绍经验丰富的开发人员每天使用的模式。我们在 Python 3.13 上运行了所有示例，显示的输出来自该运行。

什么是字典？

字典或dict将键映射到值。每个键仅出现一次，值可以是任何内容，包括列表或其他字典。

从Python 3.7开始，字典正式保留插入顺序。许多较旧的教程仍然称它们为无序的，但这已不再正确。有关其他类型的更广泛比较，请参阅 Python 列表、元组和集合。

查找速度很快，因为字典使用哈希表。无论字典包含十个项目还是一百万个项目，检查键所花费的时间大致相同，而搜索列表会随着列表的增长而变慢。

创建字典

user = {"name": "Asha", "age": 31, "city": "Pune"}

empty = {}
from_keywords = dict(name="Asha", age=31)
from_pairs = dict([("a", 1), ("b", 2)])

大括号是最常见的形式。一个陷阱：{} 创建一个空字典，而不是一个空集合。对于空集，您需要 set()。

安全地读取值

有两种读取值的方法，当键可能不存在时，差异很重要：

user["name"]                  # 'Asha'
user["email"]                 # KeyError: 'email'

user.get("email")             # None
user.get("email", "not set")  # 'not set'

当密钥必须存在时使用方括号，这样丢失的密钥就会失败。当缺席属于正常情况时使用 get()，例如 API 响应中的可选字段。要检查键，请使用 in 运算符，它查看键而不是值：

"city" in user    # True
"Pune" in user    # False

添加、更新和删除

分配给一个键会更新它（如果存在），或者添加它（如果不存在）：

user["age"] = 32
user["email"] = "asha@example.com"
print(user)

# {'name': 'Asha', 'age': 32, 'city': 'Pune', 'email': 'asha@example.com'}

Python 提供了多种删除项目的方法：

user.pop("city")          # returns 'Pune' and removes it
user.pop("phone", None)   # no error if it is missing
del user["email"]         # removes it, and raises KeyError if missing
user.clear()              # empties the dictionary

当您想要返回该值时，请使用 pop()。传递默认值作为第二个参数可以避免当密钥不存在时出现错误。 popitem() 删除并返回最近添加的对。

循环字典

循环直接给你钥匙。要获取键和值，请使用 items()：

user = {"name": "Asha", "age": 32}

for key, value in user.items():
    print(key, "=", value)

# name = Asha
# age = 32

keys()、values() 和 items() 返回实时视图而不是副本，因此它们反映了后来的更改。在循环字典时不要添加或删除键，因为 Python 会引发 RuntimeError。如果需要的话，请循环list(user)。

字典方法备忘单

合并字典

一个常见的需求是在默认值之上应用用户设置。当按键发生冲突时，右侧获胜：

defaults = {"theme": "light", "lang": "en"}
saved = {"theme": "dark"}

defaults | saved
{**defaults, **saved}

# Both give: {'theme': 'dark', 'lang': 'en'}

| 运算符需要 Python 3.9 或更高版本，而 ** 版本也适用于旧版本。两者都创建了一个新字典。相比之下，defaults.update(saved)和defaults |= saved改变了defaults。

理解和排序

字典推导式在单个可读行中构建新的字典，就像 列表推导式 对列表所做的那样：

prices = {"pen": 10, "book": 250, "bag": 900}

{k: v for k, v in prices.items() if v > 100}
# {'book': 250, 'bag': 900}

要按值排序，请将 key 函数传递给 sorted()。要查找具有最大值的键，请使用max()：

sorted(prices.items(), key=lambda item: item[1], reverse=True)
# [('bag', 900), ('book', 250), ('pen', 10)]

max(prices, key=prices.get)
# 'bag'

字典没有 sort() 方法，sorted() 返回一个对的列表。如果您想要按该顺序的字典，请将结果包含在 dict() 中。

计数和分组模式

有两个任务不断出现。第一个是计数，您可以使用 get() 来执行此操作，默认值为零：

words = "to be or not to be".split()

counts = {}
for word in words:
    counts[word] = counts.get(word, 0) + 1

print(counts)
# {'to': 2, 'be': 2, 'or': 1, 'not': 1}

标准库Counter使这个过程变得更短：

from collections import Counter

Counter(words).most_common(2)
# [('to', 2), ('be', 2)]

第二个是分组，defaultdict 在这里是理想的选择，因为它为您创建了缺失值：

from collections import defaultdict

orders = [("Asha", 1200), ("Ben", 300), ("Asha", 800)]

by_customer = defaultdict(list)
for name, total in orders:
    by_customer[name].append(total)

print(dict(by_customer))
# {'Asha': [1200, 800], 'Ben': [300]}

如果没有它，您需要在附加之前检查每个键是否存在。这些相同的模式非常适合聚合 API 数据或日志行。当字典为空或键丢失时，我们的 Python 异常处理指南 展示了如何处理结果 KeyError。

嵌套数据和复制陷阱

JSON 直接映射到嵌套字典和列表，因此您经常会链接键。当关卡可能丢失时，链接 get() 可以保证其安全：

response = {"user": {"profile": {"city": "Pune"}}}

response["user"]["profile"]["city"]               # 'Pune'
response.get("user", {}).get("settings", {}).get("theme")   # None

复制嵌套数据时要小心。 copy() 仅复制顶层，因此内部字典与原始字典保持共享：

settings = {"db": {"host": "localhost"}}

shallow = settings.copy()
shallow["db"]["host"] = "prod"

print(settings["db"]["host"])
# prod

更改副本会更改原始版本，这可能是一个令人讨厌的错误。使用 copy.deepcopy(settings) 获得完全独立的副本。

什么可以作为字典键？

键必须是可哈希，这通常意味着不可变。字符串、数字和不可变值的元组都可以。列表和字典不会：

{["a"]: 1}

# TypeError: unhashable type: 'list'

原因是密钥的哈希决定了其值的存储位置。如果某个键可能发生变化，Python 将无法再找到它。如果需要复合键，请使用元组，例如 {("Pune", 2026): 120}。

常见错误

• 在可选键上使用方括号。 当某个键可能不存在时，请使用 get()。
• 假设get()表示密钥存在。None可能表示丢失，或已存储None。当差异很重要时使用in。
• 使用可变的默认值。 dict.fromkeys(names, []) 为每个键提供完全相同的列表。请改用理解式。
• 在迭代期间更改大小。 循环键的副本。
• 对固定的已知字段使用字典。 A dataclass 可以更清晰，并且它可以捕获字段名称中的拼写错误。

最后的话

字典奖励一点练习。请记住 get() 表示可选键，items() 表示循环，Counter 和 defaultdict 表示两个最常见的作业。为了进行练习，请使用一个小的 JSON 文件并编写代码来对其记录进行计数和分组。如果您是该语言的新手，请从我们的 Python 初学者教程 开始。

常见问题

继续学习