Product
Introducing License Enforcement in Socket
Ensure open-source compliance with Socket’s License Enforcement Beta. Set up your License Policy and secure your software!
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.FAQs
Operations with ISO 8601 durations
We found that isoduration 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.
Product
Ensure open-source compliance with Socket’s License Enforcement Beta. Set up your License Policy and secure your software!
Product
We're launching a new set of license analysis and compliance features for analyzing, managing, and complying with licenses across a range of supported languages and ecosystems.
Product
We're excited to introduce Socket Optimize, a powerful CLI command to secure open source dependencies with tested, optimized package overrides.