[SciPy-Dev] Design of scipy.stats

[David Goldsmith]

On Tue, May 25, 2010 at 11:04 AM, Robert Kern <robert.kern at gmail.com> wrote:

> On Tue, May 25, 2010 at 12:47, David Goldsmith <d.l.goldsmith at gmail.com>
> wrote:
> > On Tue, May 25, 2010 at 8:54 AM, Ralf Gommers <
> ralf.gommers at googlemail.com>
> > wrote:
>
> >>>  Plus they're not really unimportant.
> >>>
> >>> Why not?  They're not returned by Python's help system.  (See earlier
> >>> this same thread.)
> >>
> >> Compare "help(alpha)" with "print alpha.__doc__" - help() is broken
> imho.
> >
> > Care to elaborate? ("Where I come from" help is the proper idiom - I've
> > never heard of anyone using, nor being told to use, print .__doc__; your
> > "ho" - that help is broken - strikes me as pretty strange).
>
> help() is broken in this case because it does not display the .__doc__
> attribute that is present. Yes, help() is idiomatic. That doesn't mean
> its behavior in this case is not broken. Nor does it mean that the
> text in the .__doc__ attributes are Unimportant for the docstring
> editing workflow. They just happen to be unavailable to the web
> docstring editor for technical reasons.


Perhaps the origin of this thread has been forgotten:

help(alpha) returns:

>>> help(alpha)
Help on alpha_gen in module scipy.stats.distributions object:

class alpha_gen(rv_continuous)
 |  ## Alpha distribution
:
:

help(alpha_gen) returns:

>>> help(alpha_gen)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
NameError: name 'alpha_gen' is not defined

But (in the Wiki) scipy.stats.distributions.alpha is "full," whereas
scipy.stats.distributions.alpha_gen is empty (but for automatically
generated content): help and the doc Wiki appear to exhibit the "transpose"
of one another - I don't know "which one" is "broken" in this situation, but
obviously something is.

At what level is help broken: the scipy level or the Python level?  If help
is simply an alias for print .__doc__, why precisely is this happening?  Is
this an undiagnosed breakage (in the sense that only the symptom(s), but
neither the cause(s) nor the cure(s) are known)?

Looking back on this thread, since <X> is the thing users are intended to
use, it sounds like the docstring _should_ be associated with <X>, not
<X>_gen, so I guess the Wiki is showing the docstring in the "right" place,
but why does help associate the docstring with <X>_gen?  And if the
docstring for <X> is consequently important, is the docstring for <X>_gen
Unimportant (since its object "should" never be used explicitly)?  If its
docstring is also important, please explain why.

Thanks.

DG


> If you want to mark them
> Unimportant just as a workaround, that's fine. But if you are keeping
> track of items to work on this summer, these are important things to
> do. You will just have to do it manually.
>
> --
> Robert Kern
>
> "I have come to believe that the whole world is an enigma, a harmless
> enigma that is made terrible by our own mad attempt to interpret it as
> though it had an underlying truth."
>  -- Umberto Eco
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>



-- 
Mathematician: noun, someone who disavows certainty when their uncertainty
set is non-empty, even if that set has measure zero.

Hope: noun, that delusive spirit which escaped Pandora's jar and, with her
lies, prevents mankind from committing a general suicide.  (As interpreted
by Robert Graves)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20100525/092ebbad/attachment.html>