From ac191ce1d38ba7f9c16b6486685abe1afc39c2ea Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Sun, 10 Aug 2014 10:41:25 -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 7c382e986f..2a89ce451e 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -1106,9 +1106,11 @@ are always available. They are listed here in alphabetical order. Return a property attribute. - *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: def __init__(self): @@ -1116,13 +1118,16 @@ are always 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 @@ -1138,8 +1143,9 @@ are always 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 @@ -1167,7 +1173,7 @@ are always 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. diff --git a/Misc/ACKS b/Misc/ACKS index 08ca65f7ab..2c58324725 100644 --- a/Misc/ACKS +++ b/Misc/ACKS @@ -248,6 +248,7 @@ David Cinege Craig Citro Gilles Civario Chris Clark +Diana Clarke Laurie Clark-Michalek Mike Clarkson Andrew Clegg -- 2.40.0