Title: Documentation Decimal power 0 to the 0 is Nan (versus 0 to the 0 which is 1)
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.10, Python 3.9, Python 3.8
Status: pending Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: JD-Veiga, docs@python, facundobatista, mark.dickinson, miss-islington, rhettinger, skrah, thatiparthy, tim.peters
Priority: normal Keywords: patch

Created on 2020-07-03 22:51 by JD-Veiga, last changed 2020-08-15 20:48 by skrah.

Pull Requests
URL Status Linked Edit
PR 21386 merged thatiparthy, 2020-07-08 04:21
PR 21547 merged miss-islington, 2020-07-19 11:03
PR 21548 merged miss-islington, 2020-07-19 11:04
Messages (10)
msg372969 - (view) Author: JD-Veiga (JD-Veiga) Date: 2020-07-03 22:51

I would like to propose a minor addition to `decimal` package documentation page ( I think that we should add a paragraph in `context.power(x, y, modulo=None)` stating that `Decimal(0) ** Decimal(0)` returns `Decimal('NaN')` instead of `1` --as `0 ** 0` does-- or `1.0` --in case of `0.0 ** 0.0`.

Indeed, `0 ** 0` is `NaN` is mentioned as example of operations raising `InvalidOperation` exceptions.

However, I think that this is not enough to indicate the different behaviour of decimal versus int and float numbers.

Moreover, in the case of `%` and `//` operators, there are clear remarks on these differences (See: “There are some small differences between arithmetic on Decimal objects and arithmetic on integers and floats [...]” in the page).

Thank you and sorry for the inconvenience.
msg372975 - (view) Author: Tim Peters (tim.peters) * (Python committer) Date: 2020-07-04 03:45
Huh! I thought everyone in Standards World gave up by now, and agreed 0**0 should be 1.
msg372980 - (view) Author: JD-Veiga (JD-Veiga) Date: 2020-07-04 06:49
Well, it is the way that it has been defined in `decimal` package and in the document that inspired this package (IBM's General Decimal Arithmetic Specification, The General Decimal Arithmetic Specification:
msg372982 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2020-07-04 07:16
I agree that the result is surprising and should be noted in the docs; we shouldn't expect all the decimal users to be familiar with the specification. Some of the other differences with float arithmetic *are* noted (e.g., the behaviour of `//` and `%`), but apparently not this one. We do document the behaviour of these corner cases for `math.pow`.

The part that I find really odd is that the specification says that `Decimal("inf")**Decimal(0)` is `1`. Treating one of 0**0 and inf**0 as undefined but not the other seems inconsistent to me. We'd probably want to note the behaviour of inf**0 in the docs, too. (I tried to argue with Mike Cowlishaw about this, but I lost.)

I'm not sure whether just noting this in the "power" documentation is enough: it's not clear to me that users using the ** operator would think to check the docs for the "power" method.

The other weirdly non-IEEE 754 behaviour (again, mandated by the standard) that bugs me from time to time is that the unary `-` and `+` operators will never give negative zero: Decimal("-0.0") and -Decimal("0.0") are not the same thing. That one's probably worth noting, too.
msg372986 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2020-07-04 09:22
Agreed, and it's even slightly worse with the ROUND_FLOOR special case:

>>> c.rounding = ROUND_FLOOR
>>> +Decimal("-0")

That's why there are three slightly different methods for applying the

   1) context.create_decimal() ==> special case for NaN payloads.

   2) context.apply() (private method) ==> no special cases at all.

   3) ==> ROUND_FLOOR special case.
msg373225 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2020-07-07 13:53
@JD-Veiga: would you be willing to work on a PR?
msg373956 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2020-07-19 11:03
New changeset 10e466448f67850ed7bb2e2a4e7f017f2b050cad by Srinivas Reddy Thatiparthy (శ్రీనివాస్  రెడ్డి తాటిపర్తి) in branch 'master':
bpo-41205: Document Decimal power 0 to the 0 (GH-21386)
msg373958 - (view) Author: miss-islington (miss-islington) Date: 2020-07-19 11:10
New changeset 8831162464138eb0267f4967b85710247ee95fde by Miss Islington (bot) in branch '3.9':
bpo-41205: Document Decimal power 0 to the 0 (GH-21386)
msg373959 - (view) Author: miss-islington (miss-islington) Date: 2020-07-19 11:10
New changeset dac8a3a15647d016842e2ae7284cefa27ce5e838 by Miss Islington (bot) in branch '3.8':
bpo-41205: Document Decimal power 0 to the 0 (GH-21386)
msg375495 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2020-08-15 20:48
Mark, do you think that we should document the other oddity as well
or should we close this?
Date User Action Args
2020-08-15 20:48:36skrahsetstatus: open -> pending

messages: + msg375495
2020-07-19 11:10:50miss-islingtonsetmessages: + msg373959
2020-07-19 11:10:07miss-islingtonsetmessages: + msg373958
2020-07-19 11:04:06miss-islingtonsetpull_requests: + pull_request20690
2020-07-19 11:03:58miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request20689
2020-07-19 11:03:48skrahsetmessages: + msg373956
2020-07-08 04:21:12thatiparthysetkeywords: + patch
nosy: + thatiparthy

pull_requests: + pull_request20532
stage: patch review
2020-07-07 13:53:32mark.dickinsonsetmessages: + msg373225
2020-07-04 09:22:30skrahsetmessages: + msg372986
2020-07-04 07:16:30mark.dickinsonsetmessages: + msg372982
2020-07-04 06:49:45JD-Veigasetmessages: + msg372980
2020-07-04 03:45:02tim.peterssetnosy: + tim.peters
messages: + msg372975
2020-07-04 02:03:36xtreaksetnosy: + rhettinger, facundobatista, mark.dickinson, skrah
2020-07-03 22:51:25JD-Veigacreate