René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Inconsistencies between documentation/annotations and behavior","articleBody":"## `naturaltime()` supports `timedelta`.\r\n\r\nIt 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.\r\n\r\n```pycon\r\n\u003e\u003e\u003e import datetime, humanize\r\n\u003e\u003e\u003e humanize.naturaltime(datetime.timedelta(days=5, hours=3))\r\n'5 days ago'\r\n\u003e\u003e\u003e humanize.naturaltime(datetime.timedelta(hours=123))\r\n'5 days ago'\r\n```\r\n\r\nI expect one of two things:\r\n\r\n1. Document that `humanize.naturaltime()` accepts `timedelta`, not only `datetime | int` and update type annotation.\r\n2. Make `humanize.naturaltime()` rejecting `timedelta` (of course, after some deprecation period).\r\n\r\nOption 1 is more compatible, but option 2 looks more logical.\r\n\r\n## `naturaltime()` and `naturaldelta()` accept not only `int`, but `float` too.\r\n\r\n```pycon\r\n\u003e\u003e\u003e humanize.naturaltime(23.5)\r\n'23 seconds ago'\r\n\u003e\u003e\u003e humanize.naturaldelta(23.5)\r\n'23 seconds'\r\n```\r\n\r\nIt is expected, since timestamp in Python is `float`, but it should be documented, and annotations should be updated.\r\n\r\n## `naturaltime()`, `naturaldelta()` , `naturaldate()` and `naturalday()` accept arbitrary object without error.\r\n\r\n```pycon\r\n\u003e\u003e\u003e humanize.naturaltime([1, 2, 3])\r\n'[1, 2, 3]'\r\n\u003e\u003e\u003e humanize.naturaldelta([1, 2, 3])\r\n'[1, 2, 3]'\r\n\u003e\u003e\u003e humanize.naturaldate([1, 2, 3])\r\n'[1, 2, 3]'\r\n\u003e\u003e\u003e humanize.naturalday([1, 2, 3])\r\n'[1, 2, 3]'\r\n```\r\n\r\nIt is unsafe, because allows programming errors to slip unnoticed. `humanize.naturalsize()` raises an error, as expected.\r\n\r\nHumanize 4.2.1\r\n","author":{"url":"https://github.com/serhiy-storchaka","@type":"Person","name":"serhiy-storchaka"},"datePublished":"2022-06-24T16:49:29.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":9},"url":"https://github.com/28/humanize/issues/28"}