← Back to branch summary

~ubuntu-branches/ubuntu/maverick/python3.1/maverick

« back to all changes in this revision

Viewing changes to Doc/library/abc.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-03-23 00:01:27 UTC
  • Revision ID: james.westby@ubuntu.com-20090323000127-5fstfxju4ufrhthq
Tags: upstream-3.1~a1+20090322
Import upstream version 3.1~a1+20090322

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/library/abc.rst
 
1
 
 
2
:mod:`abc` --- Abstract Base Classes
 
3
====================================
 
4
 
 
5
.. module:: abc
 
6
   :synopsis: Abstract base classes according to PEP 3119.
 
7
.. moduleauthor:: Guido van Rossum
 
8
.. sectionauthor:: Georg Brandl
 
9
.. much of the content adapted from docstrings
 
10
 
 
11
This module provides the infrastructure for defining an :term:`abstract base
 
12
class` (ABCs) in Python, as outlined in :pep:`3119`; see the PEP for why this
 
13
was added to Python. (See also :pep:`3141` and the :mod:`numbers` module
 
14
regarding a type hierarchy for numbers based on ABCs.)
 
15
 
 
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.
 
21
 
 
22
 
 
23
This module provides the following class:
 
24
 
 
25
.. class:: ABCMeta
 
26
 
 
27
   Metaclass for defining Abstract Base Classes (ABCs).
 
28
 
 
29
   Use this metaclass to create an ABC.  An ABC can be subclassed directly, and
 
30
   then acts as a mix-in class.  You can also register unrelated concrete
 
31
   classes (even built-in classes) and unrelated ABCs as "virtual subclasses" --
 
32
   these and their descendants will be considered subclasses of the registering
 
33
   ABC by the built-in :func:`issubclass` function, but the registering ABC
 
34
   won't show up in their MRO (Method Resolution Order) nor will method
 
35
   implementations defined by the registering ABC be callable (not even via
 
36
   :func:`super`). [#]_
 
37
 
 
38
   Classes created with a metaclass of :class:`ABCMeta` have the following method:
 
39
 
 
40
   .. method:: register(subclass)
 
41
 
 
42
      Register *subclass* as a "virtual subclass" of this ABC. For
 
43
      example::
 
44
 
 
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)
 
54
 
 
55
   You can also override this method in an abstract base class:
 
56
 
 
57
   .. method:: __subclasshook__(subclass)
 
58
 
 
59
      (Must be defined as a class method.)
 
60
 
 
61
      Check whether *subclass* is considered a subclass of this ABC.  This means
 
62
      that you can customize the behavior of ``issubclass`` further without the
 
63
      need to call :meth:`register` on every class you want to consider a
 
64
      subclass of the ABC.  (This class method is called from the
 
65
      :meth:`__subclasscheck__` method of the ABC.)
 
66
 
 
67
      This method should return ``True``, ``False`` or ``NotImplemented``.  If
 
68
      it returns ``True``, the *subclass* is considered a subclass of this ABC.
 
69
      If it returns ``False``, the *subclass* is not considered a subclass of
 
70
      this ABC, even if it would normally be one.  If it returns
 
71
      ``NotImplemented``, the subclass check is continued with the usual
 
72
      mechanism.
 
73
 
 
74
      .. XXX explain the "usual mechanism"
 
75
 
 
76
 
 
77
   For a demonstration of these concepts, look at this example ABC definition::
 
78
 
 
79
      class Foo:
 
80
          def __getitem__(self, index):
 
81
              ...
 
82
          def __len__(self):
 
83
              ...
 
84
          def get_iterator(self):
 
85
              return iter(self)
 
86
 
 
87
      class MyIterable(metaclass=ABCMeta):
 
88
 
 
89
          @abstractmethod
 
90
          def __iter__(self):
 
91
              while False:
 
92
                  yield None
 
93
 
 
94
          def get_iterator(self):
 
95
              return self.__iter__()
 
96
 
 
97
          @classmethod
 
98
          def __subclasshook__(cls, C):
 
99
              if cls is MyIterable:
 
100
                  if any("__iter__" in B.__dict__ for B in C.__mro__):
 
101
                      return True
 
102
              return NotImplemented
 
103
 
 
104
      MyIterable.register(Foo)
 
105
 
 
106
   The ABC ``MyIterable`` defines the standard iterable method,
 
107
   :meth:`__iter__`, as an abstract method.  The implementation given here can
 
108
   still be called from subclasses.  The :meth:`get_iterator` method is also
 
109
   part of the ``MyIterable`` abstract base class, but it does not have to be
 
110
   overridden in non-abstract derived classes.
 
111
 
 
112
   The :meth:`__subclasshook__` class method defined here says that any class
 
113
   that has an :meth:`__iter__` method in its :attr:`__dict__` (or in that of
 
114
   one of its base classes, accessed via the :attr:`__mro__` list) is
 
115
   considered a ``MyIterable`` too.
 
116
 
 
117
   Finally, the last line makes ``Foo`` a virtual subclass of ``MyIterable``,
 
118
   even though it does not define an :meth:`__iter__` method (it uses the
 
119
   old-style iterable protocol, defined in terms of :meth:`__len__` and
 
120
   :meth:`__getitem__`).  Note that this will not make ``get_iterator``
 
121
   available as a method of ``Foo``, so it is provided separately.
 
122
 
 
123
 
 
124
It also provides the following decorators:
 
125
 
 
126
.. function:: abstractmethod(function)
 
127
 
 
128
   A decorator indicating abstract methods.
 
129
 
 
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.
 
135
   The abstract methods can be called using any of the the normal 'super' call
 
136
   mechanisms.
 
137
 
 
138
   Dynamically adding abstract methods to a class, or attempting to modify the
 
139
   abstraction status of a method or class once it is created, are not
 
140
   supported.  The :func:`abstractmethod` only affects subclasses derived using
 
141
   regular inheritance; "virtual subclasses" registered with the ABC's
 
142
   :meth:`register` method are not affected.
 
143
 
 
144
   Usage::
 
145
 
 
146
      class C(metaclass=ABCMeta):
 
147
          @abstractmethod
 
148
          def my_abstract_method(self, ...):
 
149
              ...
 
150
 
 
151
   .. note::
 
152
 
 
153
      Unlike 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.
 
159
 
 
160
 
 
161
.. function:: abstractproperty(fget[, fset[, fdel[, doc]]])
 
162
 
 
163
   A subclass of the built-in :func:`property`, indicating an abstract property.
 
164
 
 
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.
 
171
 
 
172
   Usage::
 
173
 
 
174
      class C(metaclass=ABCMeta):
 
175
          @abstractproperty
 
176
          def my_abstract_property(self):
 
177
              ...
 
178
 
 
179
   This defines a read-only property; you can also define a read-write abstract
 
180
   property using the 'long' form of property declaration::
 
181
 
 
182
      class C(metaclass=ABCMeta):
 
183
          def getx(self): ...
 
184
          def setx(self, value): ...
 
185
          x = abstractproperty(getx, setx)
 
186
 
 
187
.. rubric:: Footnotes
 
188
 
 
189
.. [#] C++ programmers should note that Python's virtual base class
 
190
   concept is not the same as C++'s.