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

Side by Side Diff: Doc/library/abc.rst

Issue 11610: Improving property to accept abstract methods
Patch Set: Created 8 years 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:
View unified diff | Download patch
« no previous file with comments | « no previous file | Doc/whatsnew/3.3.rst » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
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`
(...skipping 109 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` or 136 Using this decorator requires that the class's metaclass is :class:`ABCMeta`
137 is derived from it. 137 or is derived from it. A class that has a metaclass derived from
138 A class that has a metaclass derived from :class:`ABCMeta` 138 :class:`ABCMeta` cannot be instantiated unless all of its abstract methods
139 cannot be instantiated unless all of its abstract methods and 139 and properties are overridden. The abstract methods can be called using any
140 properties are overridden. 140 of the normal 'super' call mechanisms. :func:`abstractmethod` may be used
141 The abstract methods can be called using any of the normal 'super' call 141 to declare abstract methods for properties and descriptors.
142 mechanisms.
143 142
144 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
145 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
146 supported. The :func:`abstractmethod` only affects subclasses derived using 145 supported. The :func:`abstractmethod` only affects subclasses derived using
147 regular inheritance; "virtual subclasses" registered with the ABC's 146 regular inheritance; "virtual subclasses" registered with the ABC's
148 :meth:`register` method are not affected. 147 :meth:`register` method are not affected.
149 148
150 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::
151 152
152 class C(metaclass=ABCMeta): 153 class C(metaclass=ABCMeta):
153 @abstractmethod 154 @abstractmethod
154 def my_abstract_method(self, ...): 155 def my_abstract_method(self, ...):
155 ... 156 ...
157 @classmethod
158 @abstractmethod
159 def my_abstract_classmethod(cls, ...):
160 ...
161 @staticmethod
162 @abstractmethod
163 def my_abstract_staticmethod(...):
164 ...
165
166 @property
167 @abstractmethod
168 def my_abstract_property(self):
169 ...
170 @my_abstract_property.setter
171 @abstractmethod
172 def my_abstract_property(self, val):
173 ...
174
175 @abstractmethod
176 def _get_x(self):
177 ...
178 @abstractmethod
179 def _set_x(self, val):
180 ...
181 x = property(_get_x, _set_x)
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))
156 195
157 .. note:: 196 .. note::
158 197
159 Unlike Java abstract methods, these abstract 198 Unlike Java abstract methods, these abstract
160 methods may have an implementation. This implementation can be 199 methods may have an implementation. This implementation can be
161 called via the :func:`super` mechanism from the class that 200 called via the :func:`super` mechanism from the class that
162 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
163 super-call in a framework that uses cooperative 202 super-call in a framework that uses cooperative
164 multiple-inheritance. 203 multiple-inheritance.
165 204
166 205
167 .. decorator:: abstractclassmethod(function) 206 .. decorator:: abstractclassmethod(function)
168 207
169 A subclass of the built-in :func:`classmethod`, indicating an abstract 208 A subclass of the built-in :func:`classmethod`, indicating an abstract
170 classmethod. Otherwise it is similar to :func:`abstractmethod`. 209 classmethod. Otherwise it is similar to :func:`abstractmethod`.
171 210
172 Usage:: 211 Usage::
173 212
174 class C(metaclass=ABCMeta): 213 class C(metaclass=ABCMeta):
175 @abstractclassmethod 214 @abstractclassmethod
176 def my_abstract_classmethod(cls, ...): 215 def my_abstract_classmethod(cls, ...):
177 ... 216 ...
178 217
179 .. versionadded:: 3.2 218 .. versionadded:: 3.2
219 .. deprecated:: 3.3
220 Use :class:`classmethod` with :func:`abstractmethod` instead
180 221
181 222
182 .. decorator:: abstractstaticmethod(function) 223 .. decorator:: abstractstaticmethod(function)
183 224
184 A subclass of the built-in :func:`staticmethod`, indicating an abstract 225 A subclass of the built-in :func:`staticmethod`, indicating an abstract
185 staticmethod. Otherwise it is similar to :func:`abstractmethod`. 226 staticmethod. Otherwise it is similar to :func:`abstractmethod`.
186 227
187 Usage:: 228 Usage::
188 229
189 class C(metaclass=ABCMeta): 230 class C(metaclass=ABCMeta):
190 @abstractstaticmethod 231 @abstractstaticmethod
191 def my_abstract_staticmethod(...): 232 def my_abstract_staticmethod(...):
192 ... 233 ...
193 234
194 .. versionadded:: 3.2 235 .. versionadded:: 3.2
236 .. deprecated:: 3.3
237 Use :class:`staticmethod` with :func:`abstractmethod` instead
195 238
196 239
197 .. decorator:: abstractproperty(fget=None, fset=None, fdel=None, doc=None) 240 .. decorator:: abstractproperty(fget=None, fset=None, fdel=None, doc=None)
198 241
199 A subclass of the built-in :func:`property`, indicating an abstract property. 242 A subclass of the built-in :func:`property`, indicating an abstract property.
200 243
201 Using this function requires that the class's metaclass is :class:`ABCMeta` o r 244 Using this function requires that the class's metaclass is :class:`ABCMeta`
202 is derived from it. 245 or is derived from it. A class that has a metaclass derived from
203 A class that has a metaclass derived from :class:`ABCMeta` cannot be 246 :class:`ABCMeta` cannot be instantiated unless all of its abstract methods
204 instantiated unless all of its abstract methods and properties are overridden . 247 and properties are overridden. The abstract properties can be called using
205 The abstract properties can be called using any of the normal 248 any of the normal 'super' call mechanisms.
206 'super' call mechanisms.
207 249
208 Usage:: 250 Usage::
209 251
210 class C(metaclass=ABCMeta): 252 class C(metaclass=ABCMeta):
211 @abstractproperty 253 @abstractproperty
212 def my_abstract_property(self): 254 def my_abstract_property(self):
213 ... 255 ...
214 256
215 This defines a read-only property; you can also define a read-write abstract 257 This defines a read-only property; you can also define a read-write abstract
216 property using the 'long' form of property declaration:: 258 property using the 'long' form of property declaration::
217 259
218 class C(metaclass=ABCMeta): 260 class C(metaclass=ABCMeta):
219 def getx(self): ... 261 def getx(self): ...
220 def setx(self, value): ... 262 def setx(self, value): ...
221 x = abstractproperty(getx, setx) 263 x = abstractproperty(getx, setx)
264
265 .. deprecated:: 3.3
266 Use :class:`property` with :func:`abstractmethod` instead
222 267
223 268
224 .. rubric:: Footnotes 269 .. rubric:: Footnotes
225 270
226 .. [#] C++ programmers should note that Python's virtual base class 271 .. [#] C++ programmers should note that Python's virtual base class
227 concept is not the same as C++'s. 272 concept is not the same as C++'s.
OLDNEW
« no previous file with comments | « no previous file | Doc/whatsnew/3.3.rst » ('j') | no next file with comments »

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