This document is for an old version of Python that is no longer supported. You should upgrade, and read the Python documentation for the current stable release.

8.4. — Abstract Base Classes for Containers

New in version 3.3: Formerly, this module was part of the collections module.

Source code: Lib/

This module provides abstract base classes that can be used to test whether a class provides a particular interface; for example, whether it is hashable or whether it is a mapping.

8.4.1. Collections Abstract Base Classes

The collections module offers the following ABCs:

ABC Inherits from Abstract Methods Mixin Methods
Container   __contains__  
Hashable   __hash__  
Iterable   __iter__  
Iterator Iterable __next__ __iter__
Sized   __len__  
Callable   __call__  
Sequence Sized, Iterable, Container __getitem__, __len__ __contains__, __iter__, __reversed__, index, and count
MutableSequence Sequence __getitem__, __setitem__, __delitem__, __len__, insert Inherited Sequence methods and append, reverse, extend, pop, remove, and __iadd__
Set Sized, Iterable, Container __contains__, __iter__, __len__ __le__, __lt__, __eq__, __ne__, __gt__, __ge__, __and__, __or__, __sub__, __xor__, and isdisjoint
MutableSet Set __contains__, __iter__, __len__, add, discard Inherited Set methods and clear, pop, remove, __ior__, __iand__, __ixor__, and __isub__
Mapping Sized, Iterable, Container __getitem__, __iter__, __len__ __contains__, keys, items, values, get, __eq__, and __ne__
MutableMapping Mapping __getitem__, __setitem__, __delitem__, __iter__, __len__ Inherited Mapping methods and pop, popitem, clear, update, and setdefault
MappingView Sized   __len__
ItemsView MappingView, Set   __contains__, __iter__
KeysView MappingView, Set   __contains__, __iter__
ValuesView MappingView   __contains__, __iter__

ABCs for classes that provide respectively the methods __contains__(), __hash__(), __len__(), and __call__().


ABC for classes that provide the __iter__() method. See also the definition of iterable.


ABC for classes that provide the __iter__() and __next__() methods. See also the definition of iterator.


ABCs for read-only and mutable sequences.


ABCs for read-only and mutable sets.


ABCs for read-only and mutable mappings.


ABCs for mapping, items, keys, and values views.

These ABCs allow us to ask classes or instances if they provide particular functionality, for example:

size = None
if isinstance(myvar,
    size = len(myvar)

Several of the ABCs are also useful as mixins that make it easier to develop classes supporting container APIs. For example, to write a class supporting the full Set API, it is only necessary to supply the three underlying abstract methods: __contains__(), __iter__(), and __len__(). The ABC supplies the remaining methods such as __and__() and isdisjoint():

class ListBasedSet(
     ''' Alternate set implementation favoring space over speed
         and not requiring the set elements to be hashable. '''
     def __init__(self, iterable):
         self.elements = lst = []
         for value in iterable:
             if value not in lst:
     def __iter__(self):
         return iter(self.elements)
     def __contains__(self, value):
         return value in self.elements
     def __len__(self):
         return len(self.elements)

s1 = ListBasedSet('abcdef')
s2 = ListBasedSet('defghi')
overlap = s1 & s2            # The __and__() method is supported automatically

Notes on using Set and MutableSet as a mixin:

  1. Since some set operations create new sets, the default mixin methods need a way to create new instances from an iterable. The class constructor is assumed to have a signature in the form ClassName(iterable). That assumption is factored-out to an internal classmethod called _from_iterable() which calls cls(iterable) to produce a new set. If the Set mixin is being used in a class with a different constructor signature, you will need to override _from_iterable() with a classmethod that can construct new instances from an iterable argument.
  2. To override the comparisons (presumably for speed, as the semantics are fixed), redefine __le__() and __ge__(), then the other operations will automatically follow suit.
  3. The Set mixin provides a _hash() method to compute a hash value for the set; however, __hash__() is not defined because not all sets are hashable or immutable. To add set hashability using mixins, inherit from both Set() and Hashable(), then define __hash__ = Set._hash.

See also