[3.6] bpo-30803: clarify truth value testing documentation (GH-2508) (#2946)

Initial patch by Peter Thomassen.
(cherry picked from commit caa1280)

diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index e929f0b68767d47a80487f8532689ad024db597c..b8c4d59363d2a6557962b5f39baa3eb295f32d2f 100644 (file)
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -39,31 +39,26 @@ Truth Value Testing
    single: false
 
 Any object can be tested for truth value, for use in an :keyword:`if` or
-:keyword:`while` condition or as operand of the Boolean operations below. The
-following values are considered false:
+:keyword:`while` condition or as operand of the Boolean operations below.
 
-  .. index:: single: None (Built-in object)
-
-* ``None``
-
-  .. index:: single: False (Built-in object)
-
-* ``False``
-
-* zero of any numeric type, for example, ``0``, ``0.0``, ``0j``.
+.. index:: single: true
 
-* any empty sequence, for example, ``''``, ``()``, ``[]``.
+By default, an object is considered true unless its class defines either a
+:meth:`__bool__` method that returns ``False`` or a :meth:`__len__` method that
+returns zero, when called with the object. [1]_  Here are most of the built-in
+objects considered false:
 
-* any empty mapping, for example, ``{}``.
+  .. index::
+     single: None (Built-in object)
+     single: False (Built-in object)
 
-* instances of user-defined classes, if the class defines a :meth:`__bool__` or
-  :meth:`__len__` method, when that method returns the integer zero or
-  :class:`bool` value ``False``. [1]_
+* constants defined to be false: ``None`` and ``False``.
 
-.. index:: single: true
+* zero of any numeric type: ``0``, ``0.0``, ``0j``, ``Decimal(0)``,
+  ``Fraction(0, 1)``
 
-All other values are considered true --- so objects of many types are always
-true.
+* empty sequences and collections: ``''``, ``()``, ``[]``, ``{}``, ``set()``,
+  ``range(0)``
 
 .. index::
    operator: or

diff --git a/Misc/NEWS.d/next/Documentation/2017-07-29-14-55-50.bpo-30803.6hutqQ.rst b/Misc/NEWS.d/next/Documentation/2017-07-29-14-55-50.bpo-30803.6hutqQ.rst
new file mode 100644 (file)
index 0000000..4699713
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2017-07-29-14-55-50.bpo-30803.6hutqQ.rst
@@ -0,0 +1 @@
+Clarify doc on truth value testing. Original patch by Peter Thomassen.