"help( pi )"

[Chris Angelico]

On Wed, Nov 22, 2017 at 4:47 PM, Gregory Ewing
<greg.ewing at canterbury.ac.nz> wrote:
> Cameron Simpson wrote:
>>
>> one could change  implementations such that applying a docstring to an
>> object _removed_ it from  the magic-shared-singleton pool,
>
>
> That's not sufficient, though. Consider:
>
>    BUFFER_SIZE = 256
>    BUFFER_SIZE.__doc__ = "Size of the buffer"
>
>    TWO_TO_THE_EIGHT = 256
>    TWO_TO_THE_EIGHT.__doc__ = "My favourite power of two"
>
> Before the code is even run, the compiler may have merged the
> two occurences of the integer literal 256 into one entry in
> co_consts. By the time the docstrings are assigned, it's too
> late to decide that they really needed to be different objects.
>
> So, an int with a docstring needs to be explicitly created as
> a separate object to begin with, one way or another.

class Int(int):
    def __new__(cls, *a, **kw):
        __doc__ = kw.pop("doc", None)
        self = super().__new__(cls, *a, **kw)
        self.__doc__ = __doc__
        return self

BUFFER_SIZE = Int(256, doc="Size of the buffer")

ChrisA