Package: isoduration
isoduration: Operations with ISO 8601 durations.What is this.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:P3Y6M4DT12H30M5SThis 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 byisodate. What we are trying to
achieve here is to address the shortcomings ofisodate(as described in their ownLimitationssection), 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.How to use it.This package revolves around theDurationtype.Given a ISO duration string we can produce such a type by using theparse_duration()function:>>>fromisodurationimportparse_duration>>>duration=parse_duration("P3Y6M4DT12H30M5S")>>>duration.dateDateDuration(years=Decimal('3'),months=Decimal('6'),days=Decimal('4'),weeks=Decimal('0'))>>>duration.timeTimeDuration(hours=Decimal('12'),minutes=Decimal('30'),seconds=Decimal('5'))Thedateandtimeportions of the parsed duration are just regulardataclasses, 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:>>>fromdatetimeimportdatetime>>>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:>>>fromisodurationimportparse_duration,format_duration>>>format_duration(parse_duration("P11YT2H"))'P11YT2H'>>>str(parse_duration("P11YT2H"))'P11YT2H'How to improve it.These steps, in this order, should land you in a development environment:gitclonegit@github.com:bolsote/isoduration.gitcdisoduration/
python-mvenvve
.ve/bin/activate
pipinstall-Upip
pipinstall-e.
pipinstall-rrequirements/dev.txtAdapt to your own likings and/or needs.Testing is driven bytox. The output oftox -land a
careful read oftox.inishould get you there.FAQs.How comeP1Y != P365D?Some years have 366 days. If it's not always the same, then it's not the same.Why do you create your own types, instead of somewhat shoehorning atimedelta?timedeltacannot 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.Why don't you use regular expressions to parse duration strings?Regular expressions should only be used to parse regular languages.Why is parsing the inverse of formatting, but the converse is not true?Because this wonderful representation is not unique.Why do you support<insert here a weird case>?Probably because the standard made me to.Why do you not support<insert here a weird case>?Probably because the standard doesn't allow me to.Why is it not possible to subtract a datetime from a duration?I'm confused.Why should I use this over some other thing?You shouldn't do what people on the Internet tell you to do.Why are ISO standards so strange?Yes.References.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.