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

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, 2 months 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 The abc module 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 ...
155 @classmethod 157 @classmethod
156 @abstractmethod 158 @abstractmethod
157 def my_abstract_method(self, ...): 159 def my_abstract_classmethod(cls, ...):
gvanrossum 2011/11/29 04:29:43 my_abstract_classmethod
158 ... 160 ...
159 @staticmethod 161 @staticmethod
160 @abstractmethod 162 @abstractmethod
161 def my_abstract_method(self, ...): 163 def my_abstract_staticmethod(...):
gvanrossum 2011/11/29 04:29:43 my_abstract_staticmethod
162 ... 164 ...
163 165
164 @property 166 @property
165 @abstractmethod 167 @abstractmethod
166 def my_abstract_property(self): 168 def my_abstract_property(self):
167 ... 169 ...
168 @my_abstract_property.setter 170 @my_abstract_property.setter
169 @abstractmethod 171 @abstractmethod
170 def my_abstract_property(self, val): 172 def my_abstract_property(self, val):
171 ... 173 ...
172 174
173 @abstractmethod 175 @abstractmethod
174 def _get_x(self): 176 def _get_x(self):
175 ... 177 ...
176 @abstractmethod 178 @abstractmethod
177 def _set_x(self, val): 179 def _set_x(self, val):
178 ... 180 ...
179 x = property(_get_x, _set_x) 181 x = property(_get_x, _set_x)
180 182
181 183 In order to correctly interoperate with the abstract base class machinery,
182 .. note:: 184 the descriptor must identify itself as abstract using
Benjamin Peterson 2011/11/29 02:45:54 I don't think this should be in a note section.
183 185 :attr:`__isabstractmethod__`. In general, this attribute should be ``True``
184 In order to include abc support for custom descriptors, the descriptor 186 if any of the methods used to compose the descriptor are abstract. For
185 must identify itself as abstract using :attr:`__isabstractmethod__`. For 187 example, Python's built-in property does the equivalent of::
186 example, Python's built-in property does the equivalent of:: 188
187 189 class Descriptor:
188 class Descriptor: 190 ...
189 » ... 191 @property
190 @property 192 def __isabstractmethod__(self):
191 def __isabstractmethod__(self): 193 » return any(getattr(f, '__isabstractmethod__', False) for
192 for f in (self._fget, self._fset, self._fdel): 194 f in (self._fget, self._fset, self._fdel))
193 is_abstract = getattr(f, '__isabstractmethod__', False)
194 if is_abstract: return True
Benjamin Peterson 2011/11/29 02:45:54 Split this into two lines. You probably don't even
195 return False
196 195
197 .. note:: 196 .. note::
198 197
199 Unlike Java abstract methods, these abstract 198 Unlike Java abstract methods, these abstract
200 methods may have an implementation. This implementation can be 199 methods may have an implementation. This implementation can be
201 called via the :func:`super` mechanism from the class that 200 called via the :func:`super` mechanism from the class that
202 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
203 super-call in a framework that uses cooperative 202 super-call in a framework that uses cooperative
204 multiple-inheritance. 203 multiple-inheritance.
205 204
206 205
207 .. decorator:: abstractclassmethod(function) 206 .. decorator:: abstractclassmethod(function)
208 207
208 A subclass of the built-in :func:`classmethod`, indicating an abstract
209 classmethod. Otherwise it is similar to :func:`abstractmethod`.
210
211 Usage::
212
213 class C(metaclass=ABCMeta):
214 @abstractclassmethod
215 def my_abstract_classmethod(cls, ...):
216 ...
217
218 .. versionadded:: 3.2
209 .. deprecated:: 3.3 219 .. deprecated:: 3.3
210 Use :class:`classmethod` and :func:`abstractmethod` instead 220 Use :class:`classmethod` with :func:`abstractmethod` instead
211 221
212 222
213 .. decorator:: abstractstaticmethod(function) 223 .. decorator:: abstractstaticmethod(function)
214 224
225 A subclass of the built-in :func:`staticmethod`, indicating an abstract
226 staticmethod. Otherwise it is similar to :func:`abstractmethod`.
227
228 Usage::
229
230 class C(metaclass=ABCMeta):
231 @abstractstaticmethod
232 def my_abstract_staticmethod(...):
233 ...
234
235 .. versionadded:: 3.2
215 .. deprecated:: 3.3 236 .. deprecated:: 3.3
216 Use :class:`staticmethod` and :func:`abstractmethod` instead 237 Use :class:`staticmethod` with :func:`abstractmethod` instead
217 238
218 239
219 .. function:: abstractproperty(fget=None, fset=None, fdel=None, doc=None) 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)
220 264
221 .. deprecated:: 3.3 265 .. deprecated:: 3.3
222 Use :class:`property` and :func:`abstractmethod` instead 266 Use :class:`property` with :func:`abstractmethod` instead
223 267
224 268
225 .. rubric:: Footnotes 269 .. rubric:: Footnotes
226 270
227 .. [#] C++ programmers should note that Python's virtual base class 271 .. [#] C++ programmers should note that Python's virtual base class
228 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+