From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Wed, 16 Mar 2022 10:12:50 +0000 (-0700)
Subject: bpo-31327: Update time documentation to reflect possible errors (GH-31460) (GH-31827)
X-Git-Tag: v3.8.13~1
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=4d8e08b21ce5d2cc08da82cf9f3ca50d9617cbdc;p=thirdparty%2FPython%2Fcpython.git

bpo-31327: Update time documentation to reflect possible errors (GH-31460) (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 c83fc9c02c9846ec3a2d0123999c98e02f00b3f5)

Co-authored-by: slateny <46876382+slateny@users.noreply.github.com>
---

diff --git a/Doc/library/time.rst b/Doc/library/time.rst
index e8bb9ccb8e77..9cdef1adec97 100644
--- a/Doc/library/time.rst
+++ b/Doc/library/time.rst
@@ -253,6 +253,12 @@ Functions
    :const:`None`, the current time as returned by :func:`.time` is used.  The dst
    flag is set to ``1`` when DST applies to the given time.
 
+   :func:`localtime` may raise :exc:`OverflowError`, if the timestamp is
+   outside 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
+   between 1970 and 2038.
+
 
 .. function:: mktime(t)