Best way to do attribute docstrings?

[Gabriel Genellina]

En Fri, 07 Sep 2007 17:06:07 -0300, Ken Kuhlman <kskuhlman at gmail.com>  
escribi�:

> What's the best method for annotating attributes with a docstring?
> I'm looking to be able to introspect my class & get the comments back
> out.

I don't know which is the *best* method. Perhaps you might use properties  
instead. Or some kind of convention, like
	four_legs__doc__ = "Animal has four legs"
to be the docstring associate to `four_legs` attribute.

> The technique I'm using is a little hoaky, but works.. basically I
> create subclasses of the builtin types that I want to be able to use &
> then instantiate them in my attribute assignments.   This gives me an
> object that I can tweak the __doc__ attribute on.   An example of what
> my code looks like is included below.

I don't like subclassing builtins, it doesn't work in general. _("Hello")  
+ _(" world!") is a plain str object, not your derived class.
What about instance attributes? All your examples show class attributes.  
Your docstring appears to be attached to the attribute "value", but it  
should be attached to the attribute definition, or be a class attribute,  
or something like that, shared between all instances and somewhat  
permanent. Else, reassigning the attribute will lose the docstring.

> # Boolean gave me extra fits that I don't understand, but this
> technique works
> class MyBool(int):
>     def __str__(self):
>         return `self.__int__() > 0`
>     def __repr__(self):
>         return self.__str__()

Let Python do the boolean conversion: -1 is a true value, but MyBool(-1)  
would say False.
I don't understand exactly why do you want this class, but I'd write it  
this way:

class MyBool(int):
     def __str__(self):
         return str(bool(self))
     __repr__ = __str__

> def bool_func(val):
>     def blah():
>        return MyBool(val)
>     return blah
> true = bool_func(True)
> false = bool_func(False)

And why do you need such functions?

-- 
Gabriel Genellina