Documentation for datetime substract operation incorrect?

[RenHernndezRemedios]

BPO	30516
Nosy	@abalkin, @vadmium
PRs	bpo-30516: Fix documentation issue with -timedelta in datetime #7348 [3.6] bpo-30516: Fix documentation issue with -timedelta in datetime (GH-7348) #8092 [3.7] bpo-30516: Fix documentation issue with -timedelta in datetime (GH-7348) #8093

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2018-07-04.23:05:50.649>
created_at = <Date 2017-05-30.21:22:13.435>
labels = ['easy', '3.8', 'type-feature', '3.7', 'docs']
title = 'Documentation for datetime substract operation incorrect?'
updated_at = <Date 2018-07-04.23:05:50.649>
user = 'https://bugs.python.org/RenHernndezRemedios'

bugs.python.org fields:

activity = <Date 2018-07-04.23:05:50.649>
actor = 'belopolsky'
assignee = 'docs@python'
closed = True
closed_date = <Date 2018-07-04.23:05:50.649>
closer = 'belopolsky'
components = ['Documentation']
creation = <Date 2017-05-30.21:22:13.435>
creator = 'Ren\xc3\xa9 Hern\xc3\xa1ndez Remedios'
dependencies = []
files = []
hgrepos = []
issue_num = 30516
keywords = ['patch', 'easy']
message_count = 6.0
messages = ['294787', '294802', '298963', '321061', '321066', '321067']
nosy_count = 4.0
nosy_names = ['belopolsky', 'docs@python', 'martin.panter', 'Ren\xc3\xa9 Hern\xc3\xa1ndez Remedios']
pr_nums = ['7348', '8092', '8093']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue30516'
versions = ['Python 3.6', 'Python 3.7', 'Python 3.8']

[RenHernndezRemedios]

In the documentation for the supported arithmetic operations for a datetime object, there is the following note, among other:

datetime2 = datetime1 - timedelta

Comment:
Computes the datetime2 such that datetime2 + timedelta == datetime1. As for addition, the result has the same 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.

While reading the source code for __sub__ operation I found in the first few lines:

Line 1885:
def __sub__(self, other):
"Subtract two datetimes, or a datetime and a timedelta."
if not isinstance(other, datetime):
if isinstance(other, timedelta):
return self + -other
return NotImplemented

Is the documentation in contradiction with the actual implementation?

[vadmium]

The C "_datetime" implementation seems to handle this as documented. But either way, the "timedelta" range is greater than the "datetime" range, so it seems to be just a difference in OverflowError messages, not a big practical problem:

Python "datetime" implementation:
>>> import sys
>>> sys.modules["_datetime"] = None
>>> from datetime import *
>>> datetime.max - timedelta.max
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "C:\Users\Martin\AppData\Local\Programs\Python\Python35-32\lib\datetime.py", line 1741, in __sub__
    return self + -other
  File "C:\Users\Martin\AppData\Local\Programs\Python\Python35-32\lib\datetime.py", line 518, in __neg__
    -self._microseconds)
  File "C:\Users\Martin\AppData\Local\Programs\Python\Python35-32\lib\datetime.py", line 430, in __new__
    raise OverflowError("timedelta # of days is too large: %d" % d)
OverflowError: timedelta # of days is too large: -1000000000

C "_datetime" implementation:
>>> from datetime import *
>>> datetime.max - timedelta.max
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
OverflowError: date value out of range

[abalkin]

I agree. The documentation can be improved here. The note about x - y not being quite the same as x + (-y) belongs to the timedelta - timedelta operation. It should be removed from both date - timedelta and datetime-timedelta footnotes.

[abalkin]

New changeset 5b6e49a by Alexander Belopolsky (Farhaan Bukhsh) in branch 'master':
bpo-30516: Fix documentation issue with -timedelta in datetime (GH-7348)
5b6e49a

[abalkin]

New changeset 55f39bd by Alexander Belopolsky (Miss Islington (bot)) in branch '3.6':
bpo-30516: Fix documentation issue with -timedelta in datetime (GH-7348) (GH-8092)
55f39bd

[abalkin]

New changeset a8bb18b by Alexander Belopolsky (Miss Islington (bot)) in branch '3.7':
bpo-30516: Fix documentation issue with -timedelta in datetime (GH-7348) (GH-8093)
a8bb18b