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

[jgehrcke]

A simple hopefully no-brainer documentation patch; came across this while reading https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DatetimeIndex.tz_localize.html#pandas-datetimeindex-tz-localize.

[jreback]

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

[jgehrcke]

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).

[mroeschke]

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.

[jgehrcke]

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.

[jgehrcke]

Pushed another commit, PTAL @mroeschke!

[jreback]

thanks @jgehrcke