ISO 8601 is most commonly known as a way to exchange datetimes in textual format. A lesser known aspect of the standard is the representation of durations. They have a shape similar to this:
P3Y6M4DT12H30M5S
This string represents a duration of 3 years, 6 months, 4 days, 12 hours, 30 minutes, and 5 seconds.
The state of the art of ISO 8601 duration handling in Python is more or less limited to
what's offered by isodate. What we are trying to
achieve here is to address the shortcomings of isodate (as described in their own
Limitations section), and a few of
our own annoyances with their interface, such as the lack of uniformity in their
handling of types, and the use of regular expressions for parsing.
This package revolves around the Duration type.
Given a ISO duration string we can produce such a type by using the parse_duration()
function:
>>> from isoduration import parse_duration
>>> duration = parse_duration("P3Y6M4DT12H30M5S")
>>> duration.date
DateDuration(years=Decimal('3'), months=Decimal('6'), days=Decimal('4'), weeks=Decimal('0'))
>>> duration.time
TimeDuration(hours=Decimal('12'), minutes=Decimal('30'), seconds=Decimal('5'))The date and time portions of the parsed duration are just regular
dataclasses, so their members can
be accessed in a non-surprising way.
Besides just parsing them, a number of additional operations are available:
- Durations can be compared and negated:
>>> parse_duration("P3Y4D") == parse_duration("P3Y4DT0H") True >>> -parse_duration("P3Y4D") Duration(DateDuration(years=Decimal('-3'), months=Decimal('0'), days=Decimal('-4'), weeks=Decimal('0')), TimeDuration(hours=Decimal('0'), minutes=Decimal('0'), seconds=Decimal('0')))
- Durations can be added to, or subtracted from, Python datetimes:
>>> from datetime import datetime >>> datetime(2020, 3, 15) + parse_duration("P2Y") datetime.datetime(2022, 3, 15, 0, 0) >>> datetime(2020, 3, 15) - parse_duration("P33Y1M4D") datetime.datetime(1987, 2, 11, 0, 0)
- Durations are hashable, so they can be used as dictionary keys or as part of sets.
- Durations can be formatted back to a ISO 8601-compliant duration string:
>>> from isoduration import parse_duration, format_duration >>> format_duration(parse_duration("P11YT2H")) 'P11YT2H' >>> str(parse_duration("P11YT2H")) 'P11YT2H'
These steps, in this order, should land you in a development environment:
git clone [email protected]:bolsote/isoduration.git
cd isoduration/
python -m venv ve
. ve/bin/activate
pip install -U pip
pip install -e .
pip install -r requirements/dev.txtAdapt to your own likings and/or needs.
Testing is driven by tox. The output of tox -l and a
careful read of tox.ini should get you there.
Some years have 366 days. If it's not always the same, then it's not the same.
timedelta cannot represent certain durations, such as those involving years or months.
Since it cannot represent all possible durations without dangerous arithmetic, then it
must not be the right type.
Regular expressions should only be used to parse regular languages.
Because this wonderful representation is not unique.
Probably because the standard made me to.
Probably because the standard doesn't allow me to.
I'm confused.
You shouldn't do what people on the Internet tell you to do.
Yes.
- XML Schema Part 2: Datatypes, Appendix D: This excitingly named document contains more details about ISO 8601 than any human should be allowed to understand.
isodate: The original implementation of ISO durations in Python. Worth a look. But ours is cooler.