Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 08898b4

Browse files
author
Mark Summerfield
committed
Proof read/editing of abc. Added table of collections.Hashable etc. to
collections with some brief notes.
1 parent fd4a7de commit 08898b4

2 files changed

Lines changed: 95 additions & 22 deletions

File tree

Doc/library/abc.rst

Lines changed: 46 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -9,13 +9,18 @@
99
.. much of the content adapted from docstrings
1010
1111
This module provides the infrastructure for defining abstract base classes
12-
(ABCs) in Python, as outlined in :pep:`3119`; see there for a rationale why this
13-
was added to Python.
12+
(ABCs) in Python, as outlined in :pep:`3119`; see the PEP for why this
13+
was added to Python. (See also, :pep:`3141` regarding a type hierarchy
14+
for numbers based on ABCs.)
1415

15-
Concrete base ABCs to derive from can be found in the :mod:`collections` module.
16+
The :mod:`collections` module has some concrete classes that derive from
17+
ABCs; these can, of course, be further derived. In addition the
18+
:mod:`collections` module has some ABCs that can be used to test whether
19+
a class or instance provides a particular interface, for example, is it
20+
hashable or a mapping.
1621

1722

18-
The module provides the following class:
23+
This module provides the following class:
1924

2025
.. class:: ABCMeta
2126

@@ -28,15 +33,24 @@ The module provides the following class:
2833
ABC by the built-in :func:`issubclass` function, but the registering ABC
2934
won't show up in their MRO (Method Resolution Order) nor will method
3035
implementations defined by the registering ABC be callable (not even via
31-
:func:`super`).
36+
:func:`super`). [#]_
3237

3338
Classes created with a metaclass of :class:`ABCMeta` have the following method:
3439

3540
.. method:: register(subclass)
3641

37-
Register *subclass* as a "virtual subclass" of this ABC. From now on,
38-
``issubclass(subclass, ABC)`` is true.
42+
Register *subclass* as a "virtual subclass" of this ABC. For
43+
example::
3944

45+
from abc import ABCMeta
46+
47+
class MyABC(metaclass=ABCMeta):
48+
pass
49+
50+
MyABC.register(tuple)
51+
52+
assert issubclass(tuple, MyABC)
53+
assert isinstance((), MyABC)
4054

4155
You can also override this method in an abstract base class:
4256

@@ -93,15 +107,15 @@ The module provides the following class:
93107
:meth:`__iter__`, as an abstract method. The implementation given here can
94108
still be called from subclasses. The :meth:`get_iterator` method is also
95109
part of the ``MyIterable`` abstract base class, but it does not have to be
96-
overridden in a non-abstract child.
110+
overridden in non-abstract derived classes.
97111

98112
The :meth:`__subclasshook__` class method defined here says that any class
99113
that has an :meth:`__iter__` method in its :attr:`__dict__` (or in that of
100-
one of its subclasses, accessed via the :attr:`__mro__`) is considered a
101-
``MyIterable`` too.
114+
one of its base classes, accessed via the :attr:`__mro__` list) is
115+
considered a ``MyIterable`` too.
102116

103117
Finally, the last line makes ``Foo`` a virtual subclass of ``MyIterable``,
104-
even though it does not define a :meth:`__iter__` method (it uses the
118+
even though it does not define an :meth:`__iter__` method (it uses the
105119
old-style iterable protocol, defined in terms of :meth:`__len__` and
106120
:meth:`__getitem__`). Note that this will not make ``get_iterator``
107121
available as a method of ``Foo``, so it is provided separately.
@@ -113,9 +127,11 @@ It also provides the following decorators:
113127

114128
A decorator indicating abstract methods.
115129

116-
Using this decorator requires that the metaclass is :class:`ABCMeta` or
117-
derived from it. A class that has a metaclass derived from :class:`ABCMeta`
118-
cannot be instantiated unless all of its abstract methods are overridden.
130+
Using this decorator requires that the class's metaclass is :class:`ABCMeta` or
131+
is derived from it.
132+
A class that has a metaclass derived from :class:`ABCMeta`
133+
cannot be instantiated unless all of its abstract methods and
134+
properties are overridden.
119135
The abstract methods can be called using any of the the normal 'super' call
120136
mechanisms.
121137

@@ -134,20 +150,24 @@ It also provides the following decorators:
134150

135151
.. note::
136152

137-
Unlike C++ or Java, these abstract methods may have an implementation.
138-
This implementation can be called via the :func:`super` mechanism from the
139-
class that overrides it. This could be useful as an end-point for a
140-
super-call in framework using a cooperative multiple-inheritance
153+
Unlike C++'s pure virtual functions, or Java abstract methods, these abstract
154+
methods may have an implementation. This implementation can be
155+
called via the :func:`super` mechanism from the class that
156+
overrides it. This could be useful as an end-point for a
157+
super-call in a framework that uses cooperative
158+
multiple-inheritance.
141159

142160

143161
.. function:: abstractproperty(fget[, fset[, fdel[, doc]]])
144162

145163
A subclass of the built-in :func:`property`, indicating an abstract property.
146164

147-
Requires that the metaclass is :class:`ABCMeta` or derived from it. A class
148-
that has a metaclass derived from :class:`ABCMeta` cannot be instantiated
149-
unless all of its abstract properties are overridden. The abstract
150-
properties can be called using any of the the normal 'super' call mechanisms.
165+
Using this function requires that the class's metaclass is :class:`ABCMeta` or
166+
is derived from it.
167+
A class that has a metaclass derived from :class:`ABCMeta` cannot be
168+
instantiated unless all of its abstract methods and properties are overridden.
169+
The abstract properties can be called using any of the normal
170+
'super' call mechanisms.
151171

152172
Usage::
153173

@@ -164,3 +184,7 @@ It also provides the following decorators:
164184
def setx(self, value): ...
165185
x = abstractproperty(getx, setx)
166186

187+
.. rubric:: Footnotes
188+
189+
.. [#] C++ programmers should note that Python's virtual base class
190+
concept is not the same as C++'s.

Doc/library/collections.rst

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,55 @@ or file based ordered dictionaries with string keys.
1919
Future editions of the standard library may include balanced trees and
2020
ordered dictionaries.
2121

22+
In addition to containers, the collections module provides some ABCs
23+
(abstract base classes) that can be used to test whether
24+
a class provides a particular interface, for example, is it hashable or
25+
a mapping. The ABCs provided include those in the following table:
26+
27+
===================================== ========================================
28+
ABC Notes
29+
===================================== ========================================
30+
:class:`collections.Container` Defines ``__contains__()``
31+
:class:`collections.Hashable` Defines ``__hash__()``
32+
:class:`collections.Iterable` Defines ``__iter__()``
33+
:class:`collections.Iterator` Derived from :class:`Iterable` and in
34+
addition defines ``__next__()``
35+
:class:`collections.Mapping` Derived from :class:`Container`,
36+
:class:`Iterable`,
37+
and :class:`Sized`, and in addition
38+
defines ``__getitem__()``, ``get()``,
39+
``__contains__()``, ``__len__()``,
40+
``__iter__()``, ``keys()``,
41+
``items()``, and ``values()``
42+
:class:`collections.MutableMapping` Derived from :class:`Mapping`
43+
:class:`collections.MutableSequence` Derived from :class:`Sequence`
44+
:class:`collections.MutableSet` Derived from :class:`Set` and in
45+
addition defines ``add()``,
46+
``clear()``, ``discard()``, ``pop()``,
47+
and ``toggle()``
48+
:class:`collections.Sequence` Derived from :class:`Container`,
49+
:class:`Iterable`, and :class:`Sized`,
50+
and in addition defines
51+
``__getitem__()``
52+
:class:`collections.Set` Derived from :class:`Container`, :class:`Iterable`, and :class:`Sized`
53+
:class:`collections.Sized` Defines ``__len__()``
54+
===================================== ========================================
55+
56+
.. XXX Have not included them all and the notes are imcomplete
57+
.. Deliberately did one row wide to get a neater output
58+
59+
These ABCs allow us to ask classes or instances if they provide
60+
particular functionality, for example::
61+
62+
from collections import Sized
63+
64+
size = None
65+
if isinstance(myvar, Sized):
66+
size = len(myvar)
67+
68+
(For more about ABCs, see the :mod:`abc` module and :pep:`3119`.)
69+
70+
2271

2372
.. _deque-objects:
2473

0 commit comments

Comments
 (0)