[docs] documentation bug

Andreas Balogh andreas.balogh at db.com
Mon Jan 30 09:01:06 CET 2012

Classification: Public


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 
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 
Deutsche Bank AG | Große Gallusstraße 10-14 | 60311 Frankfurt am Main | 
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

Andreas Balogh <andreas.balogh at db.com>
docs at python.org
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> 
>    @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.

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>

More information about the docs mailing list