Raymond Hettinger | 158c9c2 | 2011-02-22 00:41:50 +0000 | [diff] [blame] | 1 | :mod:`collections.abc` --- Abstract Base Classes for Containers |
| 2 | =============================================================== |
| 3 | |
| 4 | .. module:: collections.abc |
| 5 | :synopsis: Abstract base classes for containers |
| 6 | .. moduleauthor:: Raymond Hettinger <python at rcn.com> |
| 7 | .. sectionauthor:: Raymond Hettinger <python at rcn.com> |
| 8 | |
Éric Araujo | b389eec | 2011-08-16 19:10:24 +0200 | [diff] [blame] | 9 | .. versionadded:: 3.3 |
| 10 | Formerly, this module was part of the :mod:`collections` module. |
| 11 | |
Raymond Hettinger | 158c9c2 | 2011-02-22 00:41:50 +0000 | [diff] [blame] | 12 | .. testsetup:: * |
| 13 | |
| 14 | from collections import * |
| 15 | import itertools |
| 16 | __name__ = '<doctest>' |
| 17 | |
| 18 | **Source code:** :source:`Lib/collections/abc.py` |
| 19 | |
| 20 | -------------- |
| 21 | |
| 22 | This module provides :term:`abstract base classes <abstract base class>` that |
| 23 | can be used to test whether a class provides a particular interface; for |
| 24 | example, whether it is hashable or whether it is a mapping. |
| 25 | |
Raymond Hettinger | 158c9c2 | 2011-02-22 00:41:50 +0000 | [diff] [blame] | 26 | |
Éric Araujo | f90112e | 2011-06-03 19:18:41 +0200 | [diff] [blame] | 27 | .. _collections-abstract-base-classes: |
Raymond Hettinger | 158c9c2 | 2011-02-22 00:41:50 +0000 | [diff] [blame] | 28 | |
| 29 | Collections Abstract Base Classes |
| 30 | --------------------------------- |
| 31 | |
Ezio Melotti | c831a91 | 2011-03-28 19:27:09 +0300 | [diff] [blame] | 32 | The collections module offers the following :term:`ABCs <abstract base class>`: |
Raymond Hettinger | 158c9c2 | 2011-02-22 00:41:50 +0000 | [diff] [blame] | 33 | |
| 34 | ========================= ===================== ====================== ==================================================== |
Ezio Melotti | c831a91 | 2011-03-28 19:27:09 +0300 | [diff] [blame] | 35 | ABC Inherits from Abstract Methods Mixin Methods |
Raymond Hettinger | 158c9c2 | 2011-02-22 00:41:50 +0000 | [diff] [blame] | 36 | ========================= ===================== ====================== ==================================================== |
| 37 | :class:`Container` ``__contains__`` |
| 38 | :class:`Hashable` ``__hash__`` |
| 39 | :class:`Iterable` ``__iter__`` |
| 40 | :class:`Iterator` :class:`Iterable` ``__next__`` ``__iter__`` |
| 41 | :class:`Sized` ``__len__`` |
| 42 | :class:`Callable` ``__call__`` |
| 43 | |
Raymond Hettinger | 3ddba16 | 2013-03-23 09:07:36 -0700 | [diff] [blame] | 44 | :class:`Sequence` :class:`Sized`, ``__getitem__``, ``__contains__``, ``__iter__``, ``__reversed__``, |
| 45 | :class:`Iterable`, ``__len__`` ``index``, and ``count`` |
Raymond Hettinger | 158c9c2 | 2011-02-22 00:41:50 +0000 | [diff] [blame] | 46 | :class:`Container` |
| 47 | |
Raymond Hettinger | 3ddba16 | 2013-03-23 09:07:36 -0700 | [diff] [blame] | 48 | :class:`MutableSequence` :class:`Sequence` ``__getitem__``, Inherited :class:`Sequence` methods and |
| 49 | ``__setitem__``, ``append``, ``reverse``, ``extend``, ``pop``, |
| 50 | ``__delitem__``, ``remove``, and ``__iadd__`` |
| 51 | ``__len__``, |
| 52 | ``insert`` |
Raymond Hettinger | 158c9c2 | 2011-02-22 00:41:50 +0000 | [diff] [blame] | 53 | |
Raymond Hettinger | 3ddba16 | 2013-03-23 09:07:36 -0700 | [diff] [blame] | 54 | :class:`Set` :class:`Sized`, ``__contains__``, ``__le__``, ``__lt__``, ``__eq__``, ``__ne__``, |
| 55 | :class:`Iterable`, ``__iter__``, ``__gt__``, ``__ge__``, ``__and__``, ``__or__``, |
| 56 | :class:`Container` ``__len__`` ``__sub__``, ``__xor__``, and ``isdisjoint`` |
Raymond Hettinger | 158c9c2 | 2011-02-22 00:41:50 +0000 | [diff] [blame] | 57 | |
Raymond Hettinger | 3ddba16 | 2013-03-23 09:07:36 -0700 | [diff] [blame] | 58 | :class:`MutableSet` :class:`Set` ``__contains__``, Inherited :class:`Set` methods and |
| 59 | ``__iter__``, ``clear``, ``pop``, ``remove``, ``__ior__``, |
| 60 | ``__len__``, ``__iand__``, ``__ixor__``, and ``__isub__`` |
| 61 | ``add``, |
| 62 | ``discard`` |
Raymond Hettinger | 158c9c2 | 2011-02-22 00:41:50 +0000 | [diff] [blame] | 63 | |
Raymond Hettinger | 3ddba16 | 2013-03-23 09:07:36 -0700 | [diff] [blame] | 64 | :class:`Mapping` :class:`Sized`, ``__getitem__``, ``__contains__``, ``keys``, ``items``, ``values``, |
| 65 | :class:`Iterable`, ``__iter__``, ``get``, ``__eq__``, and ``__ne__`` |
| 66 | :class:`Container` ``__len__`` |
Raymond Hettinger | 158c9c2 | 2011-02-22 00:41:50 +0000 | [diff] [blame] | 67 | |
Raymond Hettinger | 3ddba16 | 2013-03-23 09:07:36 -0700 | [diff] [blame] | 68 | :class:`MutableMapping` :class:`Mapping` ``__getitem__``, Inherited :class:`Mapping` methods and |
| 69 | ``__setitem__``, ``pop``, ``popitem``, ``clear``, ``update``, |
| 70 | ``__delitem__``, and ``setdefault`` |
| 71 | ``__iter__``, |
| 72 | ``__len__`` |
Raymond Hettinger | 158c9c2 | 2011-02-22 00:41:50 +0000 | [diff] [blame] | 73 | |
| 74 | |
| 75 | :class:`MappingView` :class:`Sized` ``__len__`` |
Raymond Hettinger | 158c9c2 | 2011-02-22 00:41:50 +0000 | [diff] [blame] | 76 | :class:`ItemsView` :class:`MappingView`, ``__contains__``, |
| 77 | :class:`Set` ``__iter__`` |
Ezio Melotti | c831a91 | 2011-03-28 19:27:09 +0300 | [diff] [blame] | 78 | :class:`KeysView` :class:`MappingView`, ``__contains__``, |
| 79 | :class:`Set` ``__iter__`` |
Raymond Hettinger | 158c9c2 | 2011-02-22 00:41:50 +0000 | [diff] [blame] | 80 | :class:`ValuesView` :class:`MappingView` ``__contains__``, ``__iter__`` |
| 81 | ========================= ===================== ====================== ==================================================== |
| 82 | |
Ezio Melotti | c831a91 | 2011-03-28 19:27:09 +0300 | [diff] [blame] | 83 | |
| 84 | .. class:: Container |
| 85 | Hashable |
| 86 | Sized |
| 87 | Callable |
| 88 | |
| 89 | ABCs for classes that provide respectively the methods :meth:`__contains__`, |
| 90 | :meth:`__hash__`, :meth:`__len__`, and :meth:`__call__`. |
| 91 | |
| 92 | .. class:: Iterable |
| 93 | |
| 94 | ABC for classes that provide the :meth:`__iter__` method. |
| 95 | See also the definition of :term:`iterable`. |
| 96 | |
| 97 | .. class:: Iterator |
| 98 | |
Andrew Svetlov | e2303f8 | 2012-12-18 15:53:15 +0200 | [diff] [blame] | 99 | ABC for classes that provide the :meth:`__iter__` and :meth:`__next__` methods. |
Ezio Melotti | c831a91 | 2011-03-28 19:27:09 +0300 | [diff] [blame] | 100 | See also the definition of :term:`iterator`. |
| 101 | |
| 102 | .. class:: Sequence |
| 103 | MutableSequence |
| 104 | |
| 105 | ABCs for read-only and mutable :term:`sequences <sequence>`. |
| 106 | |
| 107 | .. class:: Set |
| 108 | MutableSet |
| 109 | |
| 110 | ABCs for read-only and mutable sets. |
| 111 | |
| 112 | .. class:: Mapping |
| 113 | MutableMapping |
| 114 | |
| 115 | ABCs for read-only and mutable :term:`mappings <mapping>`. |
| 116 | |
| 117 | .. class:: MappingView |
| 118 | ItemsView |
| 119 | KeysView |
| 120 | ValuesView |
| 121 | |
| 122 | ABCs for mapping, items, keys, and values :term:`views <view>`. |
| 123 | |
| 124 | |
Raymond Hettinger | 158c9c2 | 2011-02-22 00:41:50 +0000 | [diff] [blame] | 125 | These ABCs allow us to ask classes or instances if they provide |
| 126 | particular functionality, for example:: |
| 127 | |
| 128 | size = None |
| 129 | if isinstance(myvar, collections.Sized): |
| 130 | size = len(myvar) |
| 131 | |
| 132 | Several of the ABCs are also useful as mixins that make it easier to develop |
| 133 | classes supporting container APIs. For example, to write a class supporting |
| 134 | the full :class:`Set` API, it only necessary to supply the three underlying |
| 135 | abstract methods: :meth:`__contains__`, :meth:`__iter__`, and :meth:`__len__`. |
| 136 | The ABC supplies the remaining methods such as :meth:`__and__` and |
| 137 | :meth:`isdisjoint` :: |
| 138 | |
| 139 | class ListBasedSet(collections.Set): |
| 140 | ''' Alternate set implementation favoring space over speed |
| 141 | and not requiring the set elements to be hashable. ''' |
| 142 | def __init__(self, iterable): |
| 143 | self.elements = lst = [] |
| 144 | for value in iterable: |
| 145 | if value not in lst: |
| 146 | lst.append(value) |
| 147 | def __iter__(self): |
| 148 | return iter(self.elements) |
| 149 | def __contains__(self, value): |
| 150 | return value in self.elements |
| 151 | def __len__(self): |
| 152 | return len(self.elements) |
| 153 | |
| 154 | s1 = ListBasedSet('abcdef') |
| 155 | s2 = ListBasedSet('defghi') |
| 156 | overlap = s1 & s2 # The __and__() method is supported automatically |
| 157 | |
| 158 | Notes on using :class:`Set` and :class:`MutableSet` as a mixin: |
| 159 | |
| 160 | (1) |
| 161 | Since some set operations create new sets, the default mixin methods need |
| 162 | a way to create new instances from an iterable. The class constructor is |
| 163 | assumed to have a signature in the form ``ClassName(iterable)``. |
| 164 | That assumption is factored-out to an internal classmethod called |
| 165 | :meth:`_from_iterable` which calls ``cls(iterable)`` to produce a new set. |
| 166 | If the :class:`Set` mixin is being used in a class with a different |
Antoine Pitrou | 3692035 | 2011-03-22 18:33:33 +0100 | [diff] [blame] | 167 | constructor signature, you will need to override :meth:`_from_iterable` |
Raymond Hettinger | 158c9c2 | 2011-02-22 00:41:50 +0000 | [diff] [blame] | 168 | with a classmethod that can construct new instances from |
| 169 | an iterable argument. |
| 170 | |
| 171 | (2) |
| 172 | To override the comparisons (presumably for speed, as the |
| 173 | semantics are fixed), redefine :meth:`__le__` and |
| 174 | then the other operations will automatically follow suit. |
| 175 | |
| 176 | (3) |
| 177 | The :class:`Set` mixin provides a :meth:`_hash` method to compute a hash value |
| 178 | for the set; however, :meth:`__hash__` is not defined because not all sets |
| 179 | are hashable or immutable. To add set hashabilty using mixins, |
| 180 | inherit from both :meth:`Set` and :meth:`Hashable`, then define |
| 181 | ``__hash__ = Set._hash``. |
| 182 | |
| 183 | .. seealso:: |
| 184 | |
Éric Araujo | 459b452 | 2011-06-04 21:16:42 +0200 | [diff] [blame] | 185 | * `OrderedSet recipe <http://code.activestate.com/recipes/576694/>`_ for an |
| 186 | example built on :class:`MutableSet`. |
Raymond Hettinger | 158c9c2 | 2011-02-22 00:41:50 +0000 | [diff] [blame] | 187 | |
Éric Araujo | 459b452 | 2011-06-04 21:16:42 +0200 | [diff] [blame] | 188 | * For more about ABCs, see the :mod:`abc` module and :pep:`3119`. |