[Python-checkins] bpo-37488 : Document a warning for datetime.utcnow() and utcfromtimestamp() (GH-15773)
Miss Islington (bot)
webhook-mailer at python.org
Thu Sep 12 10:55:52 EDT 2019
https://github.com/python/cpython/commit/307c5fe9428b175ff3871a1fdc19bdd7562cfee5
commit: 307c5fe9428b175ff3871a1fdc19bdd7562cfee5
branch: 3.8
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2019-09-12T07:55:48-07:00
summary:
bpo-37488 : Document a warning for datetime.utcnow() and utcfromtimestamp() (GH-15773)
https://bugs.python.org/issue37488
Automerge-Triggered-By: @pganssle
(cherry picked from commit 1a53c785e62e00bad87ae19466c3a32ebcebb915)
Co-authored-by: Joannah Nanjekye <33177550+nanjekyejoannah at users.noreply.github.com>
files:
A Misc/NEWS.d/next/Library/2019-09-11-11-44-16.bpo-37488.S8CJUL.rst
M Doc/library/datetime.rst
diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index 882d4e16e1f6..b1e1b25691d8 100644
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -862,13 +862,10 @@ Other constructors, all class methods:
(for example, this may be possible on platforms supplying the C
:c:func:`gettimeofday` function).
- If *tz* is not ``None``, it must be an instance of a :class:`tzinfo` subclass, and the
- current date and time are converted to *tz*’s time zone. In this case the
- result is equivalent to::
-
- tz.fromutc(datetime.utcnow().replace(tzinfo=tz))
+ If *tz* is not ``None``, it must be an instance of a :class:`tzinfo` subclass,
+ and the current date and time are converted to *tz*’s time zone.
- See also :meth:`today`, :meth:`utcnow`.
+ This function is preferred over :meth:`today` and :meth:`utcnow`.
.. classmethod:: datetime.utcnow()
@@ -879,6 +876,14 @@ Other constructors, all class methods:
:class:`.datetime` object. An aware current UTC datetime can be obtained by
calling ``datetime.now(timezone.utc)``. See also :meth:`now`.
+ .. warning::
+
+ Because naive ``datetime`` objects are treated by many ``datetime`` methods
+ as local times, it is preferred to use aware datetimes to represent times
+ in UTC. As such, the recommended way to create an object representing the
+ current time in UTC by calling ``datetime.now(timezone.utc)``.
+
+
.. classmethod:: datetime.fromtimestamp(timestamp, tz=None)
Return the local date and time corresponding to the POSIX timestamp, such as is
@@ -889,10 +894,6 @@ Other constructors, all class methods:
If *tz* is not ``None``, it must be an instance of a :class:`tzinfo` subclass, and the
timestamp is converted to *tz*’s time zone.
- In this case the result is equivalent to::
-
- tz.fromutc(datetime.utcfromtimestamp(timestamp).replace(tzinfo=tz))
-
:meth:`fromtimestamp` may raise :exc:`OverflowError`, if the timestamp is out of
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
@@ -901,7 +902,8 @@ Other constructors, all class methods:
1970 through 2038. Note that on non-POSIX systems that include leap seconds in
their notion of a timestamp, leap seconds are ignored by :meth:`fromtimestamp`,
and then it's possible to have two timestamps differing by a second that yield
- identical :class:`.datetime` objects. See also :meth:`utcfromtimestamp`.
+ identical :class:`.datetime` objects. This method is preferred over
+ :meth:`utcfromtimestamp`.
.. versionchanged:: 3.3
Raise :exc:`OverflowError` instead of :exc:`ValueError` if the timestamp
@@ -935,6 +937,14 @@ Other constructors, all class methods:
except the latter formula always supports the full years range: between
:const:`MINYEAR` and :const:`MAXYEAR` inclusive.
+ .. warning::
+
+ Because naive ``datetime`` objects are treated by many ``datetime`` methods
+ as local times, it is preferred to use aware datetimes to represent times
+ in UTC. As such, the recommended way to create an object representing a
+ specific timestamp in UTC by calling
+ ``datetime.fromtimestamp(timestamp, tz=timezone.utc)``.
+
.. versionchanged:: 3.3
Raise :exc:`OverflowError` instead of :exc:`ValueError` if the timestamp
is out of the range of values supported by the platform C
@@ -1322,6 +1332,14 @@ Instance methods:
``MINYEAR`` or ``MAXYEAR`` and UTC adjustment spills over a year
boundary.
+ .. warning::
+
+ Because naive ``datetime`` objects are treated by many ``datetime`` methods
+ as local times, it is preferred to use aware datetimes to represent times
+ in UTC; as a result, using ``utcfromtimetuple`` may give misleading
+ results. If you have a naive ``datetime`` representing UTC, use
+ ``datetime.replace(tzinfo=timezone.utc)`` to make it aware, at which point
+ you can use :meth:`.datetime.timetuple`.
.. method:: datetime.toordinal()
@@ -1500,7 +1518,7 @@ Examples of working with :class:`~datetime.datetime` objects:
.. doctest::
- >>> from datetime import datetime, date, time
+ >>> from datetime import datetime, date, time, timezone
>>> # Using datetime.combine()
>>> d = date(2005, 7, 14)
@@ -1508,11 +1526,11 @@ Examples of working with :class:`~datetime.datetime` objects:
>>> datetime.combine(d, t)
datetime.datetime(2005, 7, 14, 12, 30)
- >>> # Using datetime.now() or datetime.utcnow()
+ >>> # Using datetime.now()
>>> datetime.now() # doctest: +SKIP
datetime.datetime(2007, 12, 6, 16, 29, 43, 79043) # GMT +1
- >>> datetime.utcnow() # doctest: +SKIP
- datetime.datetime(2007, 12, 6, 15, 29, 43, 79060)
+ >>> datetime.now(timezone.utc) # doctest: +SKIP
+ datetime.datetime(2007, 12, 6, 15, 29, 43, 79060, tzinfo=datetime.timezone.utc)
>>> # Using datetime.strptime()
>>> dt = datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M")
@@ -1616,7 +1634,7 @@ Usage of ``KabulTz`` from above::
datetime.datetime(2006, 6, 14, 8, 30, tzinfo=datetime.timezone.utc)
>>> dt2
datetime.datetime(2006, 6, 14, 13, 0, tzinfo=KabulTz())
- >>> dt2.utctimetuple() == dt3.utctimetuple()
+ >>> dt2 == dt3
True
.. _datetime-time:
diff --git a/Misc/NEWS.d/next/Library/2019-09-11-11-44-16.bpo-37488.S8CJUL.rst b/Misc/NEWS.d/next/Library/2019-09-11-11-44-16.bpo-37488.S8CJUL.rst
new file mode 100644
index 000000000000..4f9041502a91
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2019-09-11-11-44-16.bpo-37488.S8CJUL.rst
@@ -0,0 +1 @@
+Add warning to :meth:`datetime.utctimetuple`, :meth:`datetime.utcnow` and :meth:`datetime.utcfromtimestamp` .
\ No newline at end of file
More information about the Python-checkins
mailing list