This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: [doc] documentation incorrectly says that “datetime.timestamp” calls “mktime”
Type: behavior Stage:
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: belopolsky, docs@python, martin.panter, serhiy.storchaka
Priority: normal Keywords:

Created on 2017-10-29 21:10 by serhiy.storchaka, last changed 2022-04-11 14:58 by admin.

Messages (9)
msg305192 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-10-29 21:10
$ ./python -m test -vuall test_datetime
...
======================================================================
FAIL: test_timestamp_naive (test.datetimetester.TestDateTime_Pure)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/home/serhiy/py/cpython3.7/Lib/test/support/__init__.py", line 1622, in inner
    return func(*args, **kwds)
  File "/home/serhiy/py/cpython3.7/Lib/test/datetimetester.py", line 1977, in test_timestamp_naive
    self.assertEqual(t.timestamp(), 18000.0)
AssertionError: 14400.0 != 18000.0


...

Simple reproducer:

$ TZ=EST+05EDT,M3.2.0,M11.1.0 ./python -c 'import datetime; print(datetime.datetime(1970, 1, 1).timestamp())'
14400.0

It should print 18000.0 (5 hours) instead of 14400.0 (4 hours).
msg305193 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2017-10-29 21:58
I don't have access to NetBSD and this looks like a bug in the system implementation of localtime.  The timestamp method is implemented by probing system localtime in the vicinity of UTC timestamp.

What does time.localtime(14400) with these TZ settings?
msg305194 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-10-29 22:09
$ TZ=EST+05EDT,M3.2.0,M11.1.0 ./python -c 'import time; print(time.localtime(14400))'
time.struct_time(tm_year=1970, tm_mon=1, tm_mday=1, tm_hour=0, tm_min=0, tm_sec=0, tm_wday=3, tm_yday=1, tm_isdst=1)
msg305195 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2017-10-29 22:13
I hate this long form display!

Next time please use time.localtime(14400)[:].

Do you agree that this is a system bug?  On my Mac, I get

$ python -c 'import time; print(time.localtime(14400)[:])'
(1969, 12, 31, 23, 0, 0, 2, 365, 0)
msg305196 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2017-10-29 22:15
I posted a wrong command, but fortunately I am in New York, so it did not matter

$ TZ=EST+05EDT,M3.2.0,M11.1.0 python -c 'import time;print(time.localtime(14400)[:])'
(1969, 12, 31, 23, 0, 0, 2, 365, 0)
msg305197 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2017-10-29 22:42
I'm not a datetime expert. What is the better way to skip the test? Is it worth to change the date to say (1970, 3, 9) for which the correct result is obtained on this system?
msg305198 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2017-10-29 23:25
I am not sure.  This is a system bug and we often provide work-arounds
or even reimplementations of buggy time functions in the time and
datetime modules. Whether or not this is something that is worth
fixing is a question for the affected NetBSD users.

I would say, for the purposes of this issue - add a skip for NetBSD to
the failing test and add a test for another date that can be included
on all systems.

If motivated, please open a separate issue for the time.localtime() bug.
msg305201 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2017-10-30 01:30
Are you sure it is a “system” bug? As far as I understand, at least Posix does not require support for local time before 1970. See <http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_16>.

But why is localtime(14400) relevant? The documentation only says “datetime.timestamp” calls “mktime”, which should be valid since the UTC-5 timezone offset will give a positive timestamp. Perhaps is this similar to Issue 29097, probing a date before 1970?
msg305203 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2017-10-30 01:54
> The documentation only says “datetime.timestamp” calls “mktime”

Indeed.  See <https://docs.python.org/3/library/datetime.html#datetime.datetime.timestamp>.

This is a documentation bug.  Since 3.6 the timestamp does not call
mktime.  In fact, mktime should not be called anywhere in the datetime
module. See <https://github.com/python/cpython/blob/a2314283ff87c65e1745a42c2f2b716b1a209128/Modules/_datetimemodule.c#L5315>.

For the explanation of why mktime is not a good API, see PEP 495.

On Sun, Oct 29, 2017 at 9:30 PM, Martin Panter <report@bugs.python.org> wrote:
>
> Martin Panter <vadmium+py@gmail.com> added the comment:
>
> Are you sure it is a “system” bug? As far as I understand, at least Posix does not require support for local time before 1970. See <http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_16>.
>
> But why is localtime(14400) relevant? The documentation only says “datetime.timestamp” calls “mktime”, which should be valid since the UTC-5 timezone offset will give a positive timestamp. Perhaps is this similar to Issue 29097, probing a date before 1970?
>
> ----------
> nosy: +martin.panter
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <https://bugs.python.org/issue31894>
> _______________________________________
History
Date User Action Args
2022-04-11 14:58:53adminsetgithub: 76075
2022-01-16 23:40:49iritkatrielsetnosy: + docs@python
title: test_timestamp_naive failed on NetBSD -> [doc] documentation incorrectly says that “datetime.timestamp” calls “mktime”
assignee: docs@python
versions: + Python 3.9, Python 3.10, Python 3.11, - Python 3.6, Python 3.7
components: + Documentation, - Library (Lib), Tests
2017-10-30 01:54:59belopolskysetmessages: + msg305203
2017-10-30 01:30:03martin.pantersetnosy: + martin.panter
messages: + msg305201
2017-10-29 23:25:06belopolskysetmessages: + msg305198
2017-10-29 22:42:22serhiy.storchakasetmessages: + msg305197
2017-10-29 22:15:55belopolskysetmessages: + msg305196
2017-10-29 22:13:26belopolskysetmessages: + msg305195
2017-10-29 22:09:53serhiy.storchakasetmessages: + msg305194
2017-10-29 21:58:37belopolskysetmessages: + msg305193
2017-10-29 21:10:45serhiy.storchakacreate