Date and Time Representation in Python

Jochen Voss (last update: 2008-03-01)

There are many different ways to represent date and time in Python programs. This page gives an overview over the different methods and explains how to convert between different representations. The main focus of this page is on how to represent points in time often assuming some fixed, local time zone. This is used for example when analysing log files. I will not explain here how to convert between different time zones or between different calendars.

Date and Time representations

ISO 8601 Time Representation

The international standard ISO 8601 describes a string representation for dates and times. Two simple examples of this format are

2007-03-04 20:32:17 20070304T203217 

(which both stand for the 4th of March 2007, a bit after half past eight in the evening) but the format also allows for sub-second resolution times and to specify time zones. This format is of course not Python specific, but it is good for storing dates and times in a portable format. Details about this format can be found on Markus Kuhn's ISO 8601 page and on Gary Houston's ISO 8601:1988 Date/Time Representations page.

I recommend use of this format to store times in files.

One way to get the current time in this representation is to use strftime from the time module in the Python standard library:

>>> from time import strftime >>> strftime("%Y-%m-%d %H:%M:%S") '2007-03-03 22:14:39' 

Python datetime Objects

The datetime module of the Python standard library provides the datetime class.

I recommend use of this format, when possible, to represent times in Python programs.

One way to get the current time in this representation is to use the now method of the datetime class in the Python standard library:

>>> from datetime import datetime >>> datetime.now() datetime.datetime(2007, 3, 3, 22, 20, 11, 443849) 

Unix Time

The traditional way to describe times on a Unix system is to give the number of seconds elapsed since the beginning of the year 1970. Sometimes this count includes leap seconds and sometimes it does not. Traditionally this number is an integer, but of course one can get sub-second resolution by using floating point numbers here.

One way to get the current time in this representation is to use time from the time module in the Python standard library. This function returns the number of seconds elapsed since the beginning of the year 1970 in UTC as a float:

>>> from time import time >>> time() 1172960204.226908 

Broken Down Time

This is what is represented by struct_time objects in Python (and similarly by struct tm in the C standard library). Time is represented as a tuple consisting of the following fields:

1. the year as a four-digit number, e.g. 2007
2. the month (1, 2, …, 12)
3. the day of the month (1, 2, …, 31)
4. hour (0, 1, …, 23)
5. minutes (0, 1, …, 59)
6. seconds (0, 1, …, 61 where 60 and 61 are used for leap seconds)
7. week day (0=Monday, 1=Tuesday, …, 6=Sunday)
8. day of the year (1, 2, …, 366)
9. daylight saving time information (0, 1, or -1)

It is not possible to get sub-second resolution in this representation. For details see the time module description of the Python standard library.

One way to get the current time in this representation is to use localtime from the time module in the Python standard library:

>>> from time import localtime >>> localtime() (2007, 3, 3, 22, 13, 27, 5, 62, 0) 

The Egenix mxDateTime Class

Egenix provides the mxDateTime class as part of their mx extensions for Python. This class seems to be relatively similar to the standard datetime class, but it provides a parser for ISO 8601 date strings.

One way to get the current time in this representation is to use the now constructor from the mx.DateTime module:

>>> from mx.DateTime import now >>> now() <DateTime object for '2007-03-03 22:51:13.37' at 52a2c0> 

The Matplotlib Date Representation

The very nice matplotlib graphing library has support for using dates to locate data in plots. The library represents dates/times as single floating point numbers and provides functions num2date and date2num to convert between Python datetime objects and the matplotlib representation. The numbers represent days but I am not sure which day in time is matplotlib day 0.

One way to get the current time in this representation is as follows:

>>> from matplotlib.dates import date2num >>> from datetime import datetime >>> date2num(datetime.now()) 732738.96073077701 

Date Conversions

Since I recommend to normally use the standard Python datetime class to store times in Python programs, I only provide recipes here to convert between datetime and any of the other representations here. A summary of the described methods can be found in table 1 below.

Conversion between ISO Time Representation and datetime

Unfortunately there is no easy way to parse full ISO 8601 dates using the Python standard library. If you know the exact format of the date string in advance, you can use the strptime constructor of the datetime class (new in Python version 2.5):

>>> from datetime import datetime >>> datetime.strptime("2007-03-04 21:08:12", "%Y-%m-%d %H:%M:%S") datetime.datetime(2007, 3, 4, 21, 8, 12) 

There are several parsers available in external modules. The most robust one I found is contained in the Egenix mxDateTime module:

>>> from mx.DateTime.ISO import ParseDateTimeUTC >>> from datetime import datetime >>> x = ParseDateTimeUTC("2007-03-04 21:08:12") >>> datetime.fromtimestamp(x) datetime.datetime(2007, 3, 4, 21, 8, 12) 

Another one is contained in the PyXML package:

>>> from xml.utils.iso8601 import parse >>> parse("2001-11-12T12:13:00+01:00") 1005563580.0 

Conversion from datetime objects is easy using the strftime method:

>>> from datetime import datetime >>> t = datetime.now() >>> t.strftime("%Y-%m-%d %H:%M:%S") '2007-03-04 00:15:12' 

Conversion between Unix times and datetime

To convert a Unix time stamp to datetime use the fromtimestamp constructor:

>>> from datetime import datetime >>> datetime.fromtimestamp(1172969203.1) datetime.datetime(2007, 3, 4, 0, 46, 43, 100000) 

To convert a datetime object into a Unix time stamp, one has to first convert it into a struct_time:

>>> from datetime import datetime >>> from time import mktime >>> t=datetime.now() >>> mktime(t.timetuple())+1e-6*t.microsecond 1172970859.472672 

Conversion between struct_time and datetime

struct_time objects can be converted to datetime objects using the normal datetime constructor:

>>> from time import localtime >>> from datetime import datetime >>> x = localtime() >>> datetime(*x[:6]) datetime.datetime(2007, 3, 4, 1, 0, 39) 

datetime objects can be converted back to struct_time using the timetuple class method:

>>> from datetime import datetime >>> t = datetime.now() >>> t.timetuple() (2007, 3, 4, 1, 3, 18, 6, 63, -1) 

Conversion between the Egenix mxDateTime class and datetime

mxDateTime objects can be converted to datetime via the Unix time stamp format:

>>> from mx.DateTime import now >>> from datetime import datetime >>> x = now() >>> datetime.fromtimestamp(x) datetime.datetime(2007, 3, 4, 1, 14, 19, 472672) 

The reverse conversion is a bit awkward:

>>> from mx.DateTime import DateTime >>> from datetime import datetime >>> t = datetime.now() >>> DateTime(t.year,t.month,t.day,t.hour,t.minute,t.second+1e-6*t.microsecond) <DateTime object for '2007-03-04 01:14:19.47' at 104a368> 

Conversion between the matplotlib time representation and datetime

This conversion is straight-forward using the converter functions provided by matplotlib:

>>> from matplotlib.dates import num2date >>> num2date(732738.96073077701) datetime.datetime(2007, 3, 3, 23, 3, 27, 139133, tzinfo=<UTC>) 

and

>>> from matplotlib.dates import date2num >>> from datetime import datetime >>> t = datetime.now() >>> date2num(t) 732738.96073077701 

Conversion Summary

Table 1 summarises the conversion methods discussed in this chapter.

References

• Markus Kuhn's ISO 8601 page.
• Gary Houston's ISO 8601:1988 Date/Time Representations page.
• The Python time module documentation.
• The Python datetime class documentation.
• The Egenix mxDateTime class.
• The PyXML package.
• The matplotlib library.
• The Python Website.