classification
Title: [doc] Add example of platform-specific support for negative timestamps to the time doc
Type: enhancement Stage: needs patch
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, jerrykramskoy, louielu, matrixise, p-ganssle, steve.dower, tim.peters
Priority: normal Keywords: easy

Created on 2017-09-01 17:24 by jerrykramskoy, last changed 2022-01-07 00:16 by iritkatriel.

Messages (13)
msg301143 - (view) Author: Jerry Kramskoy (jerrykramskoy) Date: 2017-09-01 17:24
Running python 3.6.2 on Windows 10.

The following method causes presents a timetstamp value of -3600 (i.e. DST adjustment of one hour) which causes time.localtime() to raise an OS Errno 22.


    def _naive_is_dst(self, dt):
        timestamp = _datetime_to_timestamp(dt)
        return time.localtime(timestamp + time.timezone).tm_isdst



Reproduce with python shell...

import time
z=time.localtime(-3600)
Traceback (most recent call last):
  Python Shell, prompt 7, line 1
builtins.OSError: [Errno 22] Invalid argument



The documentation doesn't specify a legal value range for input to localtime.


Unfortunately,this causes AWS boto3 support for dynamodb to crash.

Cheers, Jerry
msg301219 - (view) Author: Louie Lu (louielu) * Date: 2017-09-04 12:46
Using macOS and Linux can't reproduce this problem, both platform
return this output:

>>> import time
>>> time.localtime(-3600)
time.struct_time(tm_year=1970, tm_mon=1, tm_mday=1, tm_hour=7, tm_min=0, tm_sec=0, tm_wday=3, tm_yday=1, tm_isdst=0)
msg304152 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2017-10-11 15:39
Hi Steve, I have added you on this issue because it's related to Windows.

Maybe you could check it.
msg304154 - (view) Author: Tim Peters (tim.peters) * (Python committer) Date: 2017-10-11 15:48
The docs for the `time` module say:

"""
Although this module is always available, not all functions are available on all platforms. Most of the functions defined in this module call platform C library functions with the same name. It may sometimes be helpful to consult the platform documentation, because the semantics of these functions varies among platforms.
"""

The Windows `localtime()` simply doesn't support dates before the epoch:

https://msdn.microsoft.com/en-us/library/aa246456(v=vs.60).aspx
msg304155 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2017-10-11 16:00
Thank you Tim,

In this case, the documentation seems to be correct, maybe we could close this issue because it's independent of Python.

What's your opinion on this point?

Close it or Improve the documentation?
msg304159 - (view) Author: Tim Peters (tim.peters) * (Python committer) Date: 2017-10-11 16:22
Since this is a pretty common gotcha, I'd prefer to add it as an example to the text I already quoted; e.g., add:

"""
For example, the native Windows C libraries do not support times before the epoch, and `localtime(n)` for negative `n` raises `OSError` on Windows.
"""
msg304160 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2017-10-11 16:24
Thank you, I will provide a PR for this issue and close it once it's over.
msg304161 - (view) Author: Tim Peters (tim.peters) * (Python committer) Date: 2017-10-11 16:33
I'll just add that it may be a different issue to argue about how `_naive_is_dst()` is implemented.
msg304162 - (view) Author: Alexander Belopolsky (belopolsky) * (Python committer) Date: 2017-10-11 16:52
Is this similar to issue 29097?
msg339018 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2019-03-28 08:27
nosy: -matrixise
msg339019 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2019-03-28 08:28
----------
nosy: -matrixise
msg339020 - (view) Author: Stéphane Wirtel (matrixise) * (Python committer) Date: 2019-03-28 08:29
sorry for the spam, I wanted to be removed from the noisy list via the mail gateway but my two tests did not work :/
msg339042 - (view) Author: Paul Ganssle (p-ganssle) * (Python committer) Date: 2019-03-28 13:52
Can we change the title of this to something like, "Add example of platform-specific support for negative timestamps to the time documentation"?

That might be a bit wordy, but as it is now, this looks like it's reporting a bug in dateutil, which is not part of the standard library, which may be confusing people looking for something to solve.

As for the meat of the documentation change, I think we can adapt the wording from `datetime.fromtimestamp`, which actually has a very similar example called out: https://docs.python.org/3.7/library/datetime.html#datetime.datetime.fromtimestamp

> fromtimestamp() may raise OverflowError, if the timestamp is out of the range of values supported by the platform C localtime() or gmtime() functions, and OSError on localtime() or gmtime() failure. It’s common for this to be restricted to years in 1970 through 2038.
History
Date User Action Args
2022-01-07 00:16:13iritkatrielsetkeywords: + easy
title: bug in dateutil\tz\tz.py -> [doc] Add example of platform-specific support for negative timestamps to the time doc
versions: + Python 3.9, Python 3.10, Python 3.11, - Python 3.7, Python 3.8
2019-03-28 13:52:04p-gansslesetmessages: + msg339042
2019-03-28 08:29:22matrixisesetmessages: + msg339020
2019-03-28 08:28:43matrixisesetmessages: + msg339019
2019-03-28 08:27:52matrixisesetmessages: + msg339018
2019-03-27 23:00:50xtreaksetnosy: + p-ganssle
2019-03-27 22:49:07cheryl.sabellasetstage: needs patch
versions: + Python 3.7, Python 3.8, - Python 3.6
2017-10-11 16:52:47belopolskysetmessages: + msg304162
2017-10-11 16:33:41tim.peterssetnosy: + belopolsky
messages: + msg304161
2017-10-11 16:24:17matrixisesetmessages: + msg304160
2017-10-11 16:22:20tim.peterssetnosy: + docs@python
messages: + msg304159

assignee: docs@python
components: + Documentation, - Library (Lib)
type: crash -> enhancement
2017-10-11 16:00:50matrixisesetmessages: + msg304155
2017-10-11 15:48:49tim.peterssetnosy: + tim.peters
messages: + msg304154
2017-10-11 15:39:49matrixisesetnosy: + matrixise, steve.dower
messages: + msg304152
2017-09-04 12:46:51louielusetnosy: + louielu
messages: + msg301219
2017-09-01 17:24:09jerrykramskoycreate