Inconsistencies between documentation/annotations and behavior

[serhiy-storchaka]

naturaltime() supports timedelta.

It is not documented, but humanize.naturaltime() accepts timedelta. I used it for years until type annotations were added, and MyPy started to complain. timedelta is still accepted at runtime.

>>> import datetime, humanize
>>> humanize.naturaltime(datetime.timedelta(days=5, hours=3))
'5 days ago'
>>> humanize.naturaltime(datetime.timedelta(hours=123))
'5 days ago'

I expect one of two things:

1. Document that humanize.naturaltime() accepts timedelta, not only datetime | int and update type annotation.
2. Make humanize.naturaltime() rejecting timedelta (of course, after some deprecation period).

Option 1 is more compatible, but option 2 looks more logical.

naturaltime() and naturaldelta() accept not only int, but float too.

>>> humanize.naturaltime(23.5)
'23 seconds ago'
>>> humanize.naturaldelta(23.5)
'23 seconds'

It is expected, since timestamp in Python is float, but it should be documented, and annotations should be updated.

naturaltime(), naturaldelta() , naturaldate() and naturalday() accept arbitrary object without error.

>>> humanize.naturaltime([1, 2, 3])
'[1, 2, 3]'
>>> humanize.naturaldelta([1, 2, 3])
'[1, 2, 3]'
>>> humanize.naturaldate([1, 2, 3])
'[1, 2, 3]'
>>> humanize.naturalday([1, 2, 3])
'[1, 2, 3]'

It is unsafe, because allows programming errors to slip unnoticed. humanize.naturalsize() raises an error, as expected.

Humanize 4.2.1

[hugovk]

naturaltime() supports timedelta.

...

I expect one of two things:

1. Document that humanize.naturaltime() accepts timedelta, not only datetime | int and update type annotation.
2. Make humanize.naturaltime() rejecting timedelta (of course, after some deprecation period).

Option 1 is more compatible, but option 2 looks more logical.

Let's do option 1, possibly with some tests.

Option 2 with deprecation could be sensible too, let's also check what the Django naturaltime does.

Feedback from others welcome!

---

naturaltime() and naturaldelta() accept not only int, but float too.

...

It is expected, since timestamp in Python is float, but it should be documented, and annotations should be updated.

Yep, let's update those.

---

naturaltime(), naturaldelta() , naturaldate() and naturalday() accept arbitrary object without error.

...

It is unsafe, because allows programming errors to slip unnoticed. humanize.naturalsize() raises an error, as expected.

Yeah, I do find it a little odd to catch things like ValueError, TypeError, AttributeError and then just return str(value), but it's done that for a long time and I didn't want to break backwards compatibility.

Maybe we should also check what the Django ones do and consider deprecating and removing in a major bump.

Feedback from others also welcome here!

[hugovk]

Let's do option 1, possibly with some tests.

Released in 4.2.2:

• https://pypi.org/project/humanize/4.2.2/
• https://github.com/python-humanize/humanize/releases/tag/4.2.2

[nuztalgia]

naturaltime() and naturaldelta() accept not only int, but float too.

If I'm not mistaken, this looks like the issue that was fixed in 4.2.2. (And thank you for that!)

---

naturaltime() supports timedelta.

1. Document that humanize.naturaltime() accepts timedelta, not only datetime | int and update type annotation.
2. Make humanize.naturaltime() rejecting timedelta (of course, after some deprecation period).

Let's do option 1, possibly with some tests.

This issue, however, seems to still be open as of 4.2.2. If option 1 is still on the table, that would (in my opinion) be ideal!

Here's an example of how I'm using naturaltime() with a timedelta, along with # noinspection PyTypeChecker as a workaround for now. 😅 As far as I can tell, naturaltime() seems to be the most intuitive function for my desired output (e.g. "1 year, 10 months ago").

Please let me know if I'm misunderstanding something, or if that sounds reasonable! I'm happy to try to put together a PR to add documentation/annotations for timedelta, if that's the direction you want to take.

[hugovk]

naturaltime() and naturaldelta() accept not only int, but float too.

If I'm not mistaken, this looks like the issue that was fixed in 4.2.2. (And thank you for that!)

Ah, correct, it was indeed the float issue fixed in 4.2.2, sorry for the mixup :)

---

naturaltime() supports timedelta.

1. Document that humanize.naturaltime() accepts timedelta, not only datetime | int and update type annotation.
2. Make humanize.naturaltime() rejecting timedelta (of course, after some deprecation period).

Let's do option 1, possibly with some tests.

This issue, however, seems to still be open as of 4.2.2. If option 1 is still on the table, that would (in my opinion) be ideal!

Here's an example of how I'm using naturaltime() with a timedelta, along with # noinspection PyTypeChecker as a workaround for now. 😅 As far as I can tell, naturaltime() seems to be the most intuitive function for my desired output (e.g. "1 year, 10 months ago").

Please let me know if I'm misunderstanding something, or if that sounds reasonable! I'm happy to try to put together a PR to add documentation/annotations for timedelta, if that's the direction you want to take.

Yes, option 1 is still on the table, PR welcome! Please include a test case passing a timedelta to naturaltime(), if there's not already.

[hugovk]

And the naturaldelta() + timedelta fix has been released in 4.2.3. Thanks!

• https://pypi.org/project/humanize/4.2.3/
• https://github.com/python-humanize/humanize/releases/tag/4.2.3

[sodul]

The type for seconds should be float and not int as introduced in #15. This actually breaks mypy for us.

[hugovk]

@sodul In which function? And what version of Humanize are you using?

[sodul]

@hugovk I posted details in the conversation for #15.

[hugovk]

Most if not all of these should be addressed, please open a new issue if there's something further. Thanks!