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 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.

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 10e466448f67850ed7bb2e2a4e7f017f2b050cad by Srinivas Reddy Thatiparthy (శ్రీనివాస్  రెడ్డి తాటిపర్తి) in branch 'master':
bpo-41205: Document Decimal power 0 to the 0 (GH-21386)
https://github.com/python/cpython/commit/10e466448f67850ed7bb2e2a4e7f017f2b050cad

New changeset 8831162464138eb0267f4967b85710247ee95fde by Miss Islington (bot) in branch '3.9':
bpo-41205: Document Decimal power 0 to the 0 (GH-21386)
https://github.com/python/cpython/commit/8831162464138eb0267f4967b85710247ee95fde

New changeset dac8a3a15647d016842e2ae7284cefa27ce5e838 by Miss Islington (bot) in branch '3.8':
bpo-41205: Document Decimal power 0 to the 0 (GH-21386)
https://github.com/python/cpython/commit/dac8a3a15647d016842e2ae7284cefa27ce5e838

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