From e2e178e081a621d2c1fd8ceb65ce7735b3036def Mon Sep 17 00:00:00 2001
From: Alexander Belopolsky <alexander.belopolsky@gmail.com>
Date: Sun, 1 Mar 2015 14:52:07 -0500
Subject: [PATCH] Closes issue #22791: Improved datetime from timestamp methods
 documentation.

Original patch by Akira Li.
---
 Doc/library/datetime.rst  | 16 +++++++++++-----
 Lib/datetime.py           |  2 +-
 Modules/_datetimemodule.c |  3 +--
 3 files changed, 13 insertions(+), 8 deletions(-)

diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index 7a9f93cd238..f82f425ac40 100644
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -759,13 +759,19 @@ Other constructors, all class methods:
    :attr:`tzinfo` ``None``. This may raise :exc:`OverflowError`, if the timestamp is
    out of the range of values supported by the platform C :c:func:`gmtime` function,
    and :exc:`OSError` on :c:func:`gmtime` failure.
-   It's common for this to be restricted to years in 1970 through 2038. See also
-   :meth:`fromtimestamp`.
+   It's common for this to be restricted to years in 1970 through 2038.
 
-   On the POSIX compliant platforms, ``utcfromtimestamp(timestamp)``
-   is equivalent to the following expression::
+   To get an aware :class:`.datetime` object, call :meth:`fromtimestamp`::
 
-     datetime(1970, 1, 1) + timedelta(seconds=timestamp)
+     datetime.fromtimestamp(timestamp, timezone.utc)
+
+   On the POSIX compliant platforms, it is equivalent to the following
+   expression::
+
+     datetime(1970, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=timestamp)
+
+   except the latter formula always supports the full years range: between
+   :const:`MINYEAR` and :const:`MAXYEAR` inclusive.
 
    .. versionchanged:: 3.3
       Raise :exc:`OverflowError` instead of :exc:`ValueError` if the timestamp
diff --git a/Lib/datetime.py b/Lib/datetime.py
index 2768e9bffd2..de574724b86 100644
--- a/Lib/datetime.py
+++ b/Lib/datetime.py
@@ -1393,7 +1393,7 @@ class datetime(date):
 
     @classmethod
     def utcfromtimestamp(cls, t):
-        "Construct a UTC datetime from a POSIX timestamp (like time.time())."
+        """Construct a naive UTC datetime from a POSIX timestamp."""
         t, frac = divmod(t, 1.0)
         us = int(frac * 1e6)
 
diff --git a/Modules/_datetimemodule.c b/Modules/_datetimemodule.c
index 701c58773b5..09285d919de 100644
--- a/Modules/_datetimemodule.c
+++ b/Modules/_datetimemodule.c
@@ -5020,8 +5020,7 @@ static PyMethodDef datetime_methods[] = {
 
     {"utcfromtimestamp", (PyCFunction)datetime_utcfromtimestamp,
      METH_VARARGS | METH_CLASS,
-     PyDoc_STR("timestamp -> UTC datetime from a POSIX timestamp "
-               "(like time.time()).")},
+     PyDoc_STR("Construct a naive UTC datetime from a POSIX timestamp.")},
 
     {"strptime", (PyCFunction)datetime_strptime,
      METH_VARARGS | METH_CLASS,