bpo-31327: Update time documentation to reflect possible errors #31460

slateny · 2022-02-21T04:37:02Z

As per the comments, this mirrors the datetime documentation.

>>> import time
>>> time.localtime(999999999999999999999)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
OverflowError: timestamp out of range for platform time_t
>>> time.localtime(-3600)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
OSError: [Errno 22] Invalid argument

https://bugs.python.org/issue31327

Automerge-Triggered-By: GH:pganssle

zooba

Approved with the CI fixes

Doc/library/time.rst

slateny · 2022-02-27T04:40:23Z

@zooba Fixed trailing spaces, could you take another look?

akulakov · 2022-02-27T05:33:37Z

Doc/library/time.rst

+   the range of values supported by the platform C :c:func:`localtime` or
+   :c:func:`gmtime` functions, and :exc:`OSError` on :c:func:`localtime` or
+   :c:func:`gmtime` failure.
+   It's common for this to be restricted to years in


Suggested change

It's common for this to be restricted to years in

It's common for this to be restricted to years in the range of

I just copied-pasted from datetime, but if we're to change the wording then there's some shorter options as well:

"... to be restricted to the years 1970 through 2038."

or

"... years in the range 1970 to 2038."

Though difficult for me to say which one of the three is the best here.

pganssle

Looks good, thanks @slateny!

miss-islington · 2022-03-11T19:05:54Z

Thanks @slateny for the PR 🌮🎉.. I'm working now to backport this PR to: 3.8, 3.9, 3.10.
🐍🍒⛏🤖

bedevere-bot · 2022-03-11T19:06:19Z

GH-31825 is a backport of this pull request to the 3.10 branch.

…onGH-31460) As per the comments, this mirrors the [datetime documentation](https://docs.python.org/3/library/datetime.htmlGH-datetime.datetime.fromtimestamp). ``` >>> import time >>> time.localtime(999999999999999999999) Traceback (most recent call last): File "<stdin>", line 1, in <module> OverflowError: timestamp out of range for platform time_t >>> time.localtime(-3600) Traceback (most recent call last): File "<stdin>", line 1, in <module> OSError: [Errno 22] Invalid argument ``` (cherry picked from commit c83fc9c) Co-authored-by: slateny <46876382+slateny@users.noreply.github.com>

bedevere-bot · 2022-03-11T19:06:23Z

GH-31826 is a backport of this pull request to the 3.9 branch.

…onGH-31460) As per the comments, this mirrors the [datetime documentation](https://docs.python.org/3/library/datetime.htmlGH-datetime.datetime.fromtimestamp). ``` >>> import time >>> time.localtime(999999999999999999999) Traceback (most recent call last): File "<stdin>", line 1, in <module> OverflowError: timestamp out of range for platform time_t >>> time.localtime(-3600) Traceback (most recent call last): File "<stdin>", line 1, in <module> OSError: [Errno 22] Invalid argument ``` (cherry picked from commit c83fc9c) Co-authored-by: slateny <46876382+slateny@users.noreply.github.com>

…1460) As per the comments, this mirrors the [datetime documentation](https://docs.python.org/3/library/datetime.htmlGH-datetime.datetime.fromtimestamp). ``` >>> import time >>> time.localtime(999999999999999999999) Traceback (most recent call last): File "<stdin>", line 1, in <module> OverflowError: timestamp out of range for platform time_t >>> time.localtime(-3600) Traceback (most recent call last): File "<stdin>", line 1, in <module> OSError: [Errno 22] Invalid argument ``` (cherry picked from commit c83fc9c) Co-authored-by: slateny <46876382+slateny@users.noreply.github.com>

iritkatriel · 2022-03-13T15:13:54Z

@pganssle Did you intend to add the backport to 3.8 label?

pganssle · 2022-03-14T14:23:12Z

@iritkatriel It's a doc fix, not sure how far we usually backport those since they are not critical bit also not likely to cause any problems, so I went with backporting as far as it would go. If you think there's no reason to go that far back I don't feel strongly about it at all.

iritkatriel · 2022-03-14T14:52:16Z

@iritkatriel It's a doc fix, not sure how far we usually backport those since they are not critical bit also not likely to cause any problems, so I went with backporting as far as it would go. If you think there's no reason to go that far back I don't feel strongly about it at all.

I don’t have a view on this (and I didn’t know we backport doc fixes to 3.8). In this particular case it seems like the 3.8 backport did not happen - maybe the bots don’t do them based on labels?

…1460) (GH-31827) As per the comments, this mirrors the [datetime documentation](https://docs.python.org/3/library/datetime.htmlGH-datetime.datetime.fromtimestamp). ``` >>> import time >>> time.localtime(999999999999999999999) Traceback (most recent call last): File "<stdin>", line 1, in <module> OverflowError: timestamp out of range for platform time_t >>> time.localtime(-3600) Traceback (most recent call last): File "<stdin>", line 1, in <module> OSError: [Errno 22] Invalid argument ``` (cherry picked from commit c83fc9c) Co-authored-by: slateny <46876382+slateny@users.noreply.github.com>

…onGH-31460) As per the comments, this mirrors the [datetime documentation](https://docs.python.org/3/library/datetime.html#datetime.datetime.fromtimestamp). ``` >>> import time >>> time.localtime(999999999999999999999) Traceback (most recent call last): File "<stdin>", line 1, in <module> OverflowError: timestamp out of range for platform time_t >>> time.localtime(-3600) Traceback (most recent call last): File "<stdin>", line 1, in <module> OSError: [Errno 22] Invalid argument ```

slateny requested review from pganssle and abalkin as code owners Feb 21, 2022

bedevere-bot added the awaiting review label Feb 21, 2022

the-knights-who-say-ni added the CLA signed label Feb 21, 2022

bedevere-bot added the docs label Feb 21, 2022

zooba added the skip news label Feb 21, 2022

zooba reviewed Feb 21, 2022

View changes

Doc/library/time.rst Outdated Show resolved Hide resolved

Doc/library/time.rst Outdated Show resolved Hide resolved

akulakov reviewed Feb 27, 2022

View changes

slateny changed the title ~~bpo-31327: Updated time documentation to reflect possible errors~~ bpo-31327: Update time documentation to reflect possible errors Mar 4, 2022

slateny added 2 commits Mar 11, 2022

Update time.rst

8c5dbec

Remove trailing whitespace + indentation on empty line

b847053

pganssle added needs backport to 3.8 needs backport to 3.9 needs backport to 3.10 labels Mar 11, 2022

Tweak wording

70004a7

pganssle force-pushed the s/time branch from bc89594 to 70004a7 Compare Mar 11, 2022

pganssle approved these changes Mar 11, 2022

View changes

bedevere-bot added awaiting merge and removed awaiting review labels Mar 11, 2022

pganssle added the 🤖 automerge label Mar 11, 2022

miss-islington merged commit c83fc9c into python:main Mar 11, 2022
12 checks passed

bedevere-bot removed awaiting merge needs backport to 3.10 labels Mar 11, 2022

bedevere-bot removed the needs backport to 3.9 label Mar 11, 2022

slateny deleted the s/time branch Mar 12, 2022

iritkatriel mentioned this pull request Mar 16, 2022

[3.8] bpo-31327: Update time documentation to reflect possible errors (GH-31460) #31827

Merged

python / cpython Public

bpo-31327: Update time documentation to reflect possible errors #31460

bpo-31327: Update time documentation to reflect possible errors #31460

slateny commented Feb 21, 2022 •

edited by miss-islington

zooba left a comment

slateny commented Feb 27, 2022

akulakov Feb 27, 2022

slateny Feb 28, 2022

pganssle left a comment

miss-islington commented Mar 11, 2022

bedevere-bot commented Mar 11, 2022

bedevere-bot commented Mar 11, 2022

iritkatriel commented Mar 13, 2022

pganssle commented Mar 14, 2022

iritkatriel commented Mar 14, 2022

	It's common for this to be restricted to years in
	It's common for this to be restricted to years in the range of

python / cpython Public

bpo-31327: Update time documentation to reflect possible errors #31460

bpo-31327: Update time documentation to reflect possible errors #31460

Conversation

slateny commented Feb 21, 2022 • edited by miss-islington

zooba left a comment

slateny commented Feb 27, 2022

akulakov Feb 27, 2022

Choose a reason for hiding this comment

slateny Feb 28, 2022

Choose a reason for hiding this comment

pganssle left a comment

miss-islington commented Mar 11, 2022

bedevere-bot commented Mar 11, 2022

bedevere-bot commented Mar 11, 2022

iritkatriel commented Mar 13, 2022

pganssle commented Mar 14, 2022

iritkatriel commented Mar 14, 2022

slateny commented Feb 21, 2022 •

edited by miss-islington