[issue22174] property doc fixes

[Raymond Hettinger]

Raymond Hettinger added the comment:

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.

--
resolution:  -> fixed
stage:  -> resolved
status: open -> closed
versions: +Python 2.7, Python 3.4

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue22174] property doc fixes

[Roundup Robot]

Roundup Robot added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue22174] property doc fixes

[Roundup Robot]

Roundup Robot added the comment:

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

--
nosy: +python-dev

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue22174] property doc fixes

[Raymond Hettinger]

Raymond Hettinger added the comment:

Most of the patch looks to be an improvement.  I've massaged it a little and 
attached a revised patch.

--
Added file: http://bugs.python.org/file36332/property2.diff

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue22174] property doc fixes

[Raymond Hettinger]

Changes by Raymond Hettinger :


--
Removed message: http://bugs.python.org/msg225123

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue22174] property doc fixes

[diana]

diana added the comment:

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

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue22174] property doc fixes

[Raymond Hettinger]

Raymond Hettinger added the comment:

Also, please don't add the extra whitespace to the docstring.  It is 
intentionally compact because of the differing needs of various IDEs and help 
utlities.

--
assignee: docs@python -> rhettinger
nosy: +rhettinger

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue22174] property doc fixes

[R. David Murray]

R. David Murray added the comment:

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

--
nosy: +r.david.murray

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue22174] property doc fixes

[diana]

Changes by diana :


Added file: http://bugs.python.org/file36319/Screen Shot 2014-08-08 at 4.44.07 
PM.png

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue22174] property doc fixes

[diana]

New submission from diana:

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
10

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

Cheers,

--diana

--
assignee: docs@python
components: Documentation
files: property_docs.patch
keywords: patch
messages: 225086
nosy: diana, docs@python
priority: normal
severity: normal
status: open
title: property doc fixes
versions: Python 3.5
Added file: http://bugs.python.org/file36318/property_docs.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com