Time Expression Parser

1.1.8 · active · verified Sun Mar 29

Pytimeparse is a small Python library designed to parse various kinds of natural language time expressions into a total number of seconds. It supports a wide range of formats including combinations of days, hours, minutes, and seconds, as well as clock-style notations. The current version is 1.1.8, and the library is considered stable with infrequent updates, with its last release in 2018.

Warnings

gotcha Parsing of months and years assumes fixed durations (30 days for a month, 365 days for a year) and does not account for leap years or leap seconds. This can lead to inaccuracies for precise date calculations.
Fix: Be aware of these assumptions when parsing time expressions involving months and years. For more precise date/time handling, consider using `datetime` or `dateutil.relativedelta` in conjunction with pytimeparse if applicable, or a different library altogether for complex date parsing. pytimeparse2, a fork, offers `as_timedelta=True` for `datetime.timedelta` or `dateutil.relativedelta` returns.
gotcha When a number is provided without an explicit unit, `parse()` will return `None`. It does not assume 'seconds' as a default unit. For example, `parse('60')` will return `None`.
Fix: Always specify a unit for numerical values (e.g., `parse('60s')` for 60 seconds, `parse('120m')` for 120 minutes). If you expect a bare number to be a specific unit, you must append the unit.
breaking Versions prior to 1.1.4 had an `ImportError` on Python 3 due to compatibility issues.
Fix: Upgrade to pytimeparse version 1.1.4 or newer to ensure Python 3 compatibility. The current version, 1.1.8, supports Python 2.7 and Python 3.2-3.6.

Install

pip install pytimeparse Install stable version

Imports

parse
```
from pytimeparse import parse
```
The `parse` function is the preferred top-level alias available since version 1.1.3. While `pytimeparse.timeparse.timeparse` still works, it's considered an older pattern.

Quickstart

The `parse` function takes a string time expression and returns the total number of seconds as an integer or float.

from pytimeparse import parse

# Parse various time expressions
print(parse('32m'))
print(parse('2h33m'))
print(parse('4:17'))
print(parse('5hr34m56s'))
print(parse('1.2 minutes'))
print(parse('2 days, 4:13:02.266'))
print(parse('1w 3d 2h 32m'))

view raw JSON →