mirror of
https://github.com/python/cpython.git
synced 2025-11-01 18:51:43 +00:00
459b452b98
I have removed the reST target I added in 38cdca2cc253: it is not necessary, as people can link to the glossary entry or the abc module without it. Two indentation fixes from 3.2 collections.rst have been ported to 3.3 collections.abc.rst.
181 lines
7.8 KiB
ReStructuredText
181 lines
7.8 KiB
ReStructuredText
:mod:`collections.abc` --- Abstract Base Classes for Containers
|
|
===============================================================
|
|
|
|
.. module:: collections.abc
|
|
:synopsis: Abstract base classes for containers
|
|
.. moduleauthor:: Raymond Hettinger <python at rcn.com>
|
|
.. sectionauthor:: Raymond Hettinger <python at rcn.com>
|
|
|
|
.. testsetup:: *
|
|
|
|
from collections import *
|
|
import itertools
|
|
__name__ = '<doctest>'
|
|
|
|
**Source code:** :source:`Lib/collections/abc.py`
|
|
|
|
--------------
|
|
|
|
This module provides :term:`abstract base classes <abstract base class>` 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.
|
|
|
|
.. versionchanged:: 3.3
|
|
Formerly, this module was part of the :mod:`collections` module.
|
|
|
|
.. _collections-abstract-base-classes:
|
|
|
|
Collections Abstract Base Classes
|
|
---------------------------------
|
|
|
|
The collections module offers the following :term:`ABCs <abstract base class>`:
|
|
|
|
========================= ===================== ====================== ====================================================
|
|
ABC Inherits from Abstract Methods Mixin Methods
|
|
========================= ===================== ====================== ====================================================
|
|
:class:`Container` ``__contains__``
|
|
:class:`Hashable` ``__hash__``
|
|
:class:`Iterable` ``__iter__``
|
|
:class:`Iterator` :class:`Iterable` ``__next__`` ``__iter__``
|
|
:class:`Sized` ``__len__``
|
|
:class:`Callable` ``__call__``
|
|
|
|
:class:`Sequence` :class:`Sized`, ``__getitem__`` ``__contains__``, ``__iter__``, ``__reversed__``,
|
|
:class:`Iterable`, ``index``, and ``count``
|
|
:class:`Container`
|
|
|
|
:class:`MutableSequence` :class:`Sequence` ``__setitem__``, Inherited :class:`Sequence` methods and
|
|
``__delitem__``, ``append``, ``reverse``, ``extend``, ``pop``,
|
|
``insert`` ``remove``, ``clear``, and ``__iadd__``
|
|
|
|
:class:`Set` :class:`Sized`, ``__le__``, ``__lt__``, ``__eq__``, ``__ne__``,
|
|
:class:`Iterable`, ``__gt__``, ``__ge__``, ``__and__``, ``__or__``,
|
|
:class:`Container` ``__sub__``, ``__xor__``, and ``isdisjoint``
|
|
|
|
:class:`MutableSet` :class:`Set` ``add``, Inherited :class:`Set` methods and
|
|
``discard`` ``clear``, ``pop``, ``remove``, ``__ior__``,
|
|
``__iand__``, ``__ixor__``, and ``__isub__``
|
|
|
|
:class:`Mapping` :class:`Sized`, ``__getitem__`` ``__contains__``, ``keys``, ``items``, ``values``,
|
|
:class:`Iterable`, ``get``, ``__eq__``, and ``__ne__``
|
|
:class:`Container`
|
|
|
|
:class:`MutableMapping` :class:`Mapping` ``__setitem__``, Inherited :class:`Mapping` methods and
|
|
``__delitem__`` ``pop``, ``popitem``, ``clear``, ``update``,
|
|
and ``setdefault``
|
|
|
|
|
|
: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:: Container
|
|
Hashable
|
|
Sized
|
|
Callable
|
|
|
|
ABCs for classes that provide respectively the methods :meth:`__contains__`,
|
|
:meth:`__hash__`, :meth:`__len__`, and :meth:`__call__`.
|
|
|
|
.. class:: Iterable
|
|
|
|
ABC for classes that provide the :meth:`__iter__` method.
|
|
See also the definition of :term:`iterable`.
|
|
|
|
.. class:: Iterator
|
|
|
|
ABC for classes that provide the :meth:`__iter__` and :meth:`next` methods.
|
|
See also the definition of :term:`iterator`.
|
|
|
|
.. class:: Sequence
|
|
MutableSequence
|
|
|
|
ABCs for read-only and mutable :term:`sequences <sequence>`.
|
|
|
|
.. class:: Set
|
|
MutableSet
|
|
|
|
ABCs for read-only and mutable sets.
|
|
|
|
.. class:: Mapping
|
|
MutableMapping
|
|
|
|
ABCs for read-only and mutable :term:`mappings <mapping>`.
|
|
|
|
.. class:: MappingView
|
|
ItemsView
|
|
KeysView
|
|
ValuesView
|
|
|
|
ABCs for mapping, items, keys, and values :term:`views <view>`.
|
|
|
|
|
|
These ABCs allow us to ask classes or instances if they provide
|
|
particular functionality, for example::
|
|
|
|
size = None
|
|
if isinstance(myvar, collections.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 :class:`Set` API, it only necessary to supply the three underlying
|
|
abstract methods: :meth:`__contains__`, :meth:`__iter__`, and :meth:`__len__`.
|
|
The ABC supplies the remaining methods such as :meth:`__and__` and
|
|
:meth:`isdisjoint` ::
|
|
|
|
class ListBasedSet(collections.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 :class:`Set` and :class:`MutableSet` as a mixin:
|
|
|
|
(1)
|
|
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
|
|
:meth:`_from_iterable` which calls ``cls(iterable)`` to produce a new set.
|
|
If the :class:`Set` mixin is being used in a class with a different
|
|
constructor signature, you will need to override :meth:`_from_iterable`
|
|
with a classmethod that can construct new instances from
|
|
an iterable argument.
|
|
|
|
(2)
|
|
To override the comparisons (presumably for speed, as the
|
|
semantics are fixed), redefine :meth:`__le__` and
|
|
then the other operations will automatically follow suit.
|
|
|
|
(3)
|
|
The :class:`Set` mixin provides a :meth:`_hash` method to compute a hash value
|
|
for the set; however, :meth:`__hash__` is not defined because not all sets
|
|
are hashable or immutable. To add set hashabilty using mixins,
|
|
inherit from both :meth:`Set` and :meth:`Hashable`, then define
|
|
``__hash__ = Set._hash``.
|
|
|
|
.. seealso::
|
|
|
|
* `OrderedSet recipe <http://code.activestate.com/recipes/576694/>`_ for an
|
|
example built on :class:`MutableSet`.
|
|
|
|
* For more about ABCs, see the :mod:`abc` module and :pep:`3119`.
|