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.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 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(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 callscls(iterable)to produce a new set. If theSetmixin 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__ge__(), then the other operations will automatically follow suit. - The
Setmixin 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 bothSet()andHashable(), then define__hash__ = Set._hash.
See also
- OrderedSet recipe for an
example built on
MutableSet. - For more about ABCs, see the
abcmodule and PEP 3119.
