diff -r 1118dfcbcc35 Doc/library/collections.abc.rst --- a/Doc/library/collections.abc.rst Tue Jan 05 21:27:54 2016 +0200 +++ b/Doc/library/collections.abc.rst Tue Jan 05 18:36:11 2016 -0800 @@ -31,61 +31,61 @@ The collections module offers the following :term:`ABCs `: -.. tabularcolumns:: |l|L|L|L| +.. tabularcolumns:: |l|L|L|L|L| -========================== ====================== ======================= ==================================================== -ABC Inherits from Abstract Methods Mixin Methods -========================== ====================== ======================= ==================================================== -:class:`Container` ``__contains__`` -:class:`Hashable` ``__hash__`` -:class:`Iterable` ``__iter__`` -:class:`Iterator` :class:`Iterable` ``__next__`` ``__iter__`` -:class:`Generator` :class:`Iterator` ``send``, ``throw`` ``close``, ``__iter__``, ``__next__`` -:class:`Sized` ``__len__`` -:class:`Callable` ``__call__`` +========================== ======== ====================== ======================= ==================================================== +ABC Implicit Inherits from Abstract Methods Mixin Methods +========================== ======== ====================== ======================= ==================================================== +:class:`Container` yes ``__contains__`` +:class:`Hashable` yes ``__hash__`` +:class:`Iterable` yes ``__iter__`` +:class:`Iterator` yes :class:`Iterable` ``__next__`` ``__iter__`` +:class:`Generator` yes :class:`Iterator` ``send``, ``throw`` ``close``, ``__iter__``, ``__next__`` +:class:`Sized` yes ``__len__`` +:class:`Callable` yes ``__call__`` -:class:`Sequence` :class:`Sized`, ``__getitem__``, ``__contains__``, ``__iter__``, ``__reversed__``, - :class:`Iterable`, ``__len__`` ``index``, and ``count`` - :class:`Container` +:class:`Sequence` no :class:`Sized`, ``__getitem__``, ``__contains__``, ``__iter__``, ``__reversed__``, + :class:`Iterable`, ``__len__`` ``index``, and ``count`` + :class:`Container` -:class:`MutableSequence` :class:`Sequence` ``__getitem__``, Inherited :class:`Sequence` methods and - ``__setitem__``, ``append``, ``reverse``, ``extend``, ``pop``, - ``__delitem__``, ``remove``, and ``__iadd__`` - ``__len__``, - ``insert`` +:class:`MutableSequence` no :class:`Sequence` ``__getitem__``, Inherited :class:`Sequence` methods and + ``__setitem__``, ``append``, ``reverse``, ``extend``, ``pop``, + ``__delitem__``, ``remove``, and ``__iadd__`` + ``__len__``, + ``insert`` -:class:`Set` :class:`Sized`, ``__contains__``, ``__le__``, ``__lt__``, ``__eq__``, ``__ne__``, - :class:`Iterable`, ``__iter__``, ``__gt__``, ``__ge__``, ``__and__``, ``__or__``, - :class:`Container` ``__len__`` ``__sub__``, ``__xor__``, and ``isdisjoint`` +:class:`Set` no :class:`Sized`, ``__contains__``, ``__le__``, ``__lt__``, ``__eq__``, ``__ne__``, + :class:`Iterable`, ``__iter__``, ``__gt__``, ``__ge__``, ``__and__``, ``__or__``, + :class:`Container` ``__len__`` ``__sub__``, ``__xor__``, and ``isdisjoint`` -:class:`MutableSet` :class:`Set` ``__contains__``, Inherited :class:`Set` methods and - ``__iter__``, ``clear``, ``pop``, ``remove``, ``__ior__``, - ``__len__``, ``__iand__``, ``__ixor__``, and ``__isub__`` - ``add``, - ``discard`` +:class:`MutableSet` no :class:`Set` ``__contains__``, Inherited :class:`Set` methods and + ``__iter__``, ``clear``, ``pop``, ``remove``, ``__ior__``, + ``__len__``, ``__iand__``, ``__ixor__``, and ``__isub__`` + ``add``, + ``discard`` -:class:`Mapping` :class:`Sized`, ``__getitem__``, ``__contains__``, ``keys``, ``items``, ``values``, - :class:`Iterable`, ``__iter__``, ``get``, ``__eq__``, and ``__ne__`` - :class:`Container` ``__len__`` +:class:`Mapping` no :class:`Sized`, ``__getitem__``, ``__contains__``, ``keys``, ``items``, ``values``, + :class:`Iterable`, ``__iter__``, ``get``, ``__eq__``, and ``__ne__`` + :class:`Container` ``__len__`` -:class:`MutableMapping` :class:`Mapping` ``__getitem__``, Inherited :class:`Mapping` methods and - ``__setitem__``, ``pop``, ``popitem``, ``clear``, ``update``, - ``__delitem__``, and ``setdefault`` - ``__iter__``, - ``__len__`` +:class:`MutableMapping` no :class:`Mapping` ``__getitem__``, Inherited :class:`Mapping` methods and + ``__setitem__``, ``pop``, ``popitem``, ``clear``, ``update``, + ``__delitem__``, and ``setdefault`` + ``__iter__``, + ``__len__`` -:class:`MappingView` :class:`Sized` ``__len__`` -:class:`ItemsView` :class:`MappingView`, ``__contains__``, - :class:`Set` ``__iter__`` -:class:`KeysView` :class:`MappingView`, ``__contains__``, - :class:`Set` ``__iter__`` -:class:`ValuesView` :class:`MappingView` ``__contains__``, ``__iter__`` -:class:`Awaitable` ``__await__`` -:class:`Coroutine` :class:`Awaitable` ``send``, ``throw`` ``close`` -:class:`AsyncIterable` ``__aiter__`` -:class:`AsyncIterator` :class:`AsyncIterable` ``__anext__`` ``__aiter__`` -========================== ====================== ======================= ==================================================== +:class:`MappingView` no :class:`Sized` ``__len__`` +:class:`ItemsView` no :class:`MappingView`, ``__contains__``, + :class:`Set` ``__iter__`` +:class:`KeysView` no :class:`MappingView`, ``__contains__``, + :class:`Set` ``__iter__`` +:class:`ValuesView` no :class:`MappingView` ``__contains__``, ``__iter__`` +:class:`Awaitable` yes ``__await__`` +:class:`Coroutine` yes :class:`Awaitable` ``send``, ``throw`` ``close`` +:class:`AsyncIterable` yes ``__aiter__`` +:class:`AsyncIterator` yes :class:`AsyncIterable` ``__anext__`` ``__aiter__`` +========================== ======== ====================== ======================= ==================================================== .. class:: Container @@ -203,6 +203,8 @@ .. versionadded:: 3.5 +.. _collections-using + These ABCs allow us to ask classes or instances if they provide particular functionality, for example:: @@ -210,6 +212,14 @@ if isinstance(myvar, collections.abc.Sized): size = len(myvar) +Some ABCs (those marked "implicit" above) will automatically register +any class that implements all of their abstract methods. But others +will not; only a class that inherits from the ABC or calls its +``register`` method are subclasses. (You can count on built-in types, +like ``list`` or the unnamed type for the iterator over a dict keys +view, being registered. But for third-party types, or those you build +yourself, the class author or user has to take care of that.) + 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 :class:`Set` API, it is only necessary to supply the three underlying