Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(3)

Delta Between Two Patch Sets: Doc/library/collections.abc.rst

Issue 25958: Implicit ABCs have no means of "anti-registration"
Left Patch Set: Created 4 years, 1 month ago
Right Patch Set: Created 3 years, 6 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
Left: Side by side diff | Download
Right: Side by side diff | Download
« no previous file with change/comment | « no previous file | Doc/reference/datamodel.rst » ('j') | no next file with change/comment »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
LEFTRIGHT
1 :mod:`collections.abc` --- Abstract Base Classes for Containers 1 :mod:`collections.abc` --- Abstract Base Classes for Containers
2 =============================================================== 2 ===============================================================
3 3
4 .. module:: collections.abc 4 .. module:: collections.abc
5 :synopsis: Abstract base classes for containers 5 :synopsis: Abstract base classes for containers
6
6 .. moduleauthor:: Raymond Hettinger <python at rcn.com> 7 .. moduleauthor:: Raymond Hettinger <python at rcn.com>
7 .. sectionauthor:: Raymond Hettinger <python at rcn.com> 8 .. sectionauthor:: Raymond Hettinger <python at rcn.com>
8 9
9 .. versionadded:: 3.3 10 .. versionadded:: 3.3
10 Formerly, this module was part of the :mod:`collections` module. 11 Formerly, this module was part of the :mod:`collections` module.
12
13 **Source code:** :source:`Lib/_collections_abc.py`
11 14
12 .. testsetup:: * 15 .. testsetup:: *
13 16
14 from collections import * 17 from collections import *
15 import itertools 18 import itertools
16 __name__ = '<doctest>' 19 __name__ = '<doctest>'
17
18 **Source code:** :source:`Lib/_collections_abc.py`
19 20
20 -------------- 21 --------------
21 22
22 This module provides :term:`abstract base classes <abstract base class>` that 23 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 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 example, whether it is hashable or whether it is a mapping.
25 26
26 27
27 .. _collections-abstract-base-classes: 28 .. _collections-abstract-base-classes:
28 29
29 Collections Abstract Base Classes 30 Collections Abstract Base Classes
30 --------------------------------- 31 ---------------------------------
31 32
32 The collections module offers the following :term:`ABCs <abstract base class>`: 33 The collections module offers the following :term:`ABCs <abstract base class>`:
33 34
34 .. tabularcolumns:: |l|L|L|L| 35 .. tabularcolumns:: |l|L|L|L|
35 36
36 ========================== ====================== ======================= ====== ============================================== 37 ========================== ====================== ======================= ====== ==============================================
37 ABC Inherits from Abstract Methods Mixin Methods 38 ABC Inherits from Abstract Methods Mixin Methods
38 ========================== ====================== ======================= ====== ============================================== 39 ========================== ====================== ======================= ====== ==============================================
39 :class:`Container` ``__contains__`` 40 :class:`Container` ``__contains__``
40 :class:`Hashable` ``__hash__`` 41 :class:`Hashable` ``__hash__``
41 :class:`Iterable` ``__iter__`` 42 :class:`Iterable` ``__iter__``
42 :class:`Iterator` :class:`Iterable` ``__next__`` ``__it er__`` 43 :class:`Iterator` :class:`Iterable` ``__next__`` ``__it er__``
44 :class:`Reversible` :class:`Iterable` ``__reversed__``
43 :class:`Generator` :class:`Iterator` ``send``, ``throw`` ``clos e``, ``__iter__``, ``__next__`` 45 :class:`Generator` :class:`Iterator` ``send``, ``throw`` ``clos e``, ``__iter__``, ``__next__``
44 :class:`Sized` ``__len__`` 46 :class:`Sized` ``__len__``
45 :class:`Reversible` :class:`Iterable` ``__reversed__``
46 :class:`Callable` ``__call__`` 47 :class:`Callable` ``__call__``
47 48
48 :class:`Sequence` :class:`Sized`, ``__getitem__``, ``__co ntains__``, ``__iter__``, ``__reversed__``, 49 :class:`Sequence` :class:`Sized`, ``__getitem__``, ``__co ntains__``, ``__iter__``, ``__reversed__``,
49 :class:`Reversible`, ``__len__`` ``inde x``, and ``count`` 50 :class:`Reversible`, ``__len__`` ``inde x``, and ``count``
50 :class:`Container` 51 :class:`Container`
51 52
52 :class:`MutableSequence` :class:`Sequence` ``__getitem__``, Inheri ted :class:`Sequence` methods and 53 :class:`MutableSequence` :class:`Sequence` ``__getitem__``, Inheri ted :class:`Sequence` methods and
53 ``__setitem__``, ``appe nd``, ``reverse``, ``extend``, ``pop``, 54 ``__setitem__``, ``appe nd``, ``reverse``, ``extend``, ``pop``,
54 ``__delitem__``, ``remo ve``, and ``__iadd__`` 55 ``__delitem__``, ``remo ve``, and ``__iadd__``
55 ``__len__``, 56 ``__len__``,
56 ``insert`` 57 ``insert``
58
59 :class:`ByteString` :class:`Sequence` ``__getitem__``, Inheri ted :class:`Sequence` methods
60 ``__len__``
57 61
58 :class:`Set` :class:`Sized`, ``__contains__``, ``__le __``, ``__lt__``, ``__eq__``, ``__ne__``, 62 :class:`Set` :class:`Sized`, ``__contains__``, ``__le __``, ``__lt__``, ``__eq__``, ``__ne__``,
59 :class:`Iterable`, ``__iter__``, ``__gt __``, ``__ge__``, ``__and__``, ``__or__``, 63 :class:`Iterable`, ``__iter__``, ``__gt __``, ``__ge__``, ``__and__``, ``__or__``,
60 :class:`Container` ``__len__`` ``__su b__``, ``__xor__``, and ``isdisjoint`` 64 :class:`Container` ``__len__`` ``__su b__``, ``__xor__``, and ``isdisjoint``
61 65
62 :class:`MutableSet` :class:`Set` ``__contains__``, Inheri ted :class:`Set` methods and 66 :class:`MutableSet` :class:`Set` ``__contains__``, Inheri ted :class:`Set` methods and
63 ``__iter__``, ``clea r``, ``pop``, ``remove``, ``__ior__``, 67 ``__iter__``, ``clea r``, ``pop``, ``remove``, ``__ior__``,
64 ``__len__``, ``__ia nd__``, ``__ixor__``, and ``__isub__`` 68 ``__len__``, ``__ia nd__``, ``__ixor__``, and ``__isub__``
65 ``add``, 69 ``add``,
66 ``discard`` 70 ``discard``
(...skipping 34 matching lines...) Expand 10 before | Expand all | Expand 10 after
101 105
102 ABC for classes that provide the :meth:`__iter__` method. 106 ABC for classes that provide the :meth:`__iter__` method.
103 See also the definition of :term:`iterable`. 107 See also the definition of :term:`iterable`.
104 108
105 .. class:: Iterator 109 .. class:: Iterator
106 110
107 ABC for classes that provide the :meth:`~iterator.__iter__` and 111 ABC for classes that provide the :meth:`~iterator.__iter__` and
108 :meth:`~iterator.__next__` methods. See also the definition of 112 :meth:`~iterator.__next__` methods. See also the definition of
109 :term:`iterator`. 113 :term:`iterator`.
110 114
115 .. class:: Reversible
116
117 ABC for iterable classes that also provide the :meth:`__reversed__`
118 method.
119
120 .. versionadded:: 3.6
121
111 .. class:: Generator 122 .. class:: Generator
112 123
113 ABC for generator classes that implement the protocol defined in 124 ABC for generator classes that implement the protocol defined in
114 :pep:`342` that extends iterators with the :meth:`~generator.send`, 125 :pep:`342` that extends iterators with the :meth:`~generator.send`,
115 :meth:`~generator.throw` and :meth:`~generator.close` methods. 126 :meth:`~generator.throw` and :meth:`~generator.close` methods.
116 See also the definition of :term:`generator`. 127 See also the definition of :term:`generator`.
117 128
118 .. versionadded:: 3.5 129 .. versionadded:: 3.5
119 130
120 .. class:: Reversible
121
122 ABC for iterable classes that also provide the :meth:`__reversed__`
123 method.
124
125 .. versionadded:: 3.6
126
127 .. class:: Sequence 131 .. class:: Sequence
128 MutableSequence 132 MutableSequence
133 ByteString
129 134
130 ABCs for read-only and mutable :term:`sequences <sequence>`. 135 ABCs for read-only and mutable :term:`sequences <sequence>`.
131 136
132 Implementation note: Some of the mixin methods, such as 137 Implementation note: Some of the mixin methods, such as
133 :meth:`__iter__`, :meth:`__reversed__` and :meth:`index`, make 138 :meth:`__iter__`, :meth:`__reversed__` and :meth:`index`, make
134 repeated calls to the underlying :meth:`__getitem__` method. 139 repeated calls to the underlying :meth:`__getitem__` method.
135 Consequently, if :meth:`__getitem__` is implemented with constant 140 Consequently, if :meth:`__getitem__` is implemented with constant
136 access speed, the mixin methods will have linear performance; 141 access speed, the mixin methods will have linear performance;
137 however, if the underlying method is linear (as it would be with a 142 however, if the underlying method is linear (as it would be with a
138 linked list), the mixins will have quadratic performance and will 143 linked list), the mixins will have quadratic performance and will
139 likely need to be overridden. 144 likely need to be overridden.
140 145
141 .. versionchanged:: 3.5 146 .. versionchanged:: 3.5
142 The index() method added support for *stop* and *start* 147 The index() method added support for *stop* and *start*
143 arguments. 148 arguments.
144 149
145
146 .. class:: Set 150 .. class:: Set
147 MutableSet 151 MutableSet
148 152
149 ABCs for read-only and mutable sets. 153 ABCs for read-only and mutable sets.
150 154
151 .. class:: Mapping 155 .. class:: Mapping
152 MutableMapping 156 MutableMapping
153 157
154 ABCs for read-only and mutable :term:`mappings <mapping>`. 158 ABCs for read-only and mutable :term:`mappings <mapping>`.
155 159
(...skipping 63 matching lines...) Expand 10 before | Expand all | Expand 10 after
219 size = len(myvar) 223 size = len(myvar)
220 224
221 Several of the ABCs are also useful as mixins that make it easier to develop 225 Several of the ABCs are also useful as mixins that make it easier to develop
222 classes supporting container APIs. For example, to write a class supporting 226 classes supporting container APIs. For example, to write a class supporting
223 the full :class:`Set` API, it is only necessary to supply the three underlying 227 the full :class:`Set` API, it is only necessary to supply the three underlying
224 abstract methods: :meth:`__contains__`, :meth:`__iter__`, and :meth:`__len__`. 228 abstract methods: :meth:`__contains__`, :meth:`__iter__`, and :meth:`__len__`.
225 The ABC supplies the remaining methods such as :meth:`__and__` and 229 The ABC supplies the remaining methods such as :meth:`__and__` and
226 :meth:`isdisjoint`:: 230 :meth:`isdisjoint`::
227 231
228 class ListBasedSet(collections.abc.Set): 232 class ListBasedSet(collections.abc.Set):
229 ''' Alternate set implementation favoring space over speed 233 ''' Alternate set implementation favoring space over speed
230 and not requiring the set elements to be hashable. ''' 234 and not requiring the set elements to be hashable. '''
231 def __init__(self, iterable): 235 def __init__(self, iterable):
232 self.elements = lst = [] 236 self.elements = lst = []
233 for value in iterable: 237 for value in iterable:
234 if value not in lst: 238 if value not in lst:
235 lst.append(value) 239 lst.append(value)
236 def __iter__(self): 240
237 return iter(self.elements) 241 def __iter__(self):
238 def __contains__(self, value): 242 return iter(self.elements)
239 return value in self.elements 243
240 def __len__(self): 244 def __contains__(self, value):
241 return len(self.elements) 245 return value in self.elements
246
247 def __len__(self):
248 return len(self.elements)
242 249
243 s1 = ListBasedSet('abcdef') 250 s1 = ListBasedSet('abcdef')
244 s2 = ListBasedSet('defghi') 251 s2 = ListBasedSet('defghi')
245 overlap = s1 & s2 # The __and__() method is supported automatical ly 252 overlap = s1 & s2 # The __and__() method is supported automatical ly
246 253
247 Notes on using :class:`Set` and :class:`MutableSet` as a mixin: 254 Notes on using :class:`Set` and :class:`MutableSet` as a mixin:
248 255
249 (1) 256 (1)
250 Since some set operations create new sets, the default mixin methods need 257 Since some set operations create new sets, the default mixin methods need
251 a way to create new instances from an iterable. The class constructor is 258 a way to create new instances from an iterable. The class constructor is
(...skipping 12 matching lines...) Expand all
264 271
265 (3) 272 (3)
266 The :class:`Set` mixin provides a :meth:`_hash` method to compute a hash valu e 273 The :class:`Set` mixin provides a :meth:`_hash` method to compute a hash valu e
267 for the set; however, :meth:`__hash__` is not defined because not all sets 274 for the set; however, :meth:`__hash__` is not defined because not all sets
268 are hashable or immutable. To add set hashability using mixins, 275 are hashable or immutable. To add set hashability using mixins,
269 inherit from both :meth:`Set` and :meth:`Hashable`, then define 276 inherit from both :meth:`Set` and :meth:`Hashable`, then define
270 ``__hash__ = Set._hash``. 277 ``__hash__ = Set._hash``.
271 278
272 .. seealso:: 279 .. seealso::
273 280
274 * `OrderedSet recipe <http://code.activestate.com/recipes/576694/>`_ for an 281 * `OrderedSet recipe <https://code.activestate.com/recipes/576694/>`_ for an
275 example built on :class:`MutableSet`. 282 example built on :class:`MutableSet`.
276 283
277 * For more about ABCs, see the :mod:`abc` module and :pep:`3119`. 284 * For more about ABCs, see the :mod:`abc` module and :pep:`3119`.
LEFTRIGHT

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+