classification
Title: property doc fixes
Type: Stage: resolved
Components: Documentation Versions: Python 3.4, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: diana, docs@python, python-dev, r.david.murray, rhettinger
Priority: normal Keywords: patch

Created on 2014-08-08 20:48 by diana, last changed 2014-08-10 17:47 by rhettinger. This issue is now closed.

Files
File name Uploaded Description Edit
property_docs.patch diana, 2014-08-08 20:48 review
Screen Shot 2014-08-08 at 4.44.07 PM.png diana, 2014-08-08 20:50 Screen Shot of the property docs after
property2.diff rhettinger, 2014-08-10 09:22 Highlight the implicit creation of the docstring review
Messages (7)
msg225086 - (view) Author: diana (diana) * Date: 2014-08-08 20:48
The property docs are a bit funky.

    https://docs.python.org/3/library/functions.html#property

1) docstrings have zero to do with making a read-only property. It currently says:

"If given, doc will be the docstring of the property attribute. Otherwise, the property will copy fget‘s docstring (if it exists). This makes it possible to create read-only properties easily using property() as a decorator:"

2) The 'then' in this sentence is awkward (and incorrect English).

"If then 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."

3) This sentence is missing a beginning.

"turns the voltage() method into a “getter” for a read-only attribute with the same name."

4) This sentence has an extra comma (after del'ing):

"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."

Attached is a patch with minimal changes to the property docs, addressing the above four issues. Okay, that's not entirely true -- I did add an example usage because the current docs don't actually show using a property attribute.

>>> p = Parrot()
>>> p.voltage
100000

I've also attached an "after" screenshot of the docs in case it helps with review.

Cheers,

--diana
msg225090 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-08-08 22:05
The docstring discussion is correct in the context.  property can easily be used to create a read only property because when used as a decorator the function that follows the decorator call is passed to it as fget, *and it copies the docstring from the function into the created property*.

The 'then' is indeed redundant (if kept should properly be set of by commas, but there is no reason to keep it).

'turns the voltage' is still part of the previous sentence.  Read it as "create read-only properties easily using property() as a decorator as follows...[this example] turns the voltage() method into a..."  Your reformulation is, however, clearer.

The comma in the 'fget is a function' sentence is in the correct place.  "and fdel a function for del'ing" is phrase...I forget the formal name for the type of phrase.  It's analogous to the structure of this sentence: "She forgot to bring not only her lunch, but also her wallet, to work".  However, the comma after 'value' should technically be a semicolon.  Although correct, I think the whole sentence would read better if it instead said "fget is a function for getting an attribute value, fset is a function for setting an attribute value, and fdel is a function for del'ing an attribute."
msg225124 - (view) Author: diana (diana) * Date: 2014-08-10 05:17
This whitespace? Or did you mean something else?

      class C:
          def __init__(self):
              self._x = None

          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.")

versus:

      class C:
          def __init__(self):
              self._x = None

          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.")

I added it to be consistent with the rest of the code snippets in the property docs. For example:

      class C:
          def __init__(self):
              self._x = None

          @property
          def x(self):
              """I'm the 'x' property."""
              return self._x

          @x.setter
          def x(self, value):
              self._x = value

          @x.deleter
          def x(self):
              del self._x

Of the three code snippets in the property docs, that first one is the only one that doesn't have whitespace between the methods. That first code snippet also has inconsistent whitespace within itself (__init__ vs the rest of methods).

Anyhoo, that was my reasoning, but that's largely beside the point. I will happily drop it and leave it as-is. What really prompted me to submit a patch was this paragraph:

"If given, doc will be the docstring of the property attribute. Otherwise, the property will copy fget‘s docstring (if it exists). This makes it possible to create read-only properties easily using property() as a decorator:"

I now understand the original intent, but I don't think it's clear as-is. 

I also find it a bit odd that 'fget', 'fset', 'fdel' are all defined in the first sentence of the docs, but 'doc' isn't. It then launches into an example that uses 'doc' (still as of yet undefined), before defining 'doc' later on in the read-only properties part.

I'll think on it a bit some more -- feel free to close this in the mean time. It's been this way for a better part of a decade, so perhaps it's just me ;)

Cheers,

--diana
msg225131 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2014-08-10 09:22
Most of the patch looks to be an improvement.  I've massaged it a little and attached a revised patch.
msg225150 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-08-10 17:41
New changeset ebd6f7f7859f by Raymond Hettinger in branch '3.4':
Issue #22174:  Clean-up grammar and ambiguities in property() docs.
http://hg.python.org/cpython/rev/ebd6f7f7859f
msg225151 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-08-10 17:44
New changeset 98a2e215ff01 by Raymond Hettinger in branch '2.7':
Issue #22174:  Clean-up grammar and ambiguities in property() docs.
http://hg.python.org/cpython/rev/98a2e215ff01
msg225152 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2014-08-10 17:47
Diana, thank you for the patch. Sorry for the bogus comment on whitespace.  I was looking the the docstring at the same time as reviewing the patch.

David, thanks for looking at it as well.
History
Date User Action Args
2014-08-10 17:47:09rhettingersetstatus: open -> closed
versions: + Python 2.7, Python 3.4
messages: + msg225152

resolution: fixed
stage: resolved
2014-08-10 17:44:27python-devsetmessages: + msg225151
2014-08-10 17:41:59python-devsetnosy: + python-dev
messages: + msg225150
2014-08-10 09:22:51rhettingersetfiles: + property2.diff

messages: + msg225131
2014-08-10 08:44:12rhettingersetmessages: - msg225123
2014-08-10 05:17:07dianasetmessages: + msg225124
2014-08-10 03:12:03rhettingersetassignee: docs@python -> rhettinger

messages: + msg225123
nosy: + rhettinger
2014-08-08 22:05:53r.david.murraysetnosy: + r.david.murray
messages: + msg225090
2014-08-08 20:50:16dianasetfiles: + Screen Shot 2014-08-08 at 4.44.07 PM.png
2014-08-08 20:48:59dianacreate