Chapter 7: Emulating Container Types with collections.abc

Python's built-in container types—list, tuple, dict, set—are incredibly powerful, but sometimes you need a container with specialized behavior. You might want a list that only accepts certain types, a dictionary with a fixed set of keys, or a sequence that maintains a unique set of ordered items.

In Chapter 1, we made our FrenchDeck behave like a sequence by implementing __len__ and __getitem__. While this works, it's an informal approach. For creating robust, full-featured container types, the modern and correct approach is to inherit from the Abstract Base Classes (ABCs) found in the collections.abc module.

Using these ABCs provides two major advantages:

1. Clear Interface Definition: The ABCs force you to implement all the necessary methods for a given container type. If you forget one, Python will raise a TypeError on instantiation, preventing bugs.

2. Free Functionality: By implementing the required abstract methods, your custom class gets a rich set of concrete methods for free, thanks to the mixin methods provided by the ABC.

This chapter will demonstrate how to build a custom mutable sequence by inheriting from collections.abc.MutableSequence.

Abstract Base Classes for Collections

The collections.abc module provides a hierarchy of ABCs for various collection types. Some of the most important are:

• Iterable, Container, Sized: The most basic ABCs. Iterable requires __iter__, Container requires __contains__, and Sized requires __len__.

• Sequence, Mapping, Set: The immutable collection types. Sequence is for ordered, indexed collections. Mapping is for key-value pairs.

• MutableSequence, MutableMapping, MutableSet: The mutable versions of the above.

Building a Custom Sequence: UniqueSequence

Let's build a UniqueSequence, a class that behaves like a list but does not allow duplicate items. By inheriting from collections.abc.MutableSequence, we only need to implement a handful of abstract methods to get the full functionality of a list.

The abstract methods required for MutableSequence are:

• __getitem__

• __setitem__

• __delitem__

• __len__

• insert

import collections.abc

class UniqueSequence(collections.abc.MutableSequence):
    """A sequence that maintains insertion order and contains no duplicates."""

    def __init__(self, initial_data=None):
        # Use a dict to store items for O(1) lookup and to maintain order (Python 3.7+)
        self._data = {}
        if initial_data:
            for item in initial_data:
                self.append(item)

    def _check_value(self, value):
        """Helper to check if a value already exists."""
        if value in self._data:
            raise ValueError(f"Value '{value}' already exists in the sequence.")

    # --- Implementing the 5 required abstract methods ---

    def __getitem__(self, index):
        # Convert dict keys to a list to access by index
        return list(self._data.keys())[index]

    def __setitem__(self, index, value):
        self._check_value(value)
        # To replace an item, we need its old key
        old_key = list(self._data.keys())[index]
        # Rebuild the dictionary to maintain order
        new_data = {}
        for k, v in self._data.items():
            if k == old_key:
                new_data[value] = None
            else:
                new_data[k] = None
        self._data = new_data

    def __delitem__(self, index):
        key_to_delete = list(self._data.keys())[index]
        del self._data[key_to_delete]

    def __len__(self):
        return len(self._data)

    def insert(self, index, value):
        self._check_value(value)
        # Rebuild the dictionary to insert at the correct position
        items = list(self._data.keys())
        items.insert(index, value)
        self._data = {item: None for item in items}

    def __repr__(self):
        return f"{self.__class__.__name__}({list(self._data.keys())})"

The "Free" Methods

Now, even though we only implemented five core methods, our UniqueSequence class can do much more. The mixin methods from MutableSequence are automatically available.

>>> u_seq = UniqueSequence(['apple', 'banana', 'orange'])
>>> u_seq
UniqueSequence(['apple', 'banana', 'orange'])

# append() is a free method. It calls our insert() under the hood.
>>> u_seq.append('grape')
>>> u_seq
UniqueSequence(['apple', 'banana', 'orange', 'grape'])

# Trying to add a duplicate raises our custom error
>>> u_seq.append('apple')
# ValueError: Value 'apple' already exists in the sequence.

# __contains__ (the 'in' operator) works for free.
>>> 'banana' in u_seq
True

# reverse() works for free.
>>> u_seq.reverse()
>>> u_seq
UniqueSequence(['grape', 'orange', 'banana', 'apple'])

# pop() works for free. It calls our __delitem__.
>>> u_seq.pop()
'apple'
>>> u_seq
UniqueSequence(['grape', 'orange', 'banana'])

Methods like append, extend, pop, reverse, __contains__, and clear are all inherited from the MutableSequence ABC. They are implemented in terms of the five abstract methods we provided. This saves an enormous amount of work and ensures that our custom container behaves consistently and correctly.

Summary

When you need to create a custom container, inheriting from the collections.abc module is the definitive, Pythonic approach. It provides a formal contract that your class must adhere to, catching errors early and ensuring a complete implementation. In return for implementing a small set of core methods, you receive a wealth of additional functionality for free, making your custom container a well-behaved and fully-featured citizen of the Python ecosystem.