[docs] Documentation bug in 'property' function

[Julien Palard]

Hi Fred, thanks for reporting this clearly!

First, please remember everything, literally everything in Python is an object. So an attribute is an object, but an int is an object:

>>> (42).__class__
<class 'int'>

a class is an object (so yes, a class is an instance of type):

>>> class Foo: pass
...
>>> Foo.__class__
<class 'type'>

A function is an object, and so on, and so on.

So yes, we could use "object" literally everywhere in the documentation, but it won't help the reader a lot.

I bet what "Return a property attribute" means is that the returned value is meant to be used as an attribute of a class. (It's obvisouly an object, everything is an object, it's not worth mentionning). Which may not be obvious at first as it's documented in a "list of functions" page (not correlated with the documentation of classes).

Then, a question could be: How that object can work as an attribute of the class? How this property object survives someone affecting the attribute where's it's stored?

The answer is that the returned object implements the descriptor protocol, see https://docs.python.org/3/howto/descriptor.html, and the machinery for the affectation calling the property methods "instead of replacing the property object" is implemented in object.__getattribute__(), I mean this *only* works when the returned object is used as an attribute. A bit of a long sentense to say "it works only when it's an attribute".

So it's useless when not an attribute. So let's call it an attribute?

Bests,
--
Julien Palard
https://mdk.fr