Skip to main content

An ISO 8601 date/time/duration parser and formater

Project description

ISO 8601 date/time parser

This module implements ISO 8601 date, time and duration parsing. The implementation follows ISO8601:2004 standard, and implements only date/time representations mentioned in the standard. If something is not mentioned there, then it is treated as non existent, and not as an allowed option.

For instance, ISO8601:2004 never mentions 2 digit years. So, it is not intended by this module to support 2 digit years. (while it may still be valid as ISO date, because it is not explicitly forbidden.) Another example is, that if no time zone designation is given for a time, the it is a local time, and not UTC.

As this module maps ISO 8601 dates/times to standard Python data types, like date, time, datetime and timedelta, it is not possible to convert all possible ISO 8601 dates/times. For instance, dates before 0001-01-01 are not allowed by the Python date and datetime classes.


Currently there are four parsing methods available.
  • parse_time:
    parses an ISO 8601 time string into a time object
  • parse_date:
    parses an ISO 8601 date string into a date object
  • parse_datetime:
    parses an ISO 8601 date-time string into a datetime object
  • parse_duration:
    parses an ISO 8601 duration string into a timedelta or Duration object.

As ISO 8601 allows to define durations in years and months, and timedelta does not handle years and months, this module provides a Duration class, which can be used almost like a timedelta object (with some limitations). However, a Duration object can be converted into a timedelta object.


This module can easily be installed with Python standard installation methods. Just use setuptools or easy_instal as usual.


  • The parser accepts several date/time representation which should be invalid according to ISO 8601 standard.
    1. for date and time together, this parser accepts a mixture of basic and extended format. e.g. the date could be in basic format, while the time is accepted in extended format. It also allows short dates and times in date-time strings.
    2. For incomplete dates, the first day is chosen. e.g. 19th century results in a date of 1901-01-01.

Further information:

The doc strings and unit tests should provide rather detailed information about the methods and their limitations.

The source release provides a script and a buildout.cfg. Both can be used to run the unit tests included.

Source code is available at


0.3.0 (2009-1-05)

  • Initial release


This to do list contains some thoughts and ideas about missing features, and parts to think about, whether to implement them or not. This list is probably not complete.

Missing features:

  • methods to format date, time, datetime, timedelta and Duration objects to various ISO strings.
  • parser for ISO intervals.


  • parse_datetime:
    • complete documentation to show what this function allows, but ISO forbids. and vice verse.
    • support other separators between date and time than ‘T’
  • parse_date:
    • yeardigits should be always greater than 4
    • dates before 0001-01-01 are not supported
  • parse_duration:
    • alternative formats are not fully supported due to parse_date restrictions
    • standard duration format is fully supported but not very restrictive.
  • Duration:
    • support fractional years and month in calculations
    • implement w3c order relation? (
    • refactor to have duration mathematics only at one place.
    • localize __str__ method (does timedelta do this?)

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for isodate, version 0.3.0
Filename, size File type Python version Upload date Hashes
Filename, size isodate-0.3.0.tar.gz (12.9 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page