"help( pi )"

[Cameron Simpson]

On 17Nov2017 11:09, Dennis Lee Bieber <wlfraed at ix.netcom.com> wrote:
>On 17 Nov 2017 12:36:37 GMT, ram at zedat.fu-berlin.de (Stefan Ram) declaimed
>>“The argument to pydoc can be the name of a function,
>>module, or package, or a dotted reference to a class,
>>method, or function within a module or module in a package.”
>>
>>  , but not for »pi«:
>	math.pi is NOT a "function, module, or package..."
>	Would you expect
>		help(1)
>to produce something like "Multiplicative identity"? (or "Boolean truth"
>especially for older Python code before True/False became standard). Why
>should
>		help(3.1415926536)	#or whatever precision is used in module math
>produce anything? That IS what is seen by the help() operation, not the
>name "pi", just a number. And if help() somehow recognizes 3.1415926536 as
>pi, what does it do if provided with just 3.141592654 instead?

This is not a consistent argument.

  mymath.py:
    def square(x):
      ''' Return the square of a value: its value muliplied by itself.
      '''
      return x*x

  my code:
    from mymath import square
    def sq2(x):
      return x*x

I expect help(square) to have doco and don't expect help(sq2) to have doco.

Stefan's argument points to the deficiency that one cannot attach a docstring 
to things like numbers. I've certainly wanted to.

I don't think he's arguing that help magicly recognises 3.1415926536 as "pi" 
and produces a docstring for it and all "sufficiently close" values. I'm not.  
But the math module has bound "pi" to a specific float. Why _can't_ we annotate 
that float with a docstring?

  math.py:
    pi = 3.1415926536
    pi.__doc__ = 'The ratio of round things to straight things. Roughly 3.'

Now, I accept that the "CPython coaleases some values to shared singletons" 
thing is an issue, but the language doesn't require it, and one could change 
implementations such that applying a docstring to an object _removed_ it from 
the magic-shared-singleton pool, avoiding conflicts with other uses of the same 
value by coincidence.

Cheers,
Cameron Simpson <cs at cskk.id.au> (formerly cs at zip.com.au)