DOC: Add notes about M and Y to to_timedelata documentation. (#34968)

[selasley]

• closes #xxxx
• tests added / passed
• passes black pandas
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• whatsnew entry

Not sure it closes these issues, but using "M" in the arg argument of to_timedelta caused confusion in #34968 and #27285. #33094 is somewhat related. I came across another issue I can't find now where there was confusion about "Y" returning a days with times delta

[dsaxton]

Suggested change

	365 days 5 hours 49 minutes 12 seconds
	365 days 5 hours 49 minutes 12 seconds.

[dsaxton]

Can you also link to the relevant issue in the description?

[selasley]

Since MS is valid for milliseconds and contains the character M my PR should probably be changed to something like

The data to be converted to timedelta. The character M by itself, e.g. '1M', is treated as minute, not month. The characters Y and y are treated as the mean length of the Gregorian calendar year - 365.2425 days or 365 days 5 hours 49 minutes 12 seconds.

[MarcoGorelli]

Since MS is valid for milliseconds and contains the character M my PR should probably be changed to something like

The data to be converted to timedelta. The character M by itself, e.g. '1M', is treated as minute, not month. The characters Y and y are treated as the mean length of the Gregorian calendar year - 365.2425 days or 365 days 5 hours 49 minutes 12 seconds.

Makes sense to me - do you want to push such an update?

[pep8speaks]

Hello @selasley! Thanks for updating this PR. We checked the lines you've touched for PEP 8 issues, and found:

There are currently no PEP 8 issues detected in this Pull Request. Cheers! 🍻

Comment last updated at 2020-09-01 16:05:04 UTC

[selasley]

I think I updated it correctly ( https://xkcd.com/1597/ ). If not, please let me know what I should have done to update the PR. Thanks.

[MarcoGorelli]

Pending green, this looks correct to me

[TomAugspurger]

Does this close #34968? If not, can you suggest what needs to be done there?

[MarcoGorelli]

As far as I can tell, this closes #34968 - @selasley , seeing as you wrote "Not sure it closes these issues", do you agree?

[selasley]

Yes, I believe documenting the current behavior addresses the issue. Thanks.

[MarcoGorelli]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[MarcoGorelli]

>>> (pd.Timestamp.today() + pd.to_timedelta('1 Y')) - pd.Timestamp.today()
Timedelta('365 days 05:49:11.999916')
>>> (pd.Timestamp.today() + pd.to_timedelta('1 M')) - pd.Timestamp.today()
Timedelta('0 days 00:00:59.999766')

Looks right to me...thanks @selasley !

[jreback]

hmm
did we not fully deprecate M and Y for timedelta conversion? i don't remember if these were actually removed

this added note is very misleading then

if the above is true then pls revert this

[MarcoGorelli]

@jreback pd.to_timedelta(1, unit='M') is deprecated, but not pd.to_timedelta('1 M').

In issue #34968 you'd commented

I'll repurpose this issue to be a doc one if you'd like to submit a PR to update.

[jreback]

i c

pls create a new issue to deprecate these as strings as well

we do not support these as they are very confusing

yes they work but they are fixed offsets and almost never what you want

[MarcoGorelli]

sure, done - #36666