#2147: PEP 237 changes to overflow behavior.

Doc/library/exceptions.rst

@@ -254,11 +254,10 @@ The following exceptions are the exceptions that are actually raised.
 
    Raised when the result of an arithmetic operation is too large to be
    represented.  This cannot occur for long integers (which would rather raise
-   :exc:`MemoryError` than give up).  Because of the lack of standardization of
-   floating point exception handling in C, most floating point operations also
-   aren't checked.  For plain integers, all operations that can overflow are
-   checked except left shift, where typical applications prefer to drop bits than
-   raise an exception.
+   :exc:`MemoryError` than give up) and for most operations with plain integers,
+   which return a long integer instead.  Because of the lack of standardization
+   of floating point exception handling in C, most floating point operations
+   also aren't checked.
 
 
 .. exception:: ReferenceError

Doc/library/stdtypes.rst

@@ -406,8 +406,7 @@ The priorities of the binary bitwise operations are all lower than the numeric
 operations and higher than the comparisons; the unary operation ``~`` has the
 same priority as the other unary numeric operations (``+`` and ``-``).
 
-This table lists the bit-string operations sorted in ascending priority
-(operations in the same box have the same priority):
+This table lists the bit-string operations sorted in ascending priority:
 
 +------------+--------------------------------+----------+
 | Operation  | Result                         | Notes    |
@@ -440,12 +439,11 @@ Notes:
    Negative shift counts are illegal and cause a :exc:`ValueError` to be raised.
 
 (2)
-   A left shift by *n* bits is equivalent to multiplication by ``pow(2, n)``
-   without overflow check.
+   A left shift by *n* bits is equivalent to multiplication by ``pow(2, n)``.  A
+   long integer is returned if the result exceeds the range of plain integers.
 
 (3)
-   A right shift by *n* bits is equivalent to division by ``pow(2, n)`` without
-   overflow check.
+   A right shift by *n* bits is equivalent to division by ``pow(2, n)``.
 
 
 .. _typeiter:

Doc/reference/datamodel.rst

@@ -175,23 +175,24 @@ Ellipsis
             object: plain integer
             single: OverflowError (built-in exception)
 
-         These represent numbers in the range -2147483648 through 2147483647. (The range
-         may be larger on machines with a larger natural word size, but not smaller.)
-         When the result of an operation would fall outside this range, the result is
-         normally returned as a long integer (in some cases, the exception
-         :exc:`OverflowError` is raised instead). For the purpose of shift and mask
-         operations, integers are assumed to have a binary, 2's complement notation using
-         32 or more bits, and hiding no bits from the user (i.e., all 4294967296
-         different bit patterns correspond to different values).
+         These represent numbers in the range -2147483648 through 2147483647.
+         (The range may be larger on machines with a larger natural word size,
+         but not smaller.)  When the result of an operation would fall outside
+         this range, the result is normally returned as a long integer (in some
+         cases, the exception :exc:`OverflowError` is raised instead).  For the
+         purpose of shift and mask operations, integers are assumed to have a
+         binary, 2's complement notation using 32 or more bits, and hiding no
+         bits from the user (i.e., all 4294967296 different bit patterns
+         correspond to different values).
 
       Long integers
          .. index:: object: long integer
 
-         These represent numbers in an unlimited range, subject to available (virtual)
-         memory only.  For the purpose of shift and mask operations, a binary
-         representation is assumed, and negative numbers are represented in a variant of
-         2's complement which gives the illusion of an infinite string of sign bits
-         extending to the left.
+         These represent numbers in an unlimited range, subject to available
+         (virtual) memory only.  For the purpose of shift and mask operations, a
+         binary representation is assumed, and negative numbers are represented
+         in a variant of 2's complement which gives the illusion of an infinite
+         string of sign bits extending to the left.
 
       Booleans
          .. index::
@@ -199,20 +200,22 @@ Ellipsis
             single: False
             single: True
 
-         These represent the truth values False and True.  The two objects representing
-         the values False and True are the only Boolean objects. The Boolean type is a
-         subtype of plain integers, and Boolean values behave like the values 0 and 1,
-         respectively, in almost all contexts, the exception being that when converted to
-         a string, the strings ``"False"`` or ``"True"`` are returned, respectively.
+         These represent the truth values False and True.  The two objects
+         representing the values False and True are the only Boolean objects.
+         The Boolean type is a subtype of plain integers, and Boolean values
+         behave like the values 0 and 1, respectively, in almost all contexts,
+         the exception being that when converted to a string, the strings
+         ``"False"`` or ``"True"`` are returned, respectively.
 
       .. index:: pair: integer; representation
 
-      The rules for integer representation are intended to give the most meaningful
-      interpretation of shift and mask operations involving negative integers and the
-      least surprises when switching between the plain and long integer domains.  Any
-      operation except left shift, if it yields a result in the plain integer domain
-      without causing overflow, will yield the same result in the long integer domain
-      or when using mixed operands.
+      The rules for integer representation are intended to give the most
+      meaningful interpretation of shift and mask operations involving negative
+      integers and the least surprises when switching between the plain and long
+      integer domains.  Any operation, if it yields a result in the plain
+      integer domain, will yield the same result in the long integer domain or
+      when using mixed operands.  The switch between domains is transparent to
+      the programmer.
 
    :class:`numbers.Real` (:class:`float`)
       .. index::

Doc/reference/expressions.rst

@@ -944,11 +944,9 @@ by the number of bits given by the second argument.
 
 .. index:: exception: ValueError
 
-A right shift by *n* bits is defined as division by ``pow(2,n)``.  A left shift
-by *n* bits is defined as multiplication with ``pow(2,n)``; for plain integers
-there is no overflow check so in that case the operation drops bits and flips
-the sign if the result is not less than ``pow(2,31)`` in absolute value.
-Negative shift counts raise a :exc:`ValueError` exception.
+A right shift by *n* bits is defined as division by ``pow(2, n)``.  A left shift
+by *n* bits is defined as multiplication with ``pow(2, n)``.  Negative shift
+counts raise a :exc:`ValueError` exception.
 
 
 .. _bitwise: