Issue 1979: Make Decimal comparisons (other than !=, ==) involving NaN

raise InvalidOperation (and return False if InvalidOperation is trapped).

1 files changed, 13 insertions, 0 deletions

diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst
index 7b85806..ebb18bb 100644
--- a/Doc/library/decimal.rst
+++ b/Doc/library/decimal.rst
@@ -1290,6 +1290,19 @@ A variant is :const:`sNaN` which signals rather than remaining quiet after every
 operation.  This is a useful return value when an invalid result needs to
 interrupt a calculation for special handling.
 
+The behavior of Python's comparison operators can be a little surprising where a
+:const:`NaN` is involved.  A test for equality where one of the operands is a
+quiet or signaling :const:`NaN` always returns :const:`False` (even when doing
+``Decimal('NaN')==Decimal('NaN')``), while a test for inequality always returns
+:const:`True`.  An attempt to compare two Decimals using any of the :const:'<',
+:const:'<=', :const:'>' or :const:'>=' operators will raise the
+:exc:`InvalidOperation` signal if either operand is a :const:`NaN`, and return
+:const:`False` if this signal is trapped.  Note that the General Decimal
+Arithmetic specification does not specify the behavior of direct comparisons;
+these rules for comparisons involving a :const:`NaN` were taken from the IEEE
+754 standard.  To ensure strict standards-compliance, use the :meth:`compare`
+and :meth:`compare-signal` methods instead.
+
 The signed zeros can result from calculations that underflow. They keep the sign
 that would have resulted if the calculation had been carried out to greater
 precision.  Since their magnitude is zero, both positive and negative zeros are