[Python-checkins] bpo-30516: Fix documentation issue with -timedelta in datetime (GH-7348) (GH-8092)

[Alexander Belopolsky]

https://github.com/python/cpython/commit/55f39bdabc91b387c18451c78ee077e6d05d6cfe
commit: 55f39bdabc91b387c18451c78ee077e6d05d6cfe
branch: 3.6
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: Alexander Belopolsky <abalkin at users.noreply.github.com>
date: 2018-07-05T00:04:03+01:00
summary:

bpo-30516: Fix documentation issue with -timedelta in datetime (GH-7348) (GH-8092)

This commit fixes the -timedelta overfllow issue not documented properly.

Signed-off-by: Farhaan Bukhsh <farhaan.bukhsh at gmail.com>
(cherry picked from commit 5b6e49a1393b3e2313471696e3568e26296137b4)

Co-authored-by: Farhaan Bukhsh <farhaan.bukhsh at gmail.com>

files:
M Doc/library/datetime.rst

diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index 06141d1c00d9..89f85fc11ad4 100644
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -241,7 +241,7 @@ Supported operations:
 +--------------------------------+-----------------------------------------------+
 | ``t1 = t2 - t3``               | Difference of *t2* and *t3*. Afterwards *t1*  |
 |                                | == *t2* - *t3* and *t2* == *t1* + *t3* are    |
-|                                | true. (1)                                     |
+|                                | true. (1)(6)                                  |
 +--------------------------------+-----------------------------------------------+
 | ``t1 = t2 * i or t1 = i * t2`` | Delta multiplied by an integer.               |
 |                                | Afterwards *t1* // i == *t2* is true,         |
@@ -316,6 +316,11 @@ Notes:
   >>> print(_)
   -1 day, 19:00:00
 
+(6)
+   The expression ``t2 - t3`` will always be equal to the expression ``t2 + (-t3)`` except
+   when t3 is equal to ``timedelta.max``; in that case the former will produce a result
+   while the latter will overflow.
+
 In addition to the operations listed above :class:`timedelta` objects support
 certain additions and subtractions with :class:`date` and :class:`.datetime`
 objects (see below).
@@ -497,8 +502,6 @@ Notes:
    :const:`MINYEAR` or larger than :const:`MAXYEAR`.
 
 (2)
-   This isn't quite equivalent to date1 + (-timedelta), because -timedelta in
-   isolation can overflow in cases where date1 - timedelta does not.
    ``timedelta.seconds`` and ``timedelta.microseconds`` are ignored.
 
 (3)
@@ -930,8 +933,6 @@ Supported operations:
    Computes the datetime2 such that datetime2 + timedelta == datetime1. As for
    addition, the result has the same :attr:`~.datetime.tzinfo` attribute as the input
    datetime, and no time zone adjustments are done even if the input is aware.
-   This isn't quite equivalent to datetime1 + (-timedelta), because -timedelta
-   in isolation can overflow in cases where datetime1 - timedelta does not.
 
 (3)
    Subtraction of a :class:`.datetime` from a :class:`.datetime` is defined only if