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

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:: Sequence 131 .. class:: Sequence
121 MutableSequence 132 MutableSequence
133 ByteString
122 134
123 ABCs for read-only and mutable :term:`sequences <sequence>`. 135 ABCs for read-only and mutable :term:`sequences <sequence>`.
124 136
125 Implementation note: Some of the mixin methods, such as 137 Implementation note: Some of the mixin methods, such as
126 :meth:`__iter__`, :meth:`__reversed__` and :meth:`index`, make 138 :meth:`__iter__`, :meth:`__reversed__` and :meth:`index`, make
127 repeated calls to the underlying :meth:`__getitem__` method. 139 repeated calls to the underlying :meth:`__getitem__` method.
128 Consequently, if :meth:`__getitem__` is implemented with constant 140 Consequently, if :meth:`__getitem__` is implemented with constant
129 access speed, the mixin methods will have linear performance; 141 access speed, the mixin methods will have linear performance;
130 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
131 linked list), the mixins will have quadratic performance and will 143 linked list), the mixins will have quadratic performance and will
132 likely need to be overridden. 144 likely need to be overridden.
133 145
134 .. versionchanged:: 3.5 146 .. versionchanged:: 3.5
135 The index() method added support for *stop* and *start* 147 The index() method added support for *stop* and *start*
136 arguments. 148 arguments.
137 149
138
139 .. class:: Set 150 .. class:: Set
140 MutableSet 151 MutableSet
141 152
142 ABCs for read-only and mutable sets. 153 ABCs for read-only and mutable sets.
143 154
144 .. class:: Mapping 155 .. class:: Mapping
145 MutableMapping 156 MutableMapping
146 157
147 ABCs for read-only and mutable :term:`mappings <mapping>`. 158 ABCs for read-only and mutable :term:`mappings <mapping>`.
148 159
(...skipping 63 matching lines...) Expand 10 before | Expand all | Expand 10 after
212 size = len(myvar) 223 size = len(myvar)
213 224
214 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
215 classes supporting container APIs. For example, to write a class supporting 226 classes supporting container APIs. For example, to write a class supporting
216 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
217 abstract methods: :meth:`__contains__`, :meth:`__iter__`, and :meth:`__len__`. 228 abstract methods: :meth:`__contains__`, :meth:`__iter__`, and :meth:`__len__`.
218 The ABC supplies the remaining methods such as :meth:`__and__` and 229 The ABC supplies the remaining methods such as :meth:`__and__` and
219 :meth:`isdisjoint`:: 230 :meth:`isdisjoint`::
220 231
221 class ListBasedSet(collections.abc.Set): 232 class ListBasedSet(collections.abc.Set):
222 ''' Alternate set implementation favoring space over speed 233 ''' Alternate set implementation favoring space over speed
223 and not requiring the set elements to be hashable. ''' 234 and not requiring the set elements to be hashable. '''
224 def __init__(self, iterable): 235 def __init__(self, iterable):
225 self.elements = lst = [] 236 self.elements = lst = []
226 for value in iterable: 237 for value in iterable:
227 if value not in lst: 238 if value not in lst:
228 lst.append(value) 239 lst.append(value)
229 def __iter__(self): 240
230 return iter(self.elements) 241 def __iter__(self):
231 def __contains__(self, value): 242 return iter(self.elements)
232 return value in self.elements 243
233 def __len__(self): 244 def __contains__(self, value):
234 return len(self.elements) 245 return value in self.elements
246
247 def __len__(self):
248 return len(self.elements)
235 249
236 s1 = ListBasedSet('abcdef') 250 s1 = ListBasedSet('abcdef')
237 s2 = ListBasedSet('defghi') 251 s2 = ListBasedSet('defghi')
238 overlap = s1 & s2 # The __and__() method is supported automatical ly 252 overlap = s1 & s2 # The __and__() method is supported automatical ly
239 253
240 Notes on using :class:`Set` and :class:`MutableSet` as a mixin: 254 Notes on using :class:`Set` and :class:`MutableSet` as a mixin:
241 255
242 (1) 256 (1)
243 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
244 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
257 271
258 (3) 272 (3)
259 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
260 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
261 are hashable or immutable. To add set hashability using mixins, 275 are hashable or immutable. To add set hashability using mixins,
262 inherit from both :meth:`Set` and :meth:`Hashable`, then define 276 inherit from both :meth:`Set` and :meth:`Hashable`, then define
263 ``__hash__ = Set._hash``. 277 ``__hash__ = Set._hash``.
264 278
265 .. seealso:: 279 .. seealso::
266 280
267 * `OrderedSet recipe <http://code.activestate.com/recipes/576694/>`_ for an 281 * `OrderedSet recipe <https://code.activestate.com/recipes/576694/>`_ for an
268 example built on :class:`MutableSet`. 282 example built on :class:`MutableSet`.
269 283
270 * 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+