[docs] documentation bug

[Andreas Balogh]

Classification: Public

Hello,

thanks for your feedback. Let me further explain why I think the doc is 
unclear to me here. Maybe I am missing something.

A little bit earlier documentation mentions:

"This makes it possible to create read-only properties easily using 
property() as a decorator: "

implying property to be the key to creating a read-only property.

In conjunction with: "A property object has getter, setter, and deleter 
methods usable as decorators that create a copy of the property with the 
corresponding accessor function set to the decorated function. This is 
best explained with an example: "

The description implies the decorator for a getter to be @x.getter and not 
@property.
I am of the impression that property() would only be used for creating 
read-only properties while x.getter, x.setter, x.deleter decorators create 
read-writable properties.
It is unclear here when a read-only property is created and when a 
read-write property is created.

Then "This code is exactly equivalent to the first example." is not true. 
The second example is about a read-write property while the first example 
is about a read-only property. It contains two additional methods. Just 
remove the sentence.

IMHO what should be explicitely mentioned is 
1. why symmetry is broken for @property vs @propertyname.setter and 
@propertyname.deleter, and
2. how python determines to create a read-only or a read-write property 
(is it just the existence of setter and deleter decorators/methods?)

Regards, Andreas

______________________________________________________________________________

Andreas Balogh 
Domain Manager
Global Technology Capital Markets | Business Solutions | Global Markets 
Equity
Deutsche Bank AG | Große Gallusstraße 10-14 | 60311 Frankfurt am Main | 
Germany
Tel: +49 69 910 39518 | Fax : +49 69 910 32260
______________________________________________________________________________





Sandro Tosi <sandro.tosi at gmail.com> 
Sent by: matrixhasu at gmail.com
28.01.2012 19:44

To
Andreas Balogh <andreas.balogh at db.com>
cc
docs at python.org
Subject
Re: [docs] documentation bug






Hello Andreas,
thanks for your email.

On Thu, Jan 26, 2012 at 15:28, Andreas Balogh <andreas.balogh at db.com> 
wrote:
>    @property
>    def x(self):
>        """I'm the 'x' property."""
>        return self._x
...
> should read correctly
...
>    @x.getter
>    def x(self):
>        """I'm the 'x' property."""
>        return self._x

I'm not exactly sure that the example is incorrect, the writer might
have wanted to recall the property decorator of the example above
instead of using the getter decorator.

Regards,
-- 
Sandro Tosi (aka morph, morpheus, matrixhasu)
My website: http://matrixhasu.altervista.org/
Me at Debian: http://wiki.debian.org/SandroTosi



-- 

Informationen (einschließlich Pflichtangaben) zu einzelnen, innerhalb der EU tätigen Gesellschaften und Zweigniederlassungen des Konzerns Deutsche Bank finden Sie unter http://www.deutsche-bank.de/de/content/pflichtangaben.htm. Diese E-Mail enthält vertrauliche und/ oder rechtlich geschützte Informationen. Wenn Sie nicht der richtige Adressat sind oder diese E-Mail irrtümlich erhalten haben, informieren Sie bitte sofort den Absender und vernichten Sie diese E-Mail. Das unerlaubte Kopieren sowie die unbefugte Weitergabe dieser E-Mail ist nicht gestattet.

Please refer to http://www.db.com/en/content/eu_disclosures.htm for information (including mandatory corporate particulars) on selected Deutsche Bank branches and group companies registered or incorporated in the European Union. This e-mail may contain confidential and/or privileged information. If you are not the intended recipient (or have received this e-mail in error) please notify the sender immediately and delete this e-mail. Any unauthorized copying, disclosure or distribution of the material in this e-mail is strictly forbidden.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20120130/0412b0ec/attachment.html>