From e2e178e081a621d2c1fd8ceb65ce7735b3036def Mon Sep 17 00:00:00 2001 From: Alexander Belopolsky Date: Sun, 1 Mar 2015 14:52:07 -0500 Subject: 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 7a9f93c..f82f425 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. + + To get an aware :class:`.datetime` object, call :meth:`fromtimestamp`:: + + datetime.fromtimestamp(timestamp, timezone.utc) + + On the POSIX compliant platforms, it is equivalent to the following + expression:: - On the POSIX compliant platforms, ``utcfromtimestamp(timestamp)`` - is equivalent to the following expression:: + datetime(1970, 1, 1, tzinfo=timezone.utc) + timedelta(seconds=timestamp) - datetime(1970, 1, 1) + 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 2768e9b..de57472 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 701c587..09285d9 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, -- cgit v0.12