Hi,

I would like to propose a minor addition to decimal package documentation page (https://docs.python.org/3/library/decimal.html). 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.

Huh! I thought everyone in Standards World gave up by now, and agreed 0**0 should be 1.

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: http://speleotrove.com/decimal/decarith.html).

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 00 and inf0 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.

Agreed, and it's even slightly worse with the ROUND_FLOOR special case:

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

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

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

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

3. Decimal.plus() ==> ROUND_FLOOR special case.

@JD-Veiga: would you be willing to work on a PR?

New changeset 10e4664 by Srinivas Reddy Thatiparthy (శ్రీనివాస్ రెడ్డి తాటిపర్తి) in branch 'master':
bpo-41205: Document Decimal power 0 to the 0 (GH-21386)
10e4664

New changeset 8831162 by Miss Islington (bot) in branch '3.9':
bpo-41205: Document Decimal power 0 to the 0 (GH-21386)
8831162

New changeset dac8a3a by Miss Islington (bot) in branch '3.8':
bpo-41205: Document Decimal power 0 to the 0 (GH-21386)
dac8a3a

Mark, do you think that we should document the other oddity as well
or should we close this?

@skrah Issue seems to be solved. We can close the issue.

Closing. It doesn't seem worth documenting the inf**0 oddity unless someone yells.