Hashability Requirements for Dictionary Keys in Python: Why Lists Are Invalid While Tuples Are Valid

Fundamentals of Hashability and Dictionary Keys

In Python, dictionaries are data structures implemented based on hash tables, requiring keys to be hashable. Hashability means that objects must implement the __hash__() and __eq__() methods to ensure unique and consistent value location in the dictionary. The hash function maps keys to integer indices, while the __eq__() method handles hash collisions. For example, immutable types like None and integers naturally meet these criteria, so they can be directly used as dictionary keys.

d = {}
d[None] = 'foo'  # Valid
print(d[None])   # Output: foo

Why Lists Are Not Hashable

Lists are mutable objects whose contents can be modified at any time, leading to unstable hash values. Allowing lists as dictionary keys would cause consistency issues. Consider the following scenario:

d = {}
li = [1, 2, 3]
d[li] = 'value'  # Assuming it were allowed
li.append(4)     # Modifying the list
# What should d[li] return now? The original list has changed, but the key's hash may have altered

Python prohibits lists as keys to avoid such ambiguity. The error message TypeError: unhashable type: 'list' directly reflects this restriction. In contrast, tuples are immutable, with hash values computed based on content and remaining constant, making them suitable as keys.

d[(1, 3)] = 'baz'  # Valid
d[(1, [3])] = 'qux'  # Invalid, as the tuple contains a mutable list

Hashability of Modules and Custom Objects

Modules and custom objects typically rely on object identity (memory address) for hashing and comparison, making them suitable as dictionary keys. For instance, the sys module is unique in a program, with stable identity.

import sys
d[sys] = 'bar'  # Valid
print(d[sys])   # Output: bar

This design reduces unexpected behavior, as object identity is more predictable than mutable content. However, if objects override the __hash__() and __eq__() methods, consistency must be ensured to avoid dictionary operation errors.

Alternative Solutions and Best Practices

Although lists cannot be used directly as keys, similar functionality can be achieved through conversion. One method is to convert a list to a tuple, as tuples are immutable and hashable.

d[tuple([1, 2, 3])] = 'value'  # Valid
print(d[(1, 2, 3)])  # Output: value

Another approach is to use string representation, but note that strings may not be unique or efficient.

d[repr([1, 2, 3])] = 'value'  # Valid, but the key is a string
print(d['[1, 2, 3]'])  # Output: value

In practice, tuple conversion is recommended as it preserves type semantics and is efficient. Understanding hashability helps design more robust code, preventing errors due to key mutability.