This is understandable given the database-agnostic nature of the Django ORM: although PostgreSQL 8.3 supports a datetime type which is time zone-aware, MySQL 5.1 does not (I have no idea what SQLite does about time zones). By ignoring time zones, Django works with the lowest common denominator.
Given time zone support in Postgres, there is a chunk of work to write a variation of
models.DateTimeField which can handle time zone-wise datetimes. Python 2.5 does not help things – Python’s native datetime module is similarly agnostic about time zones, the standard library does not include a module for handling wise datetimes.
(If regular datetime instances are naive then datetime instances that honour time zones are wise.)
Django does make it pretty easy to write a custom field class, which means it shouldn’t be too difficult to write a custom datetime field class that is time zone-wise. As ever it is the Django project’s regard for documentation that transforms that which is possible into that which is practical.
Given your backend database has a time zone-wise datetime type (i.e. PostgreSQL), what input values does one need to handle in a time zone-wise custom field class?
- value set to None
- value set to a naive datetime instance
- value set to a wise datetime instance
- value set to a naive datetime string
- value set to a wise datetime string
Now the essence of a custom field in Django is two methods:
get_db_prep_value. If the custom field defines
__metaclass__ = models.SubfieldBase
to_python method will be called any time a value is assigned to the field, and we can make sure that a suitable type is returned before the model object is saved. Because Postgres supports time zone-wise datetimes and if we take care to return a wise datetime instance we can ignore
When Django reads a record from the database it strips the time zone information, effectively giving your custom field a naive datetime string that belongs to the same time zone as the database connection object. (At least this seems to be true for Postgres and the psycopg2 adaptor.) And since the database connection sets the time zone to be the same as set by
settings.TIME_ZONE your custom class needs to treat any naive datetime strings as belonging to the time zone set with
So this leads to the important behaviour for a time zone-wise
DateTimeField sub-class: always convert naive datetimes to the time zone set in
For convenience my custom field class, the
TZDateTimeField, returns a sub-class of Python’s
datetime which has an extra method that converts the datetime to the zone defined by the project’s time zone. Therefore whether the field value has been set from a naive or wise datetime instance, or a naive or wise date string you will end up with a time zone-wise value and you can get the value converted to the project’s time zone. This extra method is intended for use in a Django template.
What I was hoping was that the backend would store the datetime as a datetime in an arbitrary zone, potentially a different time zone from one record to the next for the same field. That behaviour would allow one to infer that one datetime value was created in this time zone while another datetime value was created in that time zone. Instead all datetime values are effectively normalized to your Django project’s time zone.
So here is an example of a model class that uses my time zone-aware datetime field. It ought to work just like a regular
DateTimeField but always stores a time zone-aware datetime instance:
from django.db import models from timezones.fields import TZDateTimeField from datetime import datetime class Article(models.Model): pub_date = TZDateTimeField(default=datetime.now)
And below is my custom field definition, which has a dependency on the pytz module to handle all the difficult stuff. You can grab the complete module over here, including tests in doctest format. The tests are intended to be run by Django’s
manage.py test management command, and so one needs to add the module to the list of installed apps.
"""A time zone-aware DateTime field. When saving, naive datetime objects are assumed to belong to the local time zone and are converted to UTC. When loading from the database the naive datetime objects are converted to UTC. These field types require database support. MySQL 5 will not work. """ from datetime import datetime, tzinfo, timedelta from django.conf import settings from django.core.exceptions import ValidationError from django.db import models import pytz import re # 2009-06-04 12:00:00+01:00 or 2009-06-04 12:00:00 +0100 TZ_OFFSET = re.compile(r'^(.*?)\s?([-\+])(\d\d):?(\d\d)$') class TZDatetime(datetime): def aslocaltimezone(self): """Returns the datetime in the local time zone.""" tz = pytz.timezone(settings.TIME_ZONE) return self.astimezone(tz) class TZDateTimeField(models.DateTimeField): """A DateTimeField that treats naive datetimes as local time zone.""" __metaclass__ = models.SubfieldBase def to_python(self, value): """Returns a time zone-aware datetime object. A naive datetime is assigned the time zone from settings.TIME_ZONE. This should be the same as the database session time zone. A wise datetime is left as-is. A string with a time zone offset is assigned to UTC. """ try: value = super(TZDateTimeField, self).to_python(value) except ValidationError: match = TZ_OFFSET.search(value) if match: value, op, hours, minutes = match.groups() value = super(TZDateTimeField, self).to_python(value) value = value - timedelta(hours=int(op + hours), minutes=int(op + minutes)) value = value.replace(tzinfo=pytz.utc) else: raise if value is None: return value # Only force zone if the datetime has no tzinfo if (value.tzinfo is None) or (value.tzinfo.utcoffset(value) is None): value = force_tz(value, settings.TIME_ZONE) return TZDatetime(value.year, value.month, value.day, value.hour, value.minute, value.second, value.microsecond, tzinfo=value.tzinfo) def force_tz(obj, tz): """Converts a datetime to the given timezone. The tz argument can be an instance of tzinfo or a string such as 'Europe/London' that will be passed to pytz.timezone. Naive datetimes are forced to the timezone. Wise datetimes are converted. """ if not isinstance(tz, tzinfo): tz = pytz.timezone(tz) if (obj.tzinfo is None) or (obj.tzinfo.utcoffset(obj) is None): return tz.localize(obj) else: return obj.astimezone(tz)