classification
Title: Documentation for datetime substract operation incorrect?
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7, Python 3.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: René Hernández Remedios, belopolsky, docs@python, martin.panter
Priority: normal Keywords: easy, patch

Created on 2017-05-30 21:22 by René Hernández Remedios, last changed 2018-07-04 23:05 by belopolsky. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 7348 merged fhackdroid, 2018-06-03 07:47
PR 8092 merged miss-islington, 2018-07-04 18:43
PR 8093 merged miss-islington, 2018-07-04 18:44
Messages (6)
msg294787 - (view) Author: René Hernández Remedios (René Hernández Remedios) Date: 2017-05-30 21:22
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?
msg294802 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2017-05-31 00:08
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
msg298963 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2017-07-24 12:56
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.
msg321061 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2018-07-04 18:42
New changeset 5b6e49a1393b3e2313471696e3568e26296137b4 by Alexander Belopolsky (Farhaan Bukhsh) in branch 'master':
bpo-30516: Fix documentation issue with -timedelta in datetime (GH-7348)
https://github.com/python/cpython/commit/5b6e49a1393b3e2313471696e3568e26296137b4
msg321066 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2018-07-04 23:04
New changeset 55f39bdabc91b387c18451c78ee077e6d05d6cfe by Alexander Belopolsky (Miss Islington (bot)) in branch '3.6':
bpo-30516: Fix documentation issue with -timedelta in datetime (GH-7348) (GH-8092)
https://github.com/python/cpython/commit/55f39bdabc91b387c18451c78ee077e6d05d6cfe
msg321067 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2018-07-04 23:04
New changeset a8bb18bbb9c286cfac5a0b8c8679c440e5c49305 by Alexander Belopolsky (Miss Islington (bot)) in branch '3.7':
bpo-30516: Fix documentation issue with -timedelta in datetime (GH-7348) (GH-8093)
https://github.com/python/cpython/commit/a8bb18bbb9c286cfac5a0b8c8679c440e5c49305
History
Date User Action Args
2018-07-04 23:05:50belopolskysetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2018-07-04 23:04:27belopolskysetmessages: + msg321067
2018-07-04 23:04:06belopolskysetmessages: + msg321066
2018-07-04 18:44:14miss-islingtonsetpull_requests: + pull_request7694
2018-07-04 18:43:23miss-islingtonsetpull_requests: + pull_request7693
2018-07-04 18:42:08belopolskysetmessages: + msg321061
2018-06-03 07:47:13fhackdroidsetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request6974
2018-02-02 20:53:57cheryl.sabellasetkeywords: + easy
type: enhancement
versions: + Python 3.8
2017-07-24 12:56:01belopolskysetassignee: docs@python
components: + Documentation
versions: + Python 3.7
nosy: + docs@python

messages: + msg298963
stage: needs patch
2017-07-24 11:01:18berker.peksagsetnosy: + belopolsky
2017-05-31 00:08:47martin.pantersetnosy: + martin.panter
messages: + msg294802
2017-05-30 21:22:13René Hernández Remedioscreate