[Python-Dev] decimal API

[Tim Peters]

[Raymond Hettinger]
> Add one more.  The specs, the docs, the tutorial, and docstrings are
> chock full of extensive examples.  Those examples include NaNs and
> Infinities.  If the traps are all turned off by default, then the
> examples fail.

Did you say what you meant there?

...
> I've spent weeks trying making sure the module integrates well with the
> rest of Python.  To make the API choices as informed as possible, I
> built some apps, wrote the docs (incl. docstrings, tutorial, and
> whatsnew), communicated with Cowlishaw, communicated with the other
> module authors, and read the after-the-fact usability reviews on Java's
> big decimal package.

In some real ways, that makes you over-qualified to judge how "typical
users" will react -- you've learned too much about it.  The spec has a
great deal of internal consistency in non-stop mode, and that's
seductive.  The problem is when real users run a program for an hour,
and get a screen full of infinities and NaNs as output.  Then they're
pissed.  You can't get a NaN or infinity from finite operands without
signaling one of the 3 I recommend trap-enabling, so enabling those
traps stops their program the instant the first NaN or infinity
appears.  Then it's much easier to figure out the true cause.  NaNs
and infinities are highly contagious after they appear, and
NaN-poisoning in 754 is even worse than const-poisoning in C <wink>.

>  So, please, try out the module as-is and share the results of your experience.

That's a fair request, but I'll note that there's nothing hard to live
with when seeing a NaN or infinity result at an interactive prompt. 
You see one and go "oops!", and backtrack a step or two then.  A
long-running program just keeps going, and the special values spread.

> People have been fond of quoting Tim lately.

Not me!  I never quote Tim.

> I think either he or Guido said that they are not persuaded by arguments that
> people are not bright enough to get concepts like Infinity or NaN:

They're bright enough, but from that it doesn't follow that infinities
or NaNs are useful to most programs most of the time.  They really
aren't, notwithstanding that programs designed with them in mind can
sometimes make good use of them.

>    >>> Decimal(1) / Decimal(0)
>    Decimal("Infinity")
>
> Not nearly as hard as descriptors, Unicode, half-open intervals, etc ;-)

Now compute (1+i/j)**n as the first step in a financial projection. 
If j is 0, i/j is +Inf (assuming j isn't 0 too, else it's NaN), then
1+i/j is +Inf, then (1+i/j)**n is probably +Inf too, and on & on it
goes.  The +Inf at the end just tells you that something went wrong
sometime, with no clue as to what or when.

> More seriously, non-casual users of decimal *will* have to grapple with
> the concept of contexts.  It is intrinsic to what the module is about.
> It's not difficult, but it can't be avoided.  To that end, I introduced
> contexts right away in tutorial and in the quick-start section of the
> docs.

Another worthy goal is that casual users of decimal not have to know
about context at all.  Your fp HW has context too, most C runtimes are
set up to disable all fp traps by default, but Python bitches at you
if you try to divide by 0.0 anyway (although C would not).  I'm glad
it does.