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.

Title: [doc] Add example of platform-specific support for negative timestamps to the time doc
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: belopolsky, docs@python, jerrykramskoy, louielu, lukasz.langa, matrixise, miss-islington, p-ganssle, slateny, steve.dower, tim.peters, vidhya
Priority: normal Keywords: easy, patch

Created on 2017-09-01 17:24 by jerrykramskoy, last changed 2022-04-11 14:58 by admin. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 31460 merged slateny, 2022-02-21 04:37
PR 31825 merged miss-islington, 2022-03-11 19:06
PR 31826 merged miss-islington, 2022-03-11 19:06
PR 31827 merged miss-islington, 2022-03-11 19:06
Messages (18)
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
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:
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:

> 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.
msg413754 - (view) Author: Vidhya (vidhya) * Date: 2022-02-22 23:03
[Entry level contributor seeking guidance]If this is not yet fixed, I can work on this. Please let me know.
msg414931 - (view) Author: miss-islington (miss-islington) Date: 2022-03-11 19:05
New changeset c83fc9c02c9846ec3a2d0123999c98e02f00b3f5 by slateny in branch 'main':
bpo-31327: Update time documentation to reflect possible errors (GH-31460)
msg414933 - (view) Author: miss-islington (miss-islington) Date: 2022-03-11 19:28
New changeset 30d80213ae305bd0f0ed6bec7a0dff3e97b1c321 by Miss Islington (bot) in branch '3.9':
bpo-31327: Update time documentation to reflect possible errors (GH-31460)
msg414934 - (view) Author: miss-islington (miss-islington) Date: 2022-03-11 19:29
New changeset b35b36e106152245fe68880f4073fd99ec17f65d by Miss Islington (bot) in branch '3.10':
bpo-31327: Update time documentation to reflect possible errors (GH-31460)
msg415332 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2022-03-16 10:12
New changeset 4d8e08b21ce5d2cc08da82cf9f3ca50d9617cbdc by Miss Islington (bot) in branch '3.8':
bpo-31327: Update time documentation to reflect possible errors (GH-31460) (GH-31827)
Date User Action Args
2022-04-11 14:58:51adminsetgithub: 75508
2022-03-16 10:23:07iritkatrielsetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2022-03-16 10:12:59lukasz.langasetnosy: + lukasz.langa
messages: + msg415332
2022-03-11 19:29:55miss-islingtonsetmessages: + msg414934
2022-03-11 19:28:47miss-islingtonsetmessages: + msg414933
2022-03-11 19:06:22miss-islingtonsetpull_requests: + pull_request29924
2022-03-11 19:06:17miss-islingtonsetpull_requests: + pull_request29923
2022-03-11 19:06:13miss-islingtonsetpull_requests: + pull_request29922
2022-03-11 19:05:58miss-islingtonsetnosy: + miss-islington
messages: + msg414931
2022-02-22 23:03:59vidhyasetnosy: + vidhya
messages: + msg413754
2022-02-21 04:37:05slatenysetkeywords: + patch
nosy: + slateny

pull_requests: + pull_request29589
stage: needs patch -> patch review
2022-01-07 00:16:13iritkatrielsetkeywords: + easy
title: bug in dateutil\tz\ -> [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