What Does defaultdict Solve?

Grouping values usually needs a check. You ask whether the key is already there, and if it is not, you create an empty container first and then add to it. A defaultdict makes that check for you.

from collections import defaultdict

words = ['apple', 'avocado', 'banana', 'blueberry', 'cherry']

groups = defaultdict(list)
for word in words:
    groups[word[0]].append(word)

print(dict(groups))

The result is a mapping from the first letter to the words that begin with it. The letter a holds apple and avocado, the letter b holds banana and blueberry, and the letter c holds cherry.

Compare that with the plain dictionary version, which needs four extra lines. You write an if statement that tests whether the key is present, an assignment that creates an empty list when it is not, and the append itself. The defaultdict version is a single line, because the container is created the moment you need it.

The default factory is the argument that you pass in. Passing list creates an empty list for a missing key, int creates a zero, set creates an empty set, and str creates an empty string. The kind of factory decides what you get back, so it has to match what your code is about to do with the value.

Two related types in the same module are worth knowing. Counter is a defaultdict with an integer factory, so counting becomes counts[word] += 1 with no setup at all. OrderedDict exists for code that needs explicit reordering, although since Python 3.7 a plain dictionary already keeps the insertion order.

Reading a missing key from a defaultdict creates it with the factory and then stores it in the dictionary. That is the part that surprises people.

from collections import defaultdict

counts = defaultdict(int)
print(counts['missing'])   # 0 - and the key is now CREATED
print(counts)              # defaultdict(, {'missing': 0})

# The same thing happens with a list factory.
data = defaultdict(list)
print(data['never_set'])   # []
print('never_set' in data) # True - it is a key now

# A plain dictionary does not do this.
plain = {}
print(plain.get('never_set'))   # None, and nothing is stored
print('never_set' in plain)      # False

The counts dictionary now really does contain the key missing with the value 0. A plain dictionary does not behave that way, and that difference is what catches people out during review.

The surprise is that a read is not only a read. Code that probes a defaultdict with square brackets, in order to check whether a value exists, quietly adds an entry as a side effect. That can make a dictionary bigger, change the result of len(), and make a later loop include keys that nobody ever really set.

There are three ways to avoid it. Use the get method, which never creates anything, so you write counts.get('missing'). Use the in operator, which also never creates anything, so you write if 'missing' in counts. Or convert the object to a plain dictionary first with dict(counts) when you want to hand a normal dictionary onwards.

The right choice depends on what you mean. If a missing key means zero, then creating it is harmless and the counting code stays short. If it means that the key was never supposed to exist, then use get or in so that the dictionary stays honest about what it holds.

defaultdict solves the accumulator problem. You are building a dictionary of collections, and you have to create the collection the first time you meet a key. Without defaultdict you write a guard like if key not in d: d[key] = [] before every append, and that guard is easy to forget when several places in the code add to the same dictionary.

It works by holding a default factory. When you reach for a key that does not exist yet, the factory is called to make a fresh value, and that value is stored in the dictionary and returned to you. Pass list to get a new list, int to get a zero, set to get an empty set, and str to get an empty string. The factory is called with no arguments, so it must be something you can call without any.

dict.get has the opposite spirit. It never modifies the dictionary, it returns None or a default value that you supply, and it does not remember the key. So get is for reading a value that might not be there, and defaultdict is for collecting values where the first access should create the container for you.

The difference that matters most during a code review is that reading a defaultdict creates a key. If you use square brackets to check whether a key exists, you have written an accidental write. Use get or the in operator when the check is really only a check.

Two related options are worth mentioning. collections.Counter is the counting specialisation, and a plain dictionary with setdefault is the older way of doing the same job. That older form still works and you will still meet it in existing code.