Docstrings and class Attributes

[Nick]

Is it possible to put a doc string on a class attribute? Something
like this

class Test (object):
'''classx'''

fred = 10
'''attribute'''

print Test.__doc__
print Test.fred.__doc__

This code produces this output

classx
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 base is zero, the proper base is guessed based on the
string content. If the argument is outside the integer range a
long object will be returned instead.

===========

So the class doc string is return, but no doc string for the
attribute.

 

[Eric Snow]

Is it possible to put a doc string on a class attribute? Something
like this

You can put a docstring on a property (which is a function):

class Test(object):
@property
def fred(self):
"attribute"
return 10

Python syntax supports implicitly building docstrings only for
modules, class definitions, and function definitions.

-eric

class Test (object):
   '''classx'''

   fred = 10
   '''attribute'''

print Test.__doc__
print Test.fred.__doc__

This code produces this output

classx
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 base is zero, the proper base is guessed based on the
string content.  If the argument is outside the integer range a
long object will be returned instead.

===========

So the class doc string is return, but no doc string for the
attribute.

 

[Terry Reedy]

Is it possible to put a doc string on a class attribute?

Class and function docstrings are generated from string expression
statements at the beginning of a suite.

class Test (object):
'''classx'''

fred = 10
'''attribute'''

This is two statements that have no particular connection with each other.

print Test.__doc__
print Test.fred.__doc__

This code produces this output

classx
int(x[, base]) -> integer

....
If an instance does not have a requested attribute, it is looked up on
its class (and superclasses). Since all classes are subclasses of object
and that has a docstring, I guess everything will.

 

[Steven D'Aprano]

You can put a docstring on a property (which is a function):

class Test(object):
@property
def fred(self):
"attribute"
return 10

Which, however, doesn't really help:
'int(x[, base]) -> integer\n\nConvert a string or number to an integer ...'


The problem is that t.fred returns an integer, so t.fred.__doc__ returns the
docstring from the integer, not for the property.
'attribute'

 

[Steven D'Aprano]

Is it possible to put a doc string on a class attribute? Something
like this

class Test (object):
'''classx'''
fred = 10
'''attribute'''

The short answer is, no.

The longer answer is, maybe, if you can make Test.fred be some sort of
object with a docstring:

class MyInt(int):
'''attribute'''

class Test(object):
'''classx'''
fred = MyInt(10)

'attribute'


But the hard part is ensuring that Test.fred doesn't get replaced:
'int(x[, base]) -> integer\n\nConvert a string or number ...'


Not impossible to solve, but an awful lot of trouble for very little
benefit. Just put your documentation in the class, where people expect to
find it:

class Test(object):
'''classx

Test.fred is an attribute.
'''
fred = 10

 

[Terry Reedy]

This really makes little sense. The purpose of docstrings is to give
interactive help. The place to document data attributes of a class is in
the class docstring. The value of an int is considered to be
self-explanatory.

You can put a docstring on a property (which is a function):

class Test(object):
@property
def fred(self):
"attribute"
return 10

Which, however, doesn't really help:
'int(x[, base]) -> integer\n\nConvert a string or number to an integer ...'


The problem is that t.fred returns an integer, so t.fred.__doc__ returns the
docstring from the integer, not for the property.
'attribute'

Which is to say, the descriptor protocol allows custom get, set, and
delete methods, but not an attribute-specific getattribute method ;-).

 

[Ethan Furman]

You can put a docstring on a property (which is a function):

class Test(object):
@property
def fred(self):
"attribute"
return 10

Which, however, doesn't really help:

--> t = Test()
--> t.fred.__doc__
'int(x[, base]) -> integer\n\nConvert a string or number to an integer ...'


The problem is that t.fred returns an integer, so t.fred.__doc__ returns the
docstring from the integer, not for the property.

--> t.__class__.fred.__doc__
'attribute'

So if property docstrings are so hard to get to, what's the point in
having them?

~Ethan~

 

[Steven D'Aprano]

So if property docstrings are so hard to get to, what's the point in
having them?

Hard to get, not impossible. But I have no idea really -- they don't seem
very useful to me.

 

[Eric Snow]

Hard to get, not impossible. But I have no idea really -- they don't seem
very useful to me.

They do show up in help(), but not as some sort of data-attribute docstring.

-eric

 

[Steven D'Aprano]

Why would you expect there be a special point to them?

Men, like all primates of any sex, have nipples.

Properties, like any function in Python, have docstrings.

They're an accident of the history that led to their implementation, and
of the pre-existing parts that they're built from. There doesn't need to
be a point to them (though they might be useful for reasons incidental
for the reasons they exist).

But properties *aren't* functions, they are objects which obey the
descriptor protocol. Perhaps you are thinking of the individual getter,
setter and deleter parameters to property(). If so, then your comment is
relevant as far as it goes to the docstrings on the individual
getter/setter/deleter functions. But property() itself explicitly takes a
docstring parameter. It is that docstring that seems of limited value,
except that Eric Snow has pointed out that help(instance) will display
property help strings.

 

[John Pinner]

Why would you expect there be a special point to them?

Men, like all primates of any sex, have nipples.

Properties, like any function in Python, have docstrings.

So are you saying that men's nipples are pointless?

You could be correct, except in cold weather maybe.

John
--

 

[Steven D'Aprano]

So are you saying that men's nipples are pointless?

You could be correct, except in cold weather maybe.

Groan.

However, off-topic but interesting, there is at least one species of bat
where the males are known to routinely lactate and feed baby bats.

http://en.wikipedia.org/wiki/Male_lactation

So just because a feature is an accident of history, doesn't mean that a use
can't be found for it.