how to document a property

[TP]

Hi everybody,

I know how to document a function or a method, with a docstring (see below
for "foo" method documentation ("bar")).
But, how to document a property (below, self.d)?

#######################
class a():
def __init__( self ):
self.d = 2
def foo( self ):
"bar"

b=a()
print dir(b)
methods = [ el for el in dir( b ) ]
for meth in methods:
if hasattr( getattr( b, meth ), "__doc__" ):
print meth, " :\n", getattr( b, meth ).__doc__
#######################

When I execute this script, I obtain for self.d:

#######################
[...]
__module__ :
str(object) -> string

Return a nice string representation of the object.
If the argument is a string, the return value is the same object.

d :
int(x[, base]) -> integer

Convert a string or number to an integer, if possible. A floating point
argument will be truncated towards zero (this does not include a string
representation of a floating point number!) When converting a string, use
the optional base. It is an error to supply a base when converting a
non-string. If the argument is outside the integer range a long object
will be returned instead.
[...]
#######################

What is this default documentation?
Why?

Thanks

Julien
--
python -c "print ''.join([chr(154 - ord(c)) for c in '*9(9&(18%.9&1+,\'Z
(55l4('])"

"When a distinguished but elderly scientist states that something is
possible, he is almost certainly right. When he states that something is
impossible, he is very probably wrong." (first law of AC Clarke)

 

[Luis Zarrabeitia]

d :
int(x[, base]) -> integer

Convert a string or number to an integer, if possible. A floating point
argument will be truncated towards zero (this does not include a string
representation of a floating point number!) When converting a string, use
the optional base. It is an error to supply a base when converting a
non-string. If the argument is outside the integer range a long object
will be returned instead.
[...]
#######################

What is this default documentation?
Why?

What you are reading is not the 'default documentation', but the documentation
for the 'int' type. Do help(5) and watch the result.

The problem is that when you do help(yourobj.d) you are not asking for the help
of the attribute named 'd' in yourobj. You are asking for the help of the object
that the attribute named 'd' is bound to at that point.

The same happens when you access help(yourobj.somefunction), with the only
difference that in that particular case, you have a chance to specify a
documentation for 'somefunction' and you are unlikely to change "somefunction"'s
binding at runtime.

So if you need to do something like:

[warning: syntax is not valid]

class A(object):
age = 0 "stores the age of the person" #invalid syntax warning
def blablah(self): pass

a = A()
help(a.age)
a.age=7
help(a.age)

and always get "stores the age of the person", I don't think python has any
syntactical way of doing that. You could simulate it using properties, though
(do a 'help(property)' to see an example), but I'm not sure if that will be a
good solution.