GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing github.com — bpo-37488 : Document a warning for datetime.utcnow() and utcfromtimestamp() by nanjekyejoannah · Pull Request #15773 · python/cpython

bpo-37488 : Document a warning for datetime.utcnow() and utcfromtimestamp() #15773

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

miss-islington merged 1 commit into python:master from nanjekyejoannah:issue37488

Sep 11, 2019

Uh oh!

There was an error while loading. Please reload this page.

Merged

bpo-37488 : Document a warning for datetime.utcnow() and utcfromtimestamp() #15773

Show file tree

Hide file tree

Changes from all commits

Commits

Show all changes

1 commit

Select commit

84887b0

Add warning notes in the documentation for utc* methods

nanjekyejoannah Sep 11, 2019

File filter

Filter by extension .rst (2) All 1 file type selected

Viewed files

Clear filters

Conversations

Failed to load comments.

Uh oh!

There was an error while loading. Please reload this page.

Jump to

Jump to file

Failed to load files.

Uh oh!

There was an error while loading. Please reload this page.

Diff view

Unified

Split

Hide whitespace

Diff view

Unified

Split

Hide whitespace

There are no files selected for viewing

50 changes: 34 additions & 16 deletions 50 Doc/library/datetime.rst

Show comments

View file

Open in desktop

Original file line number	Diff line number	Diff line change
Expand Up		@@ -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()
Expand All		@@ -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
Expand All		@@ -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
Expand All		@@ -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
Expand Down Expand Up		@@ -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
Expand Down Expand Up		@@ -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()

Expand Down Expand Up		@@ -1500,19 +1518,19 @@ 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)
		>>> t = time(12, 30)
		>>> 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")
Expand Down Expand Up		@@ -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:
Expand Down

1 change: 1 addition & 0 deletions 1 Misc/NEWS.d/next/Library/2019-09-11-11-44-16.bpo-37488.S8CJUL.rst

Show comments

View file

Open in desktop

Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Add warning to :meth:`datetime.utctimetuple`, :meth:`datetime.utcnow` and :meth:`datetime.utcfromtimestamp` .

Add this suggestion to a batch that can be applied as a single commit. This suggestion is invalid because no changes were made to the code. Suggestions cannot be applied while the pull request is closed. Suggestions cannot be applied while viewing a subset of changes. Only one suggestion per line can be applied in a batch. Add this suggestion to a batch that can be applied as a single commit. Applying suggestions on deleted lines is not supported. You must change the existing code in this line in order to create a valid suggestion. Outdated suggestions cannot be applied. This suggestion has been applied or marked resolved. Suggestions cannot be applied from pending reviews. Suggestions cannot be applied on multi-line comments. Suggestions cannot be applied while the pull request is queued to merge. Suggestion cannot be applied right now. Please check back later.

You are visitor 01402503 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.