A flexible python duration parser designed for human readable lengths of time, including long form durations such as 1 day, 5 hours, and 30 seconds, short form durations such as 1d5h30s, numerals such as twelve hours, HHMMSS such as 12:30:15, and a mix thereof such as 1 day 5h 30s.
timelength can be installed via pip:
pip install timelength
Or added to your project via poetry:
poetry add timelength
Import TimeLength and pass it a string to evaluate. As long as a single valid result is found the parsing will be considered a success regardless of any invalid content included in the input.
from datetime import datetime, timezone
from timelength import TimeLength
tl = TimeLength("1.27 hours and 23 miles")
print(tl.result.success)
# True
print(tl.result.seconds)
# 4572.0
print(tl.to_minutes(max_precision=3))
# 76.2
print(tl.result.delta)
# 1:16:12
print(tl.ago(base=datetime(2025, 1, 1, 0, 0, 0, 0, timezone.utc)))
# 2024-12-31 22:43:48+00:00
print(tl.hence(base=datetime(2025, 1, 1, 0, 0, 0, 0, timezone.utc)))
# 2025-01-01 01:16:12+00:00
print(tl.result.invalid)
# ((23.0, FailureFlags.LONELY_VALUE), ('miles', FailureFlags.UNKNOWN_TERM))
print(tl.result.valid)
# ((1.27, Scale(scale=3600.0, ...)),)
Control can be increased by making use of FailureFlags and ParserSettings. Both are passed to whichever Locale you are parsing with which is then passed to the TimeLength to be parsed.
FailureFlags is an IntFlag enum which holds all the currently possible reasons for a parse to fail. The default is FailureFlags.NONE which means as long as a single value is parsed, it will be considered a success. To achieve the opposite behavior, FailureFlags.ALL will cause the parsing to be considered a failure if any FailureFlags are detected, even if a valid value was parsed. See below for a full list.
ParserSettings is an object with various parsing settings. See below for a full list of options along with the default values.
In the first part of the example below, the flags are set to (FailureFlags.LONELY_VALUE | FailureFlags.UNKNOWN_TERM), which means as long as a single valid item is found, the parsing will only be considered a failure if FailureFlags.LONELY_VALUE or FailureFlags.UNKNOWN_TERM show up in the invalid items. As 19 is included in the input without an accompanying scale, it is considered a LONELY_VALUE and thus invalid.
In the second part, the flags are reset, meaning nothing will cause parsing to be considered a failure as long as a single valid item is found. Additionally, the settings are updated such that duplicate scales are not allowed to be parsed. Due to this, 5m from the input is added to the invalid items as a DUPLICATE_SCALE due to the preceding 35m. Also, 19 is still in the invalid items as a LONELY_VALUE. Despite this, since the flags is set to FailureFlags.NONE and since 3.5d, 35m is successfully parsed, the overall parsing is considered a success.
from timelength import English, FailureFlags, ParserSettings, TimeLength
flags = (FailureFlags.LONELY_VALUE | FailureFlags.UNKNOWN_TERM)
locale = English(flags=flags)
tl = TimeLength("3.5d, 35m, 5m, 19", locale=locale)
print(tl.result.success)
# False
print(tl.result.invalid)
# ((19.0, FailureFlags.LONELY_VALUE),)
print(tl.result.valid)
# ((3.5, Scale(scale=86400.0, ...)), (35.0, Scale(scale=60.0, ...)), (5.0, Scale(scale=60.0, ...)))
flags = FailureFlags.NONE
settings = ParserSettings(allow_duplicate_scales=False)
locale.flags = flags
locale.settings = settings
tl.parse()
print(tl.result.success)
# True
print(tl.result.invalid)
# (('5m', FailureFlags.DUPLICATE_SCALE), (19.0, FailureFlags.LONELY_VALUE))
print(tl.result.valid)
# ((3.5, Scale(scale=86400.0, ...)), (35.0, Scale(scale=60.0, ...)))
To put it simply, FailureFlags is used to determine if an item that is in the invalid items tuple should invalidate the parsing as a whole, whereas ParserSettings is used to determine if certain customizable situations should even result in an item being added to the invalid items tuple to begin with.
The members of the FailureFlags IntEnum are:
NONE — No failures will cause parsing to fail.ALL — Any failure will cause parsing to fail.MALFORMED_CONTENT — The fallback when something that shouldn't have happened, happened.UNKNOWN_TERM — The parsed value was not recognized from the terms or symbols in the config.
1 mileMALFORMED_DECIMAL — Multiple decimals were attempted within a singular decimal segment.
1.2.3minMALFORMED_THOUSAND — A thousand segment was attempted but did not have a leading number or a proper number of digits following a thousand separator.
,234, 1,23, or 1,2345MALFORMED_FRACTION — A fraction was attempted but had more than 2 values, a missing value, or was not formatted correctly.
1/2/3, /2, or 1+ / +2MALFORMED_HHMMSS — An HH:MM:SS was attempted but had more segments than enabled scales or was not formatted correctly.
1:2:3:4:5:6:7:8:9:10:11:12:13:14:15 or 1:15:26:LONELY_VALUE — A value was parsed with no paired scale.
one minute and twentyLONELY_SCALE — A scale was parsed with no paired value.
2 minutes and hoursDUPLICATE_SCALE — The same scale was parsed multiple times.
1min 5:23 or 1min 5 minutes and 23 secondsCONSECUTIVE_CONNECTOR — More than the allowed number of connectors were parsed in a row.
1h 2minCONSECUTIVE_SEGMENTOR — More than the allowed number of segmentors were parsed in a row.
1h,, 2minCONSECUTIVE_SPECIAL — More than the allowed number of special characters were parsed in a row.
1h 2min!!MISPLACED_ALLOWED_TERM — An allowed term was found in the middle of a segment/sentence.
1!h 2minMISPLACED_SPECIAL — A special character was found in the middle of a segment/sentence.
1, /2UNUSED_OPERATION — A term of the operation numeral was parsed but unused on any values.
2 min ofAMBIGUOUS_MULTIPLIERS — More than one multiplier was parsed for a single segment which may be ambiguous.
half of a quarter of two minutes and 30sLiteral["LAST", "SINGLE", "NEVER"] = "SINGLE" — How to handle no scale being provided.
LAST will assume seconds only for the last value if no scale is provided for it.SINGLE will only assume seconds when a single input is provided.NEVER will never assume seconds when no scale is provided.bool = True — Prevent terms from the allowed_terms list in
the config from being used in the middle of a segment, thus interrupting a value/scale pair.
False, The terms will be ignored (within other limitations) and not effect parsing.bool = True — Allow scales to be parsed multiple times, stacking their values.
False, the first scale will be used and subsequent duplicates will be added to the invalid list.bool = False — Allow thousands to be parsed with more than three digits following a thousand delimiter.
1,2345 will be interpreted as 12,345.bool = False — Allow a number to be parsed with less than three digits following a thousand delimiter.
1,23 will be interpreted as 123.bool = True — Allow decimals to be parsed with no number following the
decimal delimiter.
1. will be interpreted as 1.0.If you're unsure of which locale the input will belong to, you can attempt to guess the locale from the available options.
from timelength import English, Spanish, Guess, TimeLength
guess = Guess()
tl = TimeLength("5 minutos", locale=guess)
print(tl.locale)
# Spanish
print(tl.result.success)
# True
print(tl.result.valid)
# ((5.0, Scale(scale=60.0, ...)))
tl.content = "5 minutes"
tl.parse(guess_locale=guess) # or `guess_locale=True`
print(tl.locale)
# English
print(tl.result.success)
# True
print(tl.result.valid)
# ((5.0, Scale(scale=60.0, ...)))
To guess the locale you can pass in an instantiated Guess either on creation of the TimeLength or to the parse() function on subsequent calls. Doing so will save locale instantiations as with each new Guess created, each locale available is instantiated in Guess().locales. Alternatively, for parse(), you can pass True for guess_locale and a new Guess will be instantiated automatically.
Guessing works by parsing with each locale. The one with the least invalid results is considered the correct locale. Ties are broken by most valid followed by alphabetically.
Any flags or settings passed to the Guess will be passed on to each locale. If none are provided, the defaults in each locale's configs are used. If you need to specify flags or settings per locale, you can directly access Guess().locales, which is a list of instantiated versions of all of the currently available locales.
If you have any custom locales you would like to be included in the possible results, append to Guess().locales before passing it to the TimeLength or parse() function.
TimeLength objects support various arithmetic operations and comparisons between each other, datetimes, timedelta, and numbers. The supported options are:
Addition
TimeLength + TimeLength or timedelta or number -> TimeLengthdatetime or timedelta + TimeLength -> datetime or timedeltaSubtraction
TimeLength - TimeLength or timedelta or number -> TimeLengthdatetime or timedelta - TimeLength -> datetime or timedeltaMultiplication
TimeLength * number -> TimeLengthTimeLength -> TimeLengthDivision
TimeLength / TimeLength or timedelta or number -> TimeLength or floattimedelta / TimeLength -> floatFloor Division
TimeLength // TimeLength or timedelta or number -> TimeLength or floattimedelta // TimeLength -> floatModulo
TimeLength % TimeLength or timedelta -> TimeLengthtimedelta % TimeLength -> timedeltaDivmod
divmod(TimeLength, TimeLength or timedelta) -> tuple[float, TimeLength]divmod(timedelta, TimeLength) -> tuple[float, timedelta]Power
TimeLength ** number -> TimeLength (optionally moduloed by TimeLength or timedelta)Comparisons
TimeLength > TimeLength or timedelta -> boolTimeLength >= TimeLength or timedelta -> boolTimeLength < TimeLength or timedelta -> boolTimeLength <= TimeLength or timedelta -> boolTimeLength == TimeLength or timedelta -> boolTimeLength != TimeLength or timedelta -> boolOther Operations
abs(TimeLength) -> TimeLength (returns self unchanged as TimeLength is an absolute measurement)+TimeLength -> TimeLength (returns self unchanged)-TimeLength -> TimeLength (returns self unchanged)bool(TimeLength) -> bool (returns True if parsing succeeded, otherwise False)len(TimeLength) -> int (returns the length of self.content)1m1min1 Minute1m and 2 SECONDS3h, 2 min, 3sec1.2d1,234sone hourtwenty-two hours and thirty five minuteshalf of a day1/2 of a day1/4 hour1 Day, 2:34:121:2:34:121:5:13:27:22half) is allowed per segment (value + scale). This is due to the ambiguity introduced when more than one multiplier is used. May be revisited in the future if a good way to handle this ambiguity is found.HH:MM:SS standards. Any parsable numbers work in each slot, whether they are single digits, multiple digits, or include decimals.
2.56:27/3:270:19.2231 is a valid input in place of 2.56 days, 9 hours, 270 minutes, and 19.2231 seconds.2: 6: 3.Millisecond to Century).
Locale, may differ for custom defined Scales) to ensure the correct scales are applied.
HH:MM:SS starts at is Second. Any scales (typically of lesser value) listed prior in the config, or appended to the scales list before Second in the case of custom scales, will not be utilized unless Second is disabled or as many HH:MM:SS segments are parsed as there are scales defined.12:30:15 is 12 hours, 30 minutes, and 15 seconds, NOT 12 minutes, 30 seconds, and 15 milliseconds.1:10:100:12:52:30:24:60:60:1000 will make use of Century to Millisecond.Locale follows the existing config parser's grammar structureLocale's grammar structure differs too drastically (PRs welcome)timelength allows for customizing the parsing behavior through JSON configuration. To get started, copy an existing locale JSON in timelength/locales/. The custom JSON may be placed anywhere.
Ensure the JSON being used is from a trusted source, as the parser is loaded dynamically based on the file specified in the JSON. This could allow for unintended code execution if an unsafe config is loaded.
Valid JSONs must include the following keys:
connectors
segmentors
allowed_terms
!!), they will still be marked as invalid. If ParserSettings().limit_allowed_terms is set then these characters won't be allowed in the middle of a segment (ex: 1!min) and will cause the segment progress to reset.hhmmss_delimiters
HH:MM:SS segments. Can't have overlap with decimal_delimiters, thousand_delimiters, or fraction_delimiters.decimal_delimiters
hhmmss_delimiters, thousand_delimiters, or fraction_delimiters.thousand_delimiters
hhmmss_delimiters, decimal_delimiters, or fraction_delimiters.fraction_delimiters
hhmmss_delimiters, decimal_delimiters, or thousand_delimiters.parser_file
timelength/parsers/, or the path to the parser file if stored elsewhere.parser_one.py and def parser_one().scales
millisecond, second, minute, hour, day, week, month, year, decade, and century. Default scales must be present. At least one scale must be valid and enabled. Custom scales can be added following the format of the others. The following keys must be present and populated:
numerals
type
value
terms
flags
FailureFlags which will cause parsing to be considered a failure. Values should be upper cased. This is optional and can be passed to the locale dynamically instead. See a full list of options in the FailureFlags section.settings
extra_data
Locale().extra_data attribute, leaving the parser to utilize it.Once your custom JSON is filled out, you can use it as follows:
from timelength import TimeLength, Locale
output = TimeLength("30 minutes", locale = Locale("path/to/config.json"))
If all goes well, the parsing will succeed, and if not, an error will point you in the right direction.
FAQs
A flexible python duration parser designed for human readable lengths of time.
We found that timelength demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Bybit's $1.46B hack by North Korea's Lazarus Group pushes 2025 crypto losses to $1.6B in just two months, already surpassing all of 2024's $1.49B total.
Security News
OpenSSF has published OSPS Baseline, an initiative designed to establish a minimum set of security-related best practices for open source software projects.
Security News
Michigan TypeScript founder Dimitri Mitropoulos implements WebAssembly runtime in TypeScript types, enabling Doom to run after processing 177 terabytes of type definitions.