Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(4)

Delta Between Two Patch Sets: Doc/library/abc.rst

Issue 11610: Improving property to accept abstract methods
Left Patch Set: Created 8 years, 7 months ago
Right Patch Set: Created 8 years, 1 month ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
Left: Side by side diff | Download
Right: Side by side diff | Download
« no previous file with change/comment | « no previous file | Doc/whatsnew/3.3.rst » ('j') | no next file with change/comment »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
LEFTRIGHT
1 :mod:`abc` --- Abstract Base Classes 1 :mod:`abc` --- Abstract Base Classes
2 ==================================== 2 ====================================
3 3
4 .. module:: abc 4 .. module:: abc
5 :synopsis: Abstract base classes according to PEP 3119. 5 :synopsis: Abstract base classes according to PEP 3119.
6 .. moduleauthor:: Guido van Rossum 6 .. moduleauthor:: Guido van Rossum
7 .. sectionauthor:: Georg Brandl 7 .. sectionauthor:: Georg Brandl
8 .. much of the content adapted from docstrings 8 .. much of the content adapted from docstrings
9 9
10 **Source code:** :source:`Lib/abc.py` 10 **Source code:** :source:`Lib/abc.py`
11 11
12 -------------- 12 --------------
13 13
14 This module provides the infrastructure for defining an :term:`abstract base 14 This module provides the infrastructure for defining :term:`abstract base
15 class` (ABC) in Python, as outlined in :pep:`3119`; see the PEP for why this 15 classes <abstract base class>` (ABCs) in Python, as outlined in :pep:`3119`; see the PEP for why this
16 was added to Python. (See also :pep:`3141` and the :mod:`numbers` module 16 was added to Python. (See also :pep:`3141` and the :mod:`numbers` module
17 regarding a type hierarchy for numbers based on ABCs.) 17 regarding a type hierarchy for numbers based on ABCs.)
18 18
19 The :mod:`collections` module has some concrete classes that derive from 19 The :mod:`collections` module has some concrete classes that derive from
20 ABCs; these can, of course, be further derived. In addition the 20 ABCs; these can, of course, be further derived. In addition the
21 :mod:`collections.abc` submodule has some ABCs that can be used to test whether 21 :mod:`collections.abc` submodule has some ABCs that can be used to test whether
22 a class or instance provides a particular interface, for example, is it 22 a class or instance provides a particular interface, for example, is it
23 hashable or a mapping. 23 hashable or a mapping.
24 24
25 25
(...skipping 94 matching lines...) Expand 10 before | Expand all | Expand 10 after
120 one of its base classes, accessed via the :attr:`__mro__` list) is 120 one of its base classes, accessed via the :attr:`__mro__` list) is
121 considered a ``MyIterable`` too. 121 considered a ``MyIterable`` too.
122 122
123 Finally, the last line makes ``Foo`` a virtual subclass of ``MyIterable``, 123 Finally, the last line makes ``Foo`` a virtual subclass of ``MyIterable``,
124 even though it does not define an :meth:`__iter__` method (it uses the 124 even though it does not define an :meth:`__iter__` method (it uses the
125 old-style iterable protocol, defined in terms of :meth:`__len__` and 125 old-style iterable protocol, defined in terms of :meth:`__len__` and
126 :meth:`__getitem__`). Note that this will not make ``get_iterator`` 126 :meth:`__getitem__`). Note that this will not make ``get_iterator``
127 available as a method of ``Foo``, so it is provided separately. 127 available as a method of ``Foo``, so it is provided separately.
128 128
129 129
130 It also provides the following decorators: 130 The :mod:`abc` module also provides the following decorators:
131 131
132 .. decorator:: abstractmethod(function) 132 .. decorator:: abstractmethod(function)
133 133
134 A decorator indicating abstract methods. 134 A decorator indicating abstract methods.
135 135
136 Using this decorator requires that the class's metaclass is :class:`ABCMeta` 136 Using this decorator requires that the class's metaclass is :class:`ABCMeta`
137 or is derived from it. A class that has a metaclass derived from 137 or is derived from it. A class that has a metaclass derived from
138 :class:`ABCMeta` cannot be instantiated unless all of its abstract methods 138 :class:`ABCMeta` cannot be instantiated unless all of its abstract methods
139 and properties are overridden. The abstract methods can be called using any 139 and properties are overridden. The abstract methods can be called using any
140 of the normal 'super' call mechanisms. :func:`abstractmethod` may be used 140 of the normal 'super' call mechanisms. :func:`abstractmethod` may be used
141 to declare abstract methods for properties and descriptors. 141 to declare abstract methods for properties and descriptors.
142 142
143 Dynamically adding abstract methods to a class, or attempting to modify the 143 Dynamically adding abstract methods to a class, or attempting to modify the
144 abstraction status of a method or class once it is created, are not 144 abstraction status of a method or class once it is created, are not
145 supported. The :func:`abstractmethod` only affects subclasses derived using 145 supported. The :func:`abstractmethod` only affects subclasses derived using
146 regular inheritance; "virtual subclasses" registered with the ABC's 146 regular inheritance; "virtual subclasses" registered with the ABC's
147 :meth:`register` method are not affected. 147 :meth:`register` method are not affected.
148 148
149 Usage:: 149 When :func:`abstractmethod` is applied in combination with other method
150 descriptors, it should be applied as the innermost decorator, as shown in
151 the following usage examples::
150 152
151 class C(metaclass=ABCMeta): 153 class C(metaclass=ABCMeta):
152 @abstractmethod 154 @abstractmethod
153 def my_abstract_method(self, ...): 155 def my_abstract_method(self, ...):
154 ... 156 ...
157 @classmethod
158 @abstractmethod
159 def my_abstract_classmethod(cls, ...):
160 ...
161 @staticmethod
162 @abstractmethod
163 def my_abstract_staticmethod(...):
164 ...
155 165
156 @property 166 @property
157 @abstractmethod 167 @abstractmethod
158 def my_abstract_property(self): 168 def my_abstract_property(self):
159 ... 169 ...
160 @my_abstract_property.setter 170 @my_abstract_property.setter
161 @abstractmethod 171 @abstractmethod
162 def my_abstract_property(self, val): 172 def my_abstract_property(self, val):
163 ... 173 ...
164 174
165 @abstractmethod 175 @abstractmethod
166 def _get_x(self): 176 def _get_x(self):
167 ... 177 ...
168 @abstractmethod 178 @abstractmethod
169 def _set_x(self, val): 179 def _set_x(self, val):
170 ... 180 ...
171 x = property(_get_x, _set_x) 181 x = property(_get_x, _set_x)
172 182
183 In order to correctly interoperate with the abstract base class machinery,
184 the descriptor must identify itself as abstract using
185 :attr:`__isabstractmethod__`. In general, this attribute should be ``True``
186 if any of the methods used to compose the descriptor are abstract. For
187 example, Python's built-in property does the equivalent of::
188
189 class Descriptor:
190 ...
191 @property
192 def __isabstractmethod__(self):
193 return any(getattr(f, '__isabstractmethod__', False) for
194 f in (self._fget, self._fset, self._fdel))
173 195
174 .. note:: 196 .. note::
175 197
176 Unlike Java abstract methods, these abstract 198 Unlike Java abstract methods, these abstract
177 methods may have an implementation. This implementation can be 199 methods may have an implementation. This implementation can be
178 called via the :func:`super` mechanism from the class that 200 called via the :func:`super` mechanism from the class that
179 overrides it. This could be useful as an end-point for a 201 overrides it. This could be useful as an end-point for a
180 super-call in a framework that uses cooperative 202 super-call in a framework that uses cooperative
181 multiple-inheritance. 203 multiple-inheritance.
182 204
183 205
184 .. decorator:: abstractclassmethod(function) 206 .. decorator:: abstractclassmethod(function)
185 207
186 A subclass of the built-in :func:`classmethod`, indicating an abstract 208 A subclass of the built-in :func:`classmethod`, indicating an abstract
187 classmethod. Otherwise it is similar to :func:`abstractmethod`. 209 classmethod. Otherwise it is similar to :func:`abstractmethod`.
188 210
189 Usage:: 211 Usage::
190 212
191 class C(metaclass=ABCMeta): 213 class C(metaclass=ABCMeta):
192 @abstractclassmethod 214 @abstractclassmethod
193 def my_abstract_classmethod(cls, ...): 215 def my_abstract_classmethod(cls, ...):
194 ... 216 ...
195 217
196 .. versionadded:: 3.2 218 .. versionadded:: 3.2
219 .. deprecated:: 3.3
220 Use :class:`classmethod` with :func:`abstractmethod` instead
197 221
198 222
199 .. decorator:: abstractstaticmethod(function) 223 .. decorator:: abstractstaticmethod(function)
200 224
201 A subclass of the built-in :func:`staticmethod`, indicating an abstract 225 A subclass of the built-in :func:`staticmethod`, indicating an abstract
202 staticmethod. Otherwise it is similar to :func:`abstractmethod`. 226 staticmethod. Otherwise it is similar to :func:`abstractmethod`.
203 227
204 Usage:: 228 Usage::
205 229
206 class C(metaclass=ABCMeta): 230 class C(metaclass=ABCMeta):
207 @abstractstaticmethod 231 @abstractstaticmethod
208 def my_abstract_staticmethod(...): 232 def my_abstract_staticmethod(...):
209 ... 233 ...
210 234
211 .. versionadded:: 3.2 235 .. versionadded:: 3.2
212
213
214 .. function:: abstractproperty(fget=None, fset=None, fdel=None, doc=None)
215
216 .. deprecated:: 3.3 236 .. deprecated:: 3.3
217 Use :class:`property` and :func:`abstractmethod` instead 237 Use :class:`staticmethod` with :func:`abstractmethod` instead
238
239
240 .. decorator:: abstractproperty(fget=None, fset=None, fdel=None, doc=None)
241
242 A subclass of the built-in :func:`property`, indicating an abstract property.
243
244 Using this function requires that the class's metaclass is :class:`ABCMeta`
245 or is derived from it. A class that has a metaclass derived from
246 :class:`ABCMeta` cannot be instantiated unless all of its abstract methods
247 and properties are overridden. The abstract properties can be called using
248 any of the normal 'super' call mechanisms.
249
250 Usage::
251
252 class C(metaclass=ABCMeta):
253 @abstractproperty
254 def my_abstract_property(self):
255 ...
256
257 This defines a read-only property; you can also define a read-write abstract
258 property using the 'long' form of property declaration::
259
260 class C(metaclass=ABCMeta):
261 def getx(self): ...
262 def setx(self, value): ...
263 x = abstractproperty(getx, setx)
264
265 .. deprecated:: 3.3
266 Use :class:`property` with :func:`abstractmethod` instead
218 267
219 268
220 .. rubric:: Footnotes 269 .. rubric:: Footnotes
221 270
222 .. [#] C++ programmers should note that Python's virtual base class 271 .. [#] C++ programmers should note that Python's virtual base class
223 concept is not the same as C++'s. 272 concept is not the same as C++'s.
LEFTRIGHT

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+