isodatetime

Python ISO 8601 full-specification parser and data model/manipulation utilities. Intended to be used in a similar way to Python's datetime module.

Installation

Install from PyPI:

$ pip install isodatetime

Or build yourself:

$ git clone https://github.com/metomi/isodatetime.git isodatetime
$ cd isodatetime
$ python setup.py install

Usage

Python API:

>>> import isodatetime.parsers as parse
>>> import isodatetime.dumpers as dump

# Dates and times
>>> date_time = parse.TimePointParser().parse('2000-01-01T00:00Z')
>>> date_time.month_of_year
1

# Durations
>>> duration = parse.DurationParser().parse('P1YT3H')
>>> duration.get_days_and_seconds()
(365.0, 10800.0)
>>> date_time + duration
2001-01-01T03:00:00Z

# Recurrences
>>> recurrence = parse.TimeRecurrenceParser().parse('R/1999/P1Y')
>>> recurrence.get_next(date_time)
2001-01-01T00:00:00Z

# Output
>>> dump.TimePointDumper().strftime(date_time, '%d/%M/%Y %H:%M:%S')
'01/00/2000 00:00:00'

CLI:

$ isodatetime
2000-01-01T00:00:00Z
$ isodatetime 1066
1066
$ isodatetime 1066 --offset P1Y
1067
$ isodatetime R/2000/P1Y --max 3
2000-01-01T00:00:00Z
2001-01-01T00:00:00Z
2002-01-01T00:00:00Z

ISO8601

ISO8601 is an international standard for writing down date/time information.

It is the correct, internationally-friendly, computer-sortable way to numerically represent date/time information.

Good reading material:

• http://www.cl.cam.ac.uk/~mgk25/iso-time.html
• http://www.tondering.dk/claus/calendar.html

Reference material:

• http://www.iso.org/iso/home/standards/iso8601.htm
• http://en.wikipedia.org/wiki/ISO_8601

Dates and times

How do I write the year, month-of-year, and day-of-month down?

How about writing down the year, week-of-year, and day-of-week?

How about writing down the year and day-of-year?

How do I write just the year?

Either: CCYY or +XCCYY

+X stands for a plus or minus sign (+ or -), followed by a fixed, agreed number of expanded year digits (X). For example, if we agree to have 2 expanded year digits, we can represent years from -999999 to +999999 (1000000 BC to 999999 AD). Note that 1 BC is the year 0 in the proleptic Gregorian calendar used by ISO 8601.

For example, you can write the year 1995 AD as: 1995 or +001995 (using 2 expanded year digits).

Note: writing just the year where you mean a proper date implies Day 1 of Month 1 in that year - 1995 implies 1995-01 => 1995-01-01 => 1995-01-01T00 => 1995-01-01T00:00 => 1995-01-01T00:00:00.

How do I write just the year and month-of-year?

Either: CCYY-MM or +XCCYY-MM (+ standing in here for a + or - sign)

(not allowed: CCYYMM or +XCCYYMM).

How do I write dates past the year 9999 and before 0000?

How do I write down time information by itself?

How do I write down time information at a date in ISO 8601?

Write the time after the date, separated with a T:

What about just the hour and minute at a date?

What about just the hour at a date?

What about decimal parts of the hour or minute or second?

Use a comma or period to delimit the decimal part, and don't include any smaller units:

How do I specify a time zone?

If the time zone is UTC, use "Z" - otherwise, use a numeric representation of the hours and minutes difference from UTC.

Note that this difference is (TIMEZONE - UTC) - so longitudes east of 0 tend to have positive differences, and west of 0 usually have negative differences.

Durations

How do I write down a certain period of time in X units?

A "P" followed by the number of units (optionally including a decimal part) followed by a designator to mark the units:

If the unit is one of hours, minutes, or seconds, you need a leading "T" to delimit time from date:

Combining any other unit with weeks is not allowed.

A supplementary format (which has to be agreed in advance) is to specify a date-time-like duration (PCCYY-MM-DDThh:mm:ss) where the numbers given for years, months, days, hours, minutes, and seconds are used literally (P1995-00-00T00:10:00 = P1995YT10M).

Recurring date-time series

1 - Recur with a duration given by the difference between a start date

and a subsequent date, starting at the start date

2 - Recur with a given duration, starting at a context date-time

(You have to supply the context somewhere else)

3 - Recur with a given duration starting at a particular date-time

4 - Recur with a given duration counting back from a particular date-time