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

[David Goldsmith]

On Mon, Jun 28, 2010 at 9:34 PM, Skipper Seabold <jsseabold at gmail.com>wrote:

> On Mon, Jun 28, 2010 at 11:14 PM, David Goldsmith
> <d.l.goldsmith at gmail.com> wrote:
> >
> > 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."
> >
>
> Sound good?
>
>
> http://docs.scipy.org/numpy/Questions+Answers/#documented-and-actual-behavior-differ
>
> Skipper
>

I appreciate that you felt my reply was canonical enough to quote verbatim
:-) (or were you just being lazy ;-) ) but over there, it should be
converted to the third person.  I'll take care of it - thanks!

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