Skip to content

DOC: timezone warning for DST beyond 2038-01-18 #33863

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.

Sign up for GitHub

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
merged 5 commits into from
May 10, 2020
Merged

DOC: timezone warning for DST beyond 2038-01-18 #33863

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
309a822
DOC: timezone warning for DST beyond 2038-01-19
Apr 29, 2020
83846bb
Merge remote-tracking branch 'upstream/master' into docs_timezone_war…
Apr 29, 2020
42d827f
fixes rst alignment and line length errors
Apr 29, 2020
16f5c6e
DOC: further textual changes
telferm57 May 1, 2020
3186296
DOC: delints line length issues
telferm57 May 1, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions doc/source/user_guide/timeseries.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2265,6 +2265,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::

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.

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:

.. ipython:: python

d_2037 = '2037-03-31T010101'
d_2038 = '2038-03-31T010101'
DST = 'Europe/London'
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is this called DST instead of LON or some other thing?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

because I am focusing on DST transitions - just happen to have picked London as that's local

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

People will think it means "this is the Daylight Saving Time zone". You don't have to call it LON, but you should at least call it ZONE or something.

assert pd.Timestamp(d_2037, tz=DST) != pd.Timestamp(d_2037, tz='GMT')
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This does not seem right to me.

If you're going to keep the example (and I'm not convinced you should, especially since it's right around when a DST transition happens - if anything you should move it deep into summer to guarantee that the fluctuations aren't just due to the transition moving around), it would be better to make assertions about the thing you care about.

assert pd.Timestamp(d_2037, tz=LON).tzname() != "GMT"
assert pd.Timestamp(d_2038, tz=LON).tzname() != "GMT"

Even better, though, would be a repr:

>>> pd.Timestamp(d_2037, tz=LON).tzname()
'BST'
>>> pd.Timestamp(d_2037, tz=LON).tzname()
'GMT'

Copy link
Contributor Author

@telferm57 telferm57 May 5, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree summer date would be clearer, but not so sure whether your examples are clearer, or whether using BST (local zone name for DST) is clearer for a global audience ... hmmm

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It doesn't really matter what offsets you use there, pick anything. The important thing is that it's obvious that they are different on the same date in different years, and that it's obvious that that's not due to fluctuations one way or the other in the date of the DST change.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it OK to submit further changes once the PR has been approved?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes you can submit further changes. I think @pganssle's suggestion about using the repr would be clearer.

assert pd.Timestamp(d_2038, tz=DST) == pd.Timestamp(d_2038, tz='GMT')

Under the hood, all timestamps are stored in UTC. Values from a time zone aware
:class:`DatetimeIndex` or :class:`Timestamp` will have their fields (day, hour, minute, etc.)
localized to the time zone. However, timestamps with the same UTC value are
Expand Down