Not logged in - Log In / Register

Datetime Usage Guide

There are a number of places in Launchpad where datetime types are used. There are three main places where datetime types are represented:

Furthermore, there are two main datetime types in use:

Data Types


We use the standard datetime module to represent time stamps and time deltas -- the datetime.datetime type for timestamps, and the datetime.timedelta type for time deltas.

To make matters a little bit more complicated, there are actually two types of datetime.datetime objects:

  1. naïve datetime objects

  2. timezone aware datetime objects

While both objects share the same Python type, they can not be compared with each other. Where possible, we use timezone aware datetime objects.

A timezone aware datetime can be created with the following code:

The pytz.timezone() function can be used to retrieve tzinfo objects for any of the named Olsen time zones. A datetime value can be converted to another time zone as follows:


In Postgres, the TIMESTAMP WITHOUT TIME ZONE should be used to represent timestamps, and INTERVAL should be used to represent time deltas. All timestamp columns in the database should store the time in UTC.

While Postgres has a TIMESTAMP WITH TIME ZONE type, it should not be used. The difference between the two column types is that the value of a TIMESTAMP WITH TIME ZONE column will be converted to local time when being read, and the reverse occurs when being written. It does not actually store a time zone with the timestamp.


To wrap a timestamp database column, use the type. To wrap an interval database column, use the type:

Page Templates

Inside page templates, use the following TALES formatters to present timestamp objects:

The preferred method of presenting datetime is:

When in doubt, use this presentation.

If the timestamp has a time zone attached, these formatters will convert the date to the user's local time before display.

For time interval objects, use the following formatters:

Two Concepts of "Now"

When working with the database, there are two distinct concepts of "now" to work with:

  1. the time when the code is running (e.g. returned by

  2. the database transaction time (when the transaction is committed, all the changes will appear to have happened atomically at that time).

Usually these two mean almost the same thing, but they will differ under the following conditions:

In cases where you are comparing timestamps, mixing the two concepts of "now" can result in race conditions. In most cases in Launchpad, the database transaction time is the correct one to use.

Database Transaction Time

Storing the current database transaction time in the database use the following syntax:

(note that you won't be able to read the value as a Python datetime object until the object is flushed to the database, or the transaction is committed).

To store a time relative to the present time in a database column, we can make use of the fact that UTC_NOW is an SQL() type:

The database transaction time can be retrieved using

Present Time

To create a Python datetime object that represents the present time, use the following code:

Note that the datetime.utcnow() method should not be used -- it creates a naïve datetime value, which can not be compared against other values in Launchpad.

DatetimeUsageGuide (last edited 2021-08-09 17:12:42 by cjwatson)