From 28b8a5b6714ecaa7165484c96dca5ede104ac153 Mon Sep 17 00:00:00 2001 From: joooeey Date: Sun, 10 May 2020 18:46:39 +0200 Subject: [PATCH 1/2] DOC: timezone warning for dates beyond TODAY introducing a suggestion discussed in PR #33863 : Added a warning in the user guide that timezone conversion on future dates is inherently unreliable. --- doc/source/user_guide/timeseries.rst | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/doc/source/user_guide/timeseries.rst b/doc/source/user_guide/timeseries.rst index a4e458032b787..908b054a5d47d 100644 --- a/doc/source/user_guide/timeseries.rst +++ b/doc/source/user_guide/timeseries.rst @@ -2314,13 +2314,24 @@ you can use the ``tz_convert`` method. Instead, the datetime needs to be localized using the ``localize`` method on the ``pytz`` time zone object. +.. warning:: + + Be aware that for times in the future, correct conversion between time zones + (and UTC) cannot be guaranteed by any time zone library. Sometimes the rules + governing a timezone's offset from UTC are changed. Authorities usually + announce such changes many months in advance but there have been examples of + much shorter lead times such as when Morocco announced just two days before + the planned switch from summer time to winter time in 2018 that the country + would stay on summer time permanently. Furthermore, the databases that + Pandas relies on may need some time to record planned changes to timezone + offsets. + .. warning:: If you are using dates beyond 2038-01-18, due to current deficiencies in the underlying libraries caused by the year 2038 problem, daylight saving time (DST) adjustments to timezone aware dates will not be applied. If and when the underlying libraries are fixed, - the DST transitions will be applied. It should be noted though, that time zone data for far future time zones - are likely to be inaccurate, as they are simple extrapolations of the current set of (regularly revised) rules. + the DST transitions will be applied. For example, for two dates that are in British Summer Time (and so would normally be GMT+1), both the following asserts evaluate as true: From 2b584ab06358b14c0848042157e24abca6edb99d Mon Sep 17 00:00:00 2001 From: joooeey Date: Fri, 22 May 2020 13:01:55 +0200 Subject: [PATCH 2/2] shorter warning text --- doc/source/user_guide/timeseries.rst | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/doc/source/user_guide/timeseries.rst b/doc/source/user_guide/timeseries.rst index 908b054a5d47d..630716f7a7396 100644 --- a/doc/source/user_guide/timeseries.rst +++ b/doc/source/user_guide/timeseries.rst @@ -2317,14 +2317,8 @@ you can use the ``tz_convert`` method. .. warning:: Be aware that for times in the future, correct conversion between time zones - (and UTC) cannot be guaranteed by any time zone library. Sometimes the rules - governing a timezone's offset from UTC are changed. Authorities usually - announce such changes many months in advance but there have been examples of - much shorter lead times such as when Morocco announced just two days before - the planned switch from summer time to winter time in 2018 that the country - would stay on summer time permanently. Furthermore, the databases that - Pandas relies on may need some time to record planned changes to timezone - offsets. + (and UTC) cannot be guaranteed by any time zone library because a timezone's + offset from UTC may be changed by the respective government. .. warning::