humanized-time-parser

parse humanized and relative time strings into datetime objects. stdlib only, no dependencies.

install

pip install git+https://github.com/ffuyu/humanized-time-parser.git

usage

from datetime import datetime
from parse_humanize import parse_humanize

parse_humanize("5 minutes ago")
parse_humanize("29 September at 18:00")
parse_humanize("Jan 19, 2024, 2:21 PM")

# pin the reference point for relative expressions (and for testing)
parse_humanize("2 hours ago", now=datetime(2024, 3, 13, 15, 30))
# -> datetime(2024, 3, 13, 13, 30)

returns a datetime, or None if nothing matched. the tzinfo of now is preserved on the result, so pass an aware now to get aware output.

formats

input	result
just now, now, few seconds ago	now
30 seconds ago, a minute ago, 2 hours ago, 3 days ago, 1 week ago	now minus the offset
13:05, 01:44 PM	today at that time
today at 4:00 pm, yesterday at 09:30	relative day at that time
monday at 01:00, fri 10:00	most recent past weekday (today if it matches)
4 Jan, 29 September at 18:00	day + month, current year
25 October 2023 at 01:44 PM	full date + time
Jan 19, 2024, 2:21 PM, August 15 2024	month-first date
25/10/2023, 25/10/23	numeric date, read day-first

notes:

• time needs HH:MM; am/pm is optional and 24h is assumed without it.
• relative offsets cover fixed units (seconds through weeks). ambiguous units like months and years return None rather than guessing.
• numeric dd/mm/yyyy is day-first by design; there is no locale sniffing.

tests

pip install pytest
pytest