[doc] documentation incorrectly says that “datetime.timestamp” calls “mktime”

[serhiy-storchaka]

BPO	31894
Nosy	@abalkin, @vadmium, @serhiy-storchaka

^{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 = None
created_at = <Date 2017-10-29.21:10:45.427>
labels = ['3.11', 'type-bug', '3.9', '3.10', 'docs']
title = '[doc] documentation incorrectly says that \xe2\x80\x9cdatetime.timestamp\xe2\x80\x9d calls \xe2\x80\x9cmktime\xe2\x80\x9d'
updated_at = <Date 2022-01-16.23:40:49.205>
user = 'https://github.com/serhiy-storchaka'

bugs.python.org fields:

activity = <Date 2022-01-16.23:40:49.205>
actor = 'iritkatriel'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2017-10-29.21:10:45.427>
creator = 'serhiy.storchaka'
dependencies = []
files = []
hgrepos = []
issue_num = 31894
keywords = []
message_count = 9.0
messages = ['305192', '305193', '305194', '305195', '305196', '305197', '305198', '305201', '305203']
nosy_count = 4.0
nosy_names = ['belopolsky', 'docs@python', 'martin.panter', 'serhiy.storchaka']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue31894'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']

Linked PRs

• gh-76075: Correct datetime.timestamp documentation #131202
• [3.13] gh-76075: Correct datetime.timestamp documentation (GH-131202) #155284
• [3.14] gh-76075: Correct datetime.timestamp documentation (GH-131202) #155285

[serhiy-storchaka]

$ ./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).

[abalkin]

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?

[serhiy-storchaka]

$ 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)

[abalkin]

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)

[abalkin]

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)

[serhiy-storchaka]

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?

[abalkin]

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.

[vadmium]

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 bpo-29097, probing a date before 1970?

[abalkin]

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 bpo-29097, probing a date before 1970?

----------
nosy: +martin.panter

---

Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue31894\>

---