{"id":3251,"library":"pytimeparse2","title":"Time Expression Parser","description":"pytimeparse2 is a small Python library for parsing various human-readable time expressions (e.g., '2h32m', '1.5 days', '5hr 34mins 56secs') into a total number of seconds or `datetime.timedelta` objects. It is a fork of the original `pytimeparse` project, aiming for optimized functionality and stable support. The current version is 1.7.1, and releases are made on an as-needed basis for bug fixes and feature enhancements.","status":"active","version":"1.7.1","language":"en","source_language":"en","source_url":"https://github.com/onegreyonewhite/pytimeparse2","tags":["time","parsing","duration","timedelta","utility"],"install":[{"cmd":"pip install pytimeparse2","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Enables returning `dateutil.relativedelta.relativedelta` objects when `as_timedelta=True` is used. Otherwise, it defaults to `datetime.timedelta`.","package":"python-dateutil","optional":true}],"imports":[{"note":"pytimeparse2 is a distinct fork from the original 'pytimeparse' library. Importing 'parse' from 'pytimeparse' will use the older, unmaintained version.","wrong":"from pytimeparse import parse","symbol":"parse","correct":"from pytimeparse2 import parse"}],"quickstart":{"code":"from pytimeparse2 import parse\n\n# Parse to total seconds\nseconds = parse('1 day, 2 hours, 30 minutes, 15 seconds')\nprint(f\"Parsed to seconds: {seconds}\")\n\n# Parse to timedelta (requires python-dateutil for relativedelta if complex units are used)\ntimedelta_obj = parse('1y 2mo 3w 4d 5h 6m 7s 8ms', as_timedelta=True)\nprint(f\"Parsed to timedelta: {timedelta_obj}\")","lang":"python","description":"This quickstart demonstrates how to parse a time expression into total seconds or a `datetime.timedelta` object using the `parse` function. For advanced `timedelta` results (e.g., handling months/years), `python-dateutil` is recommended."},"warnings":[{"fix":"Be aware of this limitation when parsing expressions involving 'mo' or 'y'. For highly accurate date/time arithmetic across varying year lengths, consider using libraries like `python-dateutil` directly, especially its `relativedelta` functionality.","message":"When parsing months ('mo') and years ('y'), `pytimeparse2` assumes fixed durations (30 days for a month, 365 days for a year). It does not account for leap years or leap seconds, which can lead to inaccuracies for precise date calculations.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install `python-dateutil` via `pip install python-dateutil` if `relativedelta` objects are desired for more precise and flexible date calculations with `as_timedelta=True`.","message":"The `as_timedelta=True` option will return a `datetime.timedelta` object by default. If `python-dateutil` is installed, it will instead return a `dateutil.relativedelta.relativedelta` object, which offers more sophisticated handling for units like months and years. Ensure `python-dateutil` is installed if `relativedelta` behavior is expected.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Explicitly import from `pytimeparse2` (i.e., `from pytimeparse2 import parse`) to leverage the updates and support provided by this specific fork.","message":"`pytimeparse2` is a fork of the original `pytimeparse` library. While functionally similar, using `from pytimeparse import parse` will import the older, less maintained version. Always use `from pytimeparse2 import parse` to ensure you are using this library.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}