8.4. collections.abc — Abstract Base Classes for Containers
New in version 3.3: Formerly, this module was part of the collections module.
Source code: Lib/collections/abc.py
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__ |
- class collections.abc.Container
- class collections.abc.Hashable
- class collections.abc.Sized
- class collections.abc.Callable
ABCs for classes that provide respectively the methods __contains__(), __hash__(), __len__(), and __call__().
- class collections.abc.Iterable
ABC for classes that provide the __iter__() method. See also the definition of iterable.
- class collections.abc.Iterator
ABC for classes that provide the __iter__() and __next__() methods. See also the definition of iterator.
- class collections.abc.Sequence
- class collections.abc.MutableSequence
ABCs for read-only and mutable sequences.
- class collections.abc.Set
- class collections.abc.MutableSet
ABCs for read-only and mutable sets.
- class collections.abc.Mapping
- class collections.abc.MutableMapping
ABCs for read-only and mutable mappings.
- class collections.abc.MappingView
- class collections.abc.ItemsView
- class collections.abc.KeysView
- class collections.abc.ValuesView
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, collections.abc.Sized):
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 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(collections.abc.Set):
''' 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:
lst.append(value)
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:
- 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.
- To override the comparisons (presumably for speed, as the semantics are fixed), redefine __le__() and then the other operations will automatically follow suit.
- 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 hashabilty using mixins, inherit from both Set() and Hashable(), then define __hash__ = Set._hash.
See also
- OrderedSet recipe for an example built on MutableSet.
- For more about ABCs, see the abc module and PEP 3119.