Operations with ISO 8601 durations
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:
>>> 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')))
>>> 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)
>>> 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 git@github.com:bolsote/isoduration.git
cd isoduration/
python -m venv ve
. ve/bin/activate
pip install -U pip
pip install -e .
pip install -r requirements/dev.txt
Adapt 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.
P1Y != P365D
?Some years have 366 days. If it's not always the same, then it's not the same.
timedelta
?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.
<insert here a weird case>
?Probably because the standard made me to.
<insert here a weird case>
?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.
isodate
: The original implementation of ISO
durations in Python. Worth a look. But ours is cooler.