[SciPy-Dev] factorial2 does not return a float with exact=False

[David Goldsmith]

On Mon, Jun 28, 2010 at 6:29 PM, Vincent Davis <vincent at vincentdavis.net>wrote:

> On Mon, Jun 28, 2010 at 7:24 PM, Warren Weckesser
> <warren.weckesser at enthought.com> wrote:
> > Vincent Davis wrote:
> >> On Mon, Jun 28, 2010 at 7:11 PM, Vincent Davis <
> vincent at vincentdavis.net> wrote:
> >>
> >>> According to the docs factorial2 should return a float or int, float
> >>> in the case of exact=False, It does not.
> >>>
> >>>
> >>>>>> import scipy.misc.common as sc
> >>>>>> sc.factorial2(7, exact=False)
> >>>>>>
> >>> array(105.00000000000001)
> >>>
> >>>>>> sc.factorial2(7, exact=True)
> >>>>>>
> >>> 105L
> >>>
> >>>>>> sc.factorial2(8, exact=True)
> >>>>>>
> >>> 384L
> >>>
> >>>>>> sc.factorial2(8, exact=False)
> >>>>>>
> >>> array(384.0)
> >>>
> >>>>>> sc.factorial2(8, exact=False)
> >>>>>>
> >>
> >> Same with factorial
> >>
> >>
> >>>>> sc.factorial(5, exact=False)
> >>>>>
> >> array(120.0)
> >>
> >>>>> arr = np.array([3,4,5])
> >>>>> sc.factorial(arr, exact=False)
> >>>>>
> >> array([   6.,   24.,  120.])
> >>
> >>>>> sc.factorial(5, exact=True)
> >>>>>
> >> 120L
> >>
> >
> > I think the problem is simply that it is an awkward API.  After looking
> > at the code for factorial, a more precise description is:
> >
> > If `exact` is True, `n` must be an integer, and an integer is returned.
> >
> > If `exact` is False, `n` is array_like, and an array the same shape as
> > `n` is returned.
>
> I am finding that when editing the docs it is not always clear if the
> problem is the docs or the function.
> comb() has a similar issue.
>
> I guess my question is?
> My thought is the you factoral(), or comb() return an array only if 1,
> exact=False and n is not an array. Basically you get back the same
> dtype as input.
> That said fixing the docs is just a little easier.
>

This issue has come up many times; again, here's the "policy": document
desired/intended behavior, not actual behavior - if they differ, and the doc
specifies the desired/intended behavior correctly, then file a (code) bug
report; if the function is behaving correctly, but the doc doesn't correctly
document that behavior, correct the doc in the Wiki; if both are wrong (and
there is precedent for this) then both actions must be taken.  What is the
implication of this when you encounter this situation while editing the
docs?  You must do what you've done: post to the appropriate list, asking
which is correct, and wait a little while for a decision; if several days
pass and no one responds, re-post; if several days pass and there remains
disagreement on the matter, file a bug ticket, so the debate moves over
there and "move on."

DG
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20100628/5f7d19db/attachment.html>