Docs for naturaldelta are wrong/incomplete

What did you do?

It seems the docs for naturaldelta() are wrong/incomplete/conflicting. They specify that the first parameter should be a timedelta or an int, but the API will also accept a datetime.

What did you expect to happen?

naturaldelta() should only accept timedelta or int as documented. I expect that users should create their own timedelta inline instead of using the when parameter.

What actually happened?

A datetime is converted to a timedelta internally using the when parameter, which defaults to now. This undocumented conversion behavior is enforced by the tests.

In the current implementation, the handling of when causes and overflow for large timedeltas (#245).

What versions are you using?

• OS: Ubuntu x64
• Python: 3.9.6
• Humanize: 3.13.1

Please include code that reproduces the issue.

The best reproductions are self-contained scripts with minimal dependencies.

import humanize
from datetime import timedelta, datetime

now = datetime(1, 1, 1, minute=1)
later = datetime(1, 1, 1, minute=31)

# Correct documented usage; input is timedelta.
assert humanize.naturaldelta(later - now) == "30 minutes"

# Incorrect/undocumented usage; input is pair of datetimes
assert humanize.naturaldelta(now, when=later) == "30 minutes"

[carterbox]

I will submit a PR.

[hugovk]

We have a major version coming out soon anyway to drop Python 3.6 (https://github.com/jmoiron/humanize/pull/239), so let’s deprecate when= first and release it, even if it’s not long until it’s removed.

Would one of you like to submit a PR to deprecate it?

Let’s show a warning when if when: is true, something along the lines of:

https://github.com/jmoiron/humanize/blob/49f2cd1b8b73e4b63aac5a84b07afcb92c3ca0b7/src/humanize/__init__.py#L40-L45

And add something like “Deprecated, will be removed in humanize 4.0.” to the parameter’s docstring.