bpo-34552: Clarify built-in types comparisons (GH-9035)

Some updates to ancient text about comparisons; fixes bp-34552.

diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index f7f59cd3a6bb9d5f45c6f8e30a09f8a8f9f02b1e..fd59a5170daedc8ae15ed2c8638ea86b72aed330 100644 (file)
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -20,10 +20,10 @@ rearrange their members in place, and don't return a specific item, never return
 the collection instance itself but ``None``.
 
 Some operations are supported by several object types; in particular,
-practically all objects can be compared, tested for truth value, and converted
-to a string (with the :func:`repr` function or the slightly different
-:func:`str` function).  The latter function is implicitly used when an object is
-written by the :func:`print` function.
+practically all objects can be compared for equality, tested for truth
+value, and converted to a string (with the :func:`repr` function or the
+slightly different :func:`str` function).  The latter function is implicitly
+used when an object is written by the :func:`print` function.
 
 
 .. _truth:
@@ -164,12 +164,10 @@ This table summarizes the comparison operations:
    pair: objects; comparing
 
 Objects of different types, except different numeric types, never compare equal.
-Furthermore, some types (for example, function objects) support only a degenerate
-notion of comparison where any two objects of that type are unequal.  The ``<``,
-``<=``, ``>`` and ``>=`` operators will raise a :exc:`TypeError` exception when
-comparing a complex number with another built-in numeric type, when the objects
-are of different types that cannot be compared, or in other cases where there is
-no defined ordering.
+The ``==`` operator is always defined but for some object types (for example,
+class objects) is equivalent to :keyword:`is`. The ``<``, ``<=``, ``>`` and ``>=``
+operators are only defined where they make sense; for example, they raise a
+:exc:`TypeError` exception when one of the arguments is a complex number.
 
 .. index::
    single: __eq__() (instance method)

diff --git a/Misc/NEWS.d/next/Documentation/2018-09-12-10-18-04.bpo-34552.p9PoYv.rst b/Misc/NEWS.d/next/Documentation/2018-09-12-10-18-04.bpo-34552.p9PoYv.rst
new file mode 100644 (file)
index 0000000..9e7605b
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2018-09-12-10-18-04.bpo-34552.p9PoYv.rst
@@ -0,0 +1,2 @@
+Make clear that ``==`` operator sometimes is equivalent to `is`. The ``<``,
+``<=``, ``>`` and ``>=`` operators are only defined where they make sense.