"help( pi )"

[Python]

On Sat, Nov 18, 2017 at 10:47:55AM +1100, Chris Angelico wrote:
> On Sat, Nov 18, 2017 at 10:34 AM, Python <python at bladeshadow.org> wrote:
> > On Sat, Nov 18, 2017 at 09:50:29AM +1100, Chris Angelico wrote:
> >> Perhaps what we want is not so much "attach docstrings to floats" but
> >> "get documentation for a module attribute, not for the object referred
> >> to".
> >
> > The reason this can't really work is that members are just variables
> > with arbitrary values.  It does not make sense for them to have doc
> > strings.
> 
> Did you read my post?

Yes!  Did you read mine?  I tried to explain to you that what you're
suggesting doesn't really fit Python's paradigm: Doc strings describe
their owner class, not individual instances--the class' doc string is
where the description of your class (or module--same thing) attributes
should go.  Of course, in most cases you can set the doc strings to
whatever you want, but in doing so you wipe out the owner class'
documentation.  If others are using your code, they may not expect or
want this, so that's mostly a bad idea.  You need a new attribute to
set the instance description, and you can in fact just add that
yourself if you want to.  Monkeypatch to your heart's content!

In this paradigm, the class for pi in your example is float, i.e. a
floating point number, where the doc string for that class would
logically be "A floating point number"--but since this is obvious,
there is no compelling reason to even have it.  In fact, it DOES have
it:

>>> x = 1.3
>>> x.__doc__
'float(x) -> floating point number\n\nConvert a string or number to a floating point number, if possible.'

Fundamental types have read-only doc strings, because it's the only
thing that makes sense.

But know what?  In fact, if you really want to, you *can* get your
attrs to have descriptive doc strings...  by defining your own class
that inherits from float (or whatever):

-=-=-=-=-=-=-

$ cat pi.py
#!/usr/bin/python

class Pi(float):
    def __init__(self):
        self.__doc__ = "the constant pi"

    def __new__(cls, value = 3.1415927):
        return float.__new__(cls, 3.1415927)

x = Pi()
print x
print x + 2
print x.__doc__

$ ./pi.py 
3.1415927
5.1415927
the constant pi

-=-=-=-=-=-=-

But asking the standard modules to do this is mostly silly, because it
doesn't fit the paradigm...  It changes the purpose of the doc string,
and obliterates the information it is INTENDED to convey.  But since
this is Python, you can still do it if you want to.