From: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Date: Sun, 18 May 2025 15:59:20 +0000 (+0100)
Subject: gh-134114: Clarify FAQ note about dictonary keys (#134118)
X-Git-Tag: v3.15.0a1~1681
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=b1c33294ca5ef8d889f2ec87f9a8fa79741f9f7d;p=thirdparty%2FPython%2Fcpython.git

gh-134114: Clarify FAQ note about dictonary keys (#134118)
---

diff --git a/Doc/faq/design.rst b/Doc/faq/design.rst
index e2710fab9cf8..c758c019ca43 100644
--- a/Doc/faq/design.rst
+++ b/Doc/faq/design.rst
@@ -420,10 +420,12 @@ strings representing the files in the current directory.  Functions which
 operate on this output would generally not break if you added another file or
 two to the directory.
 
-Tuples are immutable, meaning that once a tuple has been created, you can't
-replace any of its elements with a new value.  Lists are mutable, meaning that
-you can always change a list's elements.  Only immutable elements can be used as
-dictionary keys, and hence only tuples and not lists can be used as keys.
+Tuples are :term:`immutable`, meaning that once a tuple has been created, you can't
+replace any of its elements with a new value.  Lists are :term:`mutable`, meaning that
+you can always change a list's elements.  Only :term:`hashable` objects can
+be used as dictionary keys. Most immutable types are hashable, which is why
+tuples, but not lists, can be used as keys. Note, however, that a tuple is
+only hashable if all of its elements are hashable.
 
 
 How are lists implemented in CPython?