Python ISO 8601 date time parser and data model/manipulation utilities
Project description
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 metomi.isodatetime.parsers as parse
>>> import metomi.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:
Reference material:
Dates and times
How do I write the year, month-of-year, and day-of-month down?
Syntax | Example |
---|---|
CCYYMMDD | 20151231 |
CCYY-MM-DD | 2015-12-31 |
How about writing down the year, week-of-year, and day-of-week?
Syntax | Example |
---|---|
CCYYWwwD | 2015W534 |
CCYY-Www-D | 2015-W53-4 |
How about writing down the year and day-of-year?
Syntax | Example |
---|---|
CCYYDDD | 2015365 |
CCYY-DDD | 2015-365 |
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?
Syntax | Example (2 expanded year digits) |
---|---|
+XCCYYMMDD | +0020151231 |
+XCCYY-MM-DD | +002015-12-31 |
+XCCYYWwwD | +002015W534 |
+XCCYY-Www-D | +002015-W53-4 |
+XCCYYDDD | +002015365 |
+XCCYY-DDD | +002015-365 |
How do I write down time information by itself?
Syntax | Example |
---|---|
hhmmss | 083000 |
hhmm | 0830 |
hh:mm:ss | 17:45:01 |
hh:mm | 17:45 |
hh | 08 |
How do I write down time information at a date in ISO 8601?
Write the time after the date, separated with a T
:
Syntax | Example |
---|---|
CCYYMMDDThhmmss | 20151231T063101 |
CCYY-MM-DDThh:mm:ss | 2015-12-31T06:31:01 |
CCYYWwwDThhmmss | 2015W534T063101 |
CCYY-Www-DThh:mm:ss | 2015-W53-4T06:31:01 |
CCYYDDDThhmmss | 2015365T063101 |
CCYY-DDDThh:mm:ss | 2015-365T06:31:01 |
What about just the hour and minute at a date?
Syntax | Example |
---|---|
CCYYWwwDThhmm | 2015W534T0631 |
CCYY-Www-DThh:mm | 2015-W53-4T06:31 |
What about just the hour at a date?
Syntax | Example |
---|---|
CCYYMMDDThh | 20151231T06 |
CCYY-MM-DDThh | 2015-12-31T06 |
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:
Syntax | Example |
---|---|
CCYYMMDDThh,ii | 20151231T06,5 |
CCYYMMDDThh.ii | 20151231T06.5 |
CCYYMMDDThhmm,nn | 20151231T0631,3333 |
CCYYMMDDThhmm.nn | 20151231T0631.3333 |
CCYYMMDDThhmmss,tt | 20151231T063101,25671 |
CCYYMMDDThhmmss.tt | 20151231T063101.25671 |
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.
Syntax | Example |
---|---|
CCYYMMDDThhmmssZ | 20151231T063101Z |
CCYY-MM-DDThh:mm:ssZ | 2015-12-31T06:31:01Z |
CCYYMMDDThhmmss-hh | 20151231T013101-05 |
CCYY-MM-DDThh:mm:ss-hh | 2015-12-31T01:31:01-05 |
CCYYMMDDThhmmss+hh | 20151231T083101+02 |
CCYY-MM-DDThh:mm:ss+hh | 2015-12-31T08:31:01+02 |
CCYYMMDDThhmmss-hhmm | 20151230T203101-1000 |
CCYY-MM-DDThh:mm:ss-hh:mm | 2015-12-30T20:31:01-10:00 |
CCYYMMDDThhmmss+hhmm | 20151231T193101+1300 |
CCYY-MM-DDThh:mm:ss+hh:mm | 2015-12-31T19:31:01+13:00 |
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:
Unit type | Unit designator |
---|---|
years | Y |
months | M |
weeks | W |
days | D |
hours | H |
minutes | M |
seconds | S |
If the unit is one of hours, minutes, or seconds, you need a leading "T" to delimit time from date:
Syntax | Example | Meaning |
---|---|---|
PnY | P2Y | 2 years |
Pn,oY | P5,5Y | 5 and a half years |
Pn.oY | P5.5Y | 5 and a half years |
PTnM | PT7M | 7 minutes (note the 'T') |
PnM | P10M | 10 months |
PnDTnH | P5DT6H | 5 days and 6 hours |
PnW | P2W | 2 weeks |
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
Example Syntax | Example | Meaning |
---|---|---|
R/CCYY/CCYY | R/2010/2014 | Repeat every 4 years, starting at 2010-01-01. |
R/CCYY-MM/CCYY-DDD | R/2010-01/2012-045 | Repeat every 2 years and 44 days, starting at 2010-01-01 |
R5/CCYY-Www-D/CCYY-Www-D | R/2015-W05-2/2015-W07-3 | Repeat every 2 weeks and 1 day, five times, starting at 2015-W05-2 |
2 - Recur with a given duration, starting at a context date-time
(You have to supply the context somewhere else)
Example Syntax | Example | Meaning |
---|---|---|
R/PnMnDTnM | R/P10M3DT45M | Repeat every 10 months, 3 days, and 45 minutes from a context start date-time. |
Rn/PnY | R2/P4Y | Repeat every 4 years, for a total of 2 times, from a context start date-time. |
3 - Recur with a given duration starting at a particular date-time
Example Syntax | Example | Meaning |
---|---|---|
R/CCYYMMDDThhZ/PTnH | R/20201231T00Z/PT12H | Repeat every 12 hours starting at 2020-12-31T00Z |
R/CCYY-Www-D/PnW | R/2012-W02-1/P1W | Repeat weekly starting at Monday in the second ISO week of 2012 |
R/CCYYDDDThhmm/PnD | R/1996291T0630+0100/P2D | Repeat every 2 days starting on the 291st day of 1996 at 06:30, UTC + 1 |
Rn/CCYY-MM-DDThh:mm/PTnH | R2/19900201T06Z/PT12H | Repeat every 12 hours, for a total of 2 repetitions, starting at 1990-02-01T06Z |
Rn/CCYY-Www-D/PnW | R5/2012-W02-1/P1W | Repeat weekly, for a total of 5 repetitions, starting at Monday in the second ISO week of 2012 |
Rn/CCYYDDDThhmm/PnD | R1/1996291T0630+0100/P2D | Repeat once at the 291st day of 1996 at 06:30, UTC + 1 |
4 - Recur with a given duration counting back from a particular date-time
Example Syntax | Example | Meaning |
---|---|---|
R/PTnH/CCYY-MM-DDThhZ | R/PT1H/2012-01-02T00Z | Repeat hourly counting back from 2012-01-02T00Z |
R/PnY/CCYY | R/P3Y/2000 | Repeat every 3 years counting back from 2000-01-01. |
R/PTnS/+XCCYYDDDThhmm | R/PT5s/-002500012T1800 | Repeat every 5 seconds counting back from the 12th day in 2501 BC at 18:00 (using 2 expanded year digits). |
Rn/PnYTnM/CCYY-MM-DDThhZ | R5/P1YT5M/2012-01-02T00Z | Repeat every year and 5 minutes counting back from 2012-01-02T00Z |
Rn/PnM/CCYY-MM | R4/P1M/2000-05 | Repeat monthly, four times, counting back from 2000-05-01. |
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for metomi-isodatetime-1!2.0.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | a8dd8a12f4df79098c297de192d6dd75b93c78a2565f10ec13281f2f2c5faf29 |
|
MD5 | d0ba85fba8814c79cfd387a2b520d5c8 |
|
BLAKE2b-256 | b85d7b397b161255a1e962ebe089ccbb71daa35ce5d59d3b9e0ee3d8b660f2cd |
Hashes for metomi_isodatetime-1!2.0.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1c504c6b74811a40904ab34db7ff1e008c7f2901ca8b2f1d0df349f482b474cb |
|
MD5 | 9ef604b498574dcf6718fc1a159f0fa7 |
|
BLAKE2b-256 | cf32e30fc8374be2e4f5e5c9d6b9e1f0b36af0909d1a155c2fea298cf7b2a6fe |