Skip to content

DOC: clarify (un)aware logic in tz_localize() docstring #40940

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 2 commits into from
Apr 16, 2021
Merged

DOC: clarify (un)aware logic in tz_localize() docstring #40940

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c6923c8
DOC: fix tz (un)aware logic in tz_localize() docstring
jgehrcke Apr 14, 2021
4ffb6d1
DOC: fix tz (un)aware logic in tz_localize() docstring
jgehrcke Apr 16, 2021
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
4 changes: 2 additions & 2 deletions pandas/core/arrays/datetimes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -857,8 +857,8 @@ def tz_localize(self, tz, ambiguous="raise", nonexistent="raise") -> DatetimeArr
This method takes a time zone (tz) naive Datetime Array/Index object
and makes this time zone aware. It does not move the time to another
time zone.
Time zone localization helps to switch from time zone aware to time
zone unaware objects.
Time zone localization helps to switch from time zone unaware to time
zone aware objects.
Copy link
Contributor

Choose a reason for hiding this comment

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

the tz is None the existing is correct - why don't we break this down into multiple statements

Copy link
Contributor Author

@jgehrcke jgehrcke Apr 14, 2021 •
edited
Loading

Choose a reason for hiding this comment

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

Hey @jreback thank you for super quick feedback! Let's clarify.

I was considering to remove the entire sentence, because the two sentences above the one I changed already say pretty precisely what's happening:

Localize tz-naive Datetime Array/Index to tz-aware Datetime Array/Index.

This method takes a time zone (tz) naive Datetime Array/Index object and makes this time zone aware.

This third sentence says the opposite:

Time zone localization helps to switch from time zone aware to time zone unaware objects.

The way I understand things the first two sentences are correct, the third one is not.

This assumes that "tz-naive" means the same as "tz-unaware" or just "unaware" which I think we agree on, do we? :)

Maybe I miss something, would love to understand what you mean with "tz is None".

Also, the way I have personally always looked at methods like this is:

  • simply attach time zone information (add meta data)
  • leave the actual numbers intact (no magic shifting / translation)

That's what tz_localize() is doing according to the code examples. It's therefore a useful helper tool to switch from tz-unaware to tz-aware objects (which is the opposite of what's written in the sentenced I proposed modifying).

Copy link
Member

Choose a reason for hiding this comment

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

I think this sentence tries to (poorly) describe that tz_localize(None) can convert tz-aware to tz-unaware (there's an example in this doc-string already)

So it would be great to have this in a new paragraph clarifying this point.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Oooooh. Gotcha. And now I understand that "the tz is None the existing is correct" was supposed to be

if tz is None, ...

🙏

I'll happily improve on the current patch. Thanks everyone.


Parameters
----------
Expand Down