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

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') | Doc/whatsnew/3.3.rst » ('J')
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 abc module also provides the following decorators:
Nick Coghlan 2011/12/06 09:14:01 :mod:`abc`
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 Usage::
Nick Coghlan 2011/12/06 09:14:01 I would expand on this paragraph to say something
151 150
152 class C(metaclass=ABCMeta): 151 class C(metaclass=ABCMeta):
153 @abstractmethod 152 @abstractmethod
154 def my_abstract_method(self, ...): 153 def my_abstract_method(self, ...):
155 ... 154 ...
155 @classmethod
156 @abstractmethod
157 def my_abstract_classmethod(self, ...):
Nick Coghlan 2011/12/06 09:14:01 For a class method, use 'cls' as first argument, n
158 ...
159 @staticmethod
160 @abstractmethod
161 def my_abstract_staticmethod(self, ...):
162 ...
Nick Coghlan 2011/12/06 09:14:01 There's no 'self' argument to a static method
163
164 @property
165 @abstractmethod
166 def my_abstract_property(self):
167 ...
168 @my_abstract_property.setter
169 @abstractmethod
170 def my_abstract_property(self, val):
171 ...
172
173 @abstractmethod
174 def _get_x(self):
175 ...
176 @abstractmethod
177 def _set_x(self, val):
178 ...
179 x = property(_get_x, _set_x)
180
181
182 In order to include abc support for custom descriptors, the descriptor
183 must identify itself as abstract using :attr:`__isabstractmethod__`. For
184 example, Python's built-in property does the equivalent of::
Nick Coghlan 2011/12/06 09:14:01 Change this paragraph to something like: "In order
dsdale24 2011/12/06 15:00:25 The implementation doesn't propagate the value of
dsdale24 2011/12/06 17:07:35 How about: In order to correctly interoperate
185
186 class Descriptor:
187 ...
188 @property
189 def __isabstractmethod__(self):
190 for f in (self._fget, self._fset, self._fdel):
191 if getattr(f, '__isabstractmethod__', False):
192 return True
193 return False
156 194
Nick Coghlan 2011/12/06 09:14:01 Replace the body of the property implementation wi
157 .. note:: 195 .. note::
158 196
159 Unlike Java abstract methods, these abstract 197 Unlike Java abstract methods, these abstract
160 methods may have an implementation. This implementation can be 198 methods may have an implementation. This implementation can be
161 called via the :func:`super` mechanism from the class that 199 called via the :func:`super` mechanism from the class that
162 overrides it. This could be useful as an end-point for a 200 overrides it. This could be useful as an end-point for a
163 super-call in a framework that uses cooperative 201 super-call in a framework that uses cooperative
164 multiple-inheritance. 202 multiple-inheritance.
165 203
166 204
167 .. decorator:: abstractclassmethod(function) 205 .. decorator:: abstractclassmethod(function)
168 206
169 A subclass of the built-in :func:`classmethod`, indicating an abstract 207 .. deprecated:: 3.3
170 classmethod. Otherwise it is similar to :func:`abstractmethod`. 208 Use :class:`classmethod` with :func:`abstractmethod` instead
Nick Coghlan 2011/12/06 09:14:01 Don't delete the documentation - this function wil
dsdale24 2011/12/06 17:07:35 Should the deprecation warning go at the beginning
171
172 Usage::
173
174 class C(metaclass=ABCMeta):
175 @abstractclassmethod
176 def my_abstract_classmethod(cls, ...):
177 ...
178
179 .. versionadded:: 3.2
180 209
181 210
182 .. decorator:: abstractstaticmethod(function) 211 .. decorator:: abstractstaticmethod(function)
183 212
184 A subclass of the built-in :func:`staticmethod`, indicating an abstract 213 .. deprecated:: 3.3
185 staticmethod. Otherwise it is similar to :func:`abstractmethod`. 214 Use :class:`staticmethod` with :func:`abstractmethod` instead
Nick Coghlan 2011/12/06 09:14:01 As above
186
187 Usage::
188
189 class C(metaclass=ABCMeta):
190 @abstractstaticmethod
191 def my_abstract_staticmethod(...):
192 ...
193
194 .. versionadded:: 3.2
195 215
196 216
197 .. decorator:: abstractproperty(fget=None, fset=None, fdel=None, doc=None) 217 .. decorator:: abstractproperty(fget=None, fset=None, fdel=None, doc=None)
198 218
199 A subclass of the built-in :func:`property`, indicating an abstract property. 219 .. deprecated:: 3.3
200 220 Use :class:`property` with :func:`abstractmethod` instead
Nick Coghlan 2011/12/06 09:14:01 As above.
201 Using this function requires that the class's metaclass is :class:`ABCMeta` o r
202 is derived from it.
203 A class that has a metaclass derived from :class:`ABCMeta` cannot be
204 instantiated unless all of its abstract methods and properties are overridden .
205 The abstract properties can be called using any of the normal
206 'super' call mechanisms.
207
208 Usage::
209
210 class C(metaclass=ABCMeta):
211 @abstractproperty
212 def my_abstract_property(self):
213 ...
214
215 This defines a read-only property; you can also define a read-write abstract
216 property using the 'long' form of property declaration::
217
218 class C(metaclass=ABCMeta):
219 def getx(self): ...
220 def setx(self, value): ...
221 x = abstractproperty(getx, setx)
222 221
223 222
224 .. rubric:: Footnotes 223 .. rubric:: Footnotes
225 224
226 .. [#] C++ programmers should note that Python's virtual base class 225 .. [#] C++ programmers should note that Python's virtual base class
227 concept is not the same as C++'s. 226 concept is not the same as C++'s.
OLDNEW
« no previous file with comments | « no previous file | Doc/whatsnew/3.3.rst » ('j') | Doc/whatsnew/3.3.rst » ('J')

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