Real Python: Custom Python Dictionaries: Inheriting From dict vs UserDict

Creating dictionary-like classes may be a requirement in your Python career. Specifically, you may be interested in making custom dictionaries with modified behavior, new functionalities, or both. In Python, you can do this by inheriting from an abstract base class, by subclassing the built-in dict class directly, or by inheriting from UserDict.

In this tutorial, you’ll learn how to:

• Create dictionary-like classes by inheriting from the built-in dict class
• Identify common pitfalls that can happen when inheriting from dict
• Build dictionary-like classes by subclassing UserDict from the collections module

Additionally, you’ll code a few examples that’ll help you understand the pros and cons of using dict vs UserDict to create your custom dictionary classes.

To get the most out of this tutorial, you should be familiar with Python’s built-in dict class and its standard functionality and features. You’ll also need to know the basics of object-oriented programming and understand how inheritance works in Python.

Creating Dictionary-Like Classes in Python

The built-in dict class provides a valuable and versatile collection data type, the Python dictionary. Dictionaries are everywhere, including in your code and the code of Python itself.

Sometimes, the standard functionality of Python dictionaries isn’t enough for certain use cases. In these situations, you’ll probably have to create a custom dictionary-like class. In other words, you need a class that behaves like a regular dictionary but with modified or new functionality.

You’ll typically find at least two reasons for creating custom dictionary-like classes:

1. Extending the regular dictionary by adding new functionality
2. Modifying the standard dictionary’s functionality

Note that you could also face situations in which you need to both extend and modify the dictionary’s standard functionality.

Depending on your specific needs and skill level, you can choose from a few strategies for creating custom dictionaries. You can:

• Inherit from an appropriate abstract base class, such as MutableMapping
• Inherit from the Python built-in dict class directly
• Subclass UserDict from collections

There are a few key considerations when you’re selecting the appropriate strategy to implement. Keep reading for more details.

Building a Dictionary-Like Class From an Abstract Base Class

This strategy for creating dictionary-like classes requires that you inherit from an abstract base class (ABC), like MutableMapping. This class provides concrete generic implementations of all the dictionary methods except for .__getitem__(), .__setitem__(), .__delitem__(), .__iter__(), and .__len__(), which you’ll have to implement by yourself.

Additionally, suppose you need to customize the functionality of any other standard dictionary method. In that case, you’ll have to override the method at hand and provide a suitable implementation that fulfills your needs.

This process implies a fair amount of work. It’s also error-prone and requires advanced knowledge of Python and its data model. It can also imply performance issues because you’ll be writing the class in pure Python.

The main advantage of this strategy is that the parent ABC will alert you if you miss any method in your custom implementation.

For these reasons, you should embrace this strategy only if you need a dictionary-like class that’s fundamentally different from the built-in dictionary.

In this tutorial, you’ll focus on creating dictionary-like classes by inheriting from the built-in dict class and the UserDict class, which seem to be the quickest and most practical strategies.

Inheriting From the Python Built-in dict Class

For a long time, it was impossible to subclass Python types implemented in C. Python 2.2 fixed this issue. Now you can directly subclass built-in types, including dict. This change brings several technical advantages to the subclasses because now they:

• Will work in every place that requires the original built-in type
• Can define new instance, static, and class methods
• Can store their instance attributes in a .__slots__ class attribute, which essentially replaces the .__dict__ attribute