Proof read/editing of abc. Added table of collections.Hashable etc. to

Mark Summerfield · Mark Summerfield · commit 08898b4b19a0 · 2007-09-05T08:43:04.000Z
collections with some brief notes.
diff --git a/Doc/library/abc.rst b/Doc/library/abc.rst
@@ -9,13 +9,18 @@
 .. much of the content adapted from docstrings
 
 This module provides the infrastructure for defining abstract base classes
-(ABCs) in Python, as outlined in :pep:`3119`; see there for a rationale why this
-was added to Python.
+(ABCs) in Python, as outlined in :pep:`3119`; see the PEP for why this
+was added to Python. (See also, :pep:`3141` regarding a type hierarchy
+for numbers based on ABCs.)
 
-Concrete base ABCs to derive from can be found in the :mod:`collections` module.
+The :mod:`collections` module has some concrete classes that derive from
+ABCs; these can, of course, be further derived. In addition the
+:mod:`collections` module has some ABCs that can be used to test whether
+a class or instance provides a particular interface, for example, is it
+hashable or a mapping.
 
 
-The module provides the following class:
+This module provides the following class:
 
 .. class:: ABCMeta
 
@@ -28,15 +33,24 @@ The module provides the following class:
    ABC by the built-in :func:`issubclass` function, but the registering ABC
    won't show up in their MRO (Method Resolution Order) nor will method
    implementations defined by the registering ABC be callable (not even via
-   :func:`super`).
+   :func:`super`). [#]_
 
    Classes created with a metaclass of :class:`ABCMeta` have the following method:
 
    .. method:: register(subclass)
 
-      Register *subclass* as a "virtual subclass" of this ABC.  From now on,
-      ``issubclass(subclass, ABC)`` is true.
+      Register *subclass* as a "virtual subclass" of this ABC. For
+      example::
 
+	from abc import ABCMeta
+
+	class MyABC(metaclass=ABCMeta):
+	    pass
+
+	MyABC.register(tuple)
+
+	assert issubclass(tuple, MyABC)
+	assert isinstance((), MyABC)
 
    You can also override this method in an abstract base class:
 
@@ -93,15 +107,15 @@ The module provides the following class:
    :meth:`__iter__`, as an abstract method.  The implementation given here can
    still be called from subclasses.  The :meth:`get_iterator` method is also
    part of the ``MyIterable`` abstract base class, but it does not have to be
-   overridden in a non-abstract child.
+   overridden in non-abstract derived classes.
 
    The :meth:`__subclasshook__` class method defined here says that any class
    that has an :meth:`__iter__` method in its :attr:`__dict__` (or in that of
-   one of its subclasses, accessed via the :attr:`__mro__`) is considered a
-   ``MyIterable`` too.
+   one of its base classes, accessed via the :attr:`__mro__` list) is
+   considered a ``MyIterable`` too.
 
    Finally, the last line makes ``Foo`` a virtual subclass of ``MyIterable``,
-   even though it does not define a :meth:`__iter__` method (it uses the
+   even though it does not define an :meth:`__iter__` method (it uses the
    old-style iterable protocol, defined in terms of :meth:`__len__` and
    :meth:`__getitem__`).  Note that this will not make ``get_iterator``
    available as a method of ``Foo``, so it is provided separately.
@@ -113,9 +127,11 @@ It also provides the following decorators:
 
    A decorator indicating abstract methods.
 
-   Using this decorator requires that the metaclass is :class:`ABCMeta` or
-   derived from it.  A class that has a metaclass derived from :class:`ABCMeta`
-   cannot be instantiated unless all of its abstract methods are overridden.
+   Using this decorator requires that the class's metaclass is :class:`ABCMeta` or
+   is derived from it. 
+   A class that has a metaclass derived from :class:`ABCMeta`
+   cannot be instantiated unless all of its abstract methods and
+   properties are overridden.
    The abstract methods can be called using any of the the normal 'super' call
    mechanisms.
 
@@ -134,20 +150,24 @@ It also provides the following decorators:
 
    .. note::
 
-      Unlike C++ or Java, these abstract methods may have an implementation.
-      This implementation can be called via the :func:`super` mechanism from the
-      class that overrides it.  This could be useful as an end-point for a
-      super-call in framework using a cooperative multiple-inheritance
+      Unlike C++'s pure virtual functions, or Java abstract methods, these abstract
+      methods may have an implementation. This implementation can be
+      called via the :func:`super` mechanism from the class that
+      overrides it.  This could be useful as an end-point for a
+      super-call in a framework that uses cooperative
+      multiple-inheritance.
 
 
 .. function:: abstractproperty(fget[, fset[, fdel[, doc]]])
 
    A subclass of the built-in :func:`property`, indicating an abstract property.
 
-   Requires that the metaclass is :class:`ABCMeta` or derived from it.  A class
-   that has a metaclass derived from :class:`ABCMeta` cannot be instantiated
-   unless all of its abstract properties are overridden.  The abstract
-   properties can be called using any of the the normal 'super' call mechanisms.
+   Using this function requires that the class's metaclass is :class:`ABCMeta` or
+   is derived from it. 
+   A class that has a metaclass derived from :class:`ABCMeta` cannot be
+   instantiated unless all of its abstract methods and properties are overridden.
+   The abstract properties can be called using any of the normal
+   'super' call mechanisms.
 
    Usage::
 
@@ -164,3 +184,7 @@ It also provides the following decorators:
           def setx(self, value): ...
           x = abstractproperty(getx, setx)
 
+.. rubric:: Footnotes
+
+.. [#] C++ programmers should note that Python's virtual base class
+   concept is not the same as C++'s.
diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
@@ -19,6 +19,55 @@ or file based ordered dictionaries with string keys.
 Future editions of the standard library may include balanced trees and
 ordered dictionaries.
 
+In addition to containers, the collections module provides some ABCs
+(abstract base classes) that can be used to test whether
+a class provides a particular interface, for example, is it hashable or
+a mapping. The ABCs provided include those in the following table:
+
+=====================================  ========================================
+ABC                                    Notes
+=====================================  ========================================
+:class:`collections.Container`         Defines ``__contains__()``
+:class:`collections.Hashable`          Defines ``__hash__()``
+:class:`collections.Iterable`          Defines ``__iter__()``
+:class:`collections.Iterator`          Derived from :class:`Iterable` and in
+                                       addition defines ``__next__()``
+:class:`collections.Mapping`           Derived from :class:`Container`,
+                                       :class:`Iterable`,
+                                       and :class:`Sized`, and in addition
+                                       defines ``__getitem__()``, ``get()``,
+                                       ``__contains__()``, ``__len__()``,
+                                       ``__iter__()``, ``keys()``,
+                                       ``items()``, and ``values()``
+:class:`collections.MutableMapping`    Derived from :class:`Mapping`
+:class:`collections.MutableSequence`   Derived from :class:`Sequence`
+:class:`collections.MutableSet`        Derived from :class:`Set` and in
+                                       addition defines ``add()``,
+                                       ``clear()``, ``discard()``, ``pop()``,
+                                       and ``toggle()``
+:class:`collections.Sequence`          Derived from :class:`Container`,
+                                       :class:`Iterable`, and :class:`Sized`,
+                                       and in addition defines
+                                       ``__getitem__()``
+:class:`collections.Set`               Derived from :class:`Container`, :class:`Iterable`, and :class:`Sized`
+:class:`collections.Sized`             Defines ``__len__()``
+=====================================  ========================================
+
+.. XXX Have not included them all and the notes are imcomplete
+.. Deliberately did one row wide to get a neater output
+
+These ABCs allow us to ask classes or instances if they provide
+particular functionality, for example::
+
+    from collections import Sized
+
+    size = None
+    if isinstance(myvar, Sized):
+	size = len(myvar)
+
+(For more about ABCs, see the :mod:`abc` module and :pep:`3119`.)
+
+
 
 .. _deque-objects:
 
