Time Expression Parser

1.7.1 · active · verified Sat Apr 11

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.

Warnings

gotcha 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.
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.
gotcha 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.
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`.
gotcha `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.
Fix: Explicitly import from `pytimeparse2` (i.e., `from pytimeparse2 import parse`) to leverage the updates and support provided by this specific fork.

Install

pip install pytimeparse2 Install stable version

Imports

parse
```
from pytimeparse2 import parse
```
pytimeparse2 is a distinct fork from the original 'pytimeparse' library. Importing 'parse' from 'pytimeparse' will use the older, unmaintained version.

Quickstart

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.

from pytimeparse2 import parse

# Parse to total seconds
seconds = parse('1 day, 2 hours, 30 minutes, 15 seconds')
print(f"Parsed to seconds: {seconds}")

# Parse to timedelta (requires python-dateutil for relativedelta if complex units are used)
timedelta_obj = parse('1y 2mo 3w 4d 5h 6m 7s 8ms', as_timedelta=True)
print(f"Parsed to timedelta: {timedelta_obj}")

view raw JSON →