From 575ee4c4c7641bb574b28b12e64308c3fd697e48 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Sun, 10 Aug 2014 10:44:21 -0700 Subject: [PATCH] Issue #22174: Clean-up grammar and ambiguities in property() docs. --- Doc/library/functions.rst | 20 +++++++++++++------- Misc/ACKS | 1 + 2 files changed, 14 insertions(+), 7 deletions(-) diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 0667ec53f3..f2e6b6c37d 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -992,9 +992,11 @@ available. They are listed here in alphabetical order. Return a property attribute for :term:`new-style class`\es (classes that derive from :class:`object`). - *fget* is a function for getting an attribute value, likewise *fset* is a - function for setting, and *fdel* a function for del'ing, an attribute. Typical - use is to define a managed attribute ``x``:: + *fget* is a function for getting an attribute value. *fset* is a function + for setting an attribute value. *fdel* is a function for deleting an attribute + value. And *doc* creates a docstring for the attribute. + + A typical use is to define a managed attribute ``x``:: class C(object): def __init__(self): @@ -1002,13 +1004,16 @@ available. They are listed here in alphabetical order. def getx(self): return self._x + def setx(self, value): self._x = value + def delx(self): del self._x + x = property(getx, setx, delx, "I'm the 'x' property.") - If then *c* is an instance of *C*, ``c.x`` will invoke the getter, + If *c* is an instance of *C*, ``c.x`` will invoke the getter, ``c.x = value`` will invoke the setter and ``del c.x`` the deleter. If given, *doc* will be the docstring of the property attribute. Otherwise, the @@ -1024,8 +1029,9 @@ available. They are listed here in alphabetical order. """Get the current voltage.""" return self._voltage - turns the :meth:`voltage` method into a "getter" for a read-only attribute - with the same name. + The ``@property`` decorator turns the :meth:`voltage` method into a "getter" + for a read-only attribute with the same name, and it sets the docstring for + *voltage* to "Get the current voltage." A property object has :attr:`~property.getter`, :attr:`~property.setter`, and :attr:`~property.deleter` methods usable as decorators that create a @@ -1053,7 +1059,7 @@ available. They are listed here in alphabetical order. additional functions the same name as the original property (``x`` in this case.) - The returned property also has the attributes ``fget``, ``fset``, and + The returned property object also has the attributes ``fget``, ``fset``, and ``fdel`` corresponding to the constructor arguments. .. versionadded:: 2.2 diff --git a/Misc/ACKS b/Misc/ACKS index a5e9b4e757..4ebe074824 100644 --- a/Misc/ACKS +++ b/Misc/ACKS @@ -245,6 +245,7 @@ David Cinege Craig Citro Gilles Civario Chris Clark +Diana Clarke Laurie Clark-Michalek Mike Clarkson Andrew Clegg -- 2.50.1