Docs for naturaldelta are wrong/incomplete about humanize HOT 5 CLOSED

I will submit a PR.

from humanize.

I suspect that the when parameter exists because naturaltime() was implemented first, and the API was just copied to naturaldelta() even though when is not appropriate in the later.

from humanize.

The when parameter was added to both naturaltime() and naturaldelta() at the same time, in #144 by @phijor.

Accepting a datetime was intentional:

• both methods may now be used with datetime objects that are not in the local timezone

So let's update the docs? @phijor Any thoughts?

from humanize.

Accepting datetime was done intentionally, but tbf I'm not entirely sure whether that was a good idea?

I agree that the when-parameter does not make a lot of sense for naturaldelta(). It is only there to make sure naturaltime can be implemented in terms of it.

Maybe the details of both functions should be put in a (private) function as an implementation detail, and when= should be removed from naturaldelta. If the behaviour was never specified, is counter-intuitive and leads to issues I'd argue it's not a breaking change to remove it.

Comparing my own use-cases with @carterbox's example, I think computing your own timedelta should be encouraged.

from humanize.

We have a major version coming out soon anyway to drop Python 3.6 (#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:

And add something like "Deprecated, will be removed in humanize 4.0." to the parameter's docstring.

from humanize.