A DateTime field extension that automatically stores the timezone, and the computed UTC equivalent. This field needs the pytz library.
The field adds two new fields to the model, with the same name of the UTCDateTimeField field, and a suffix. For an UTCDateTimeField named 'updated', the model will contain
* an 'updated' field, which holds the local datetime
* an 'updated_utc' field, which holds the corresponding UTC datetime
* an 'updated_tz' field, which holds the field timezone name
The timezone can vary between model instances, just set the 'xxx_tz' field to the desired timezone before saving.
UTCDateTimeField supports a single optional keyword argument 'default_tz', in addition to the DateTimeField standard ones, to let the user choose a provider for a default timezone when no timezone has been set. Its value can be
* None (or the argument missing), in which case the default settings.TIME_ZONE will be used
* a callable, which will be called when the 'xxx_tz' field is emtpy, which should return a timezone name
* a string, which will be used to access a model attribute or call a model method, which should return a timezone name
If the timezone name points to a non-existent timezone, a warning will be issued and the default settings.TIME_ZONE value will be used.
The field will also add three properties to the model, to access the pytz timezone instance, and the offset aware datetimes for local time and UTC. For the same 'updated' field instance we used above, the three properties added to the model will be:
* updated_timezone
* updated_offset_aware
* updated_utc_offset_aware
A brief example on how to use UTCDateTimeField:
class UTCDateTimeTest(models.Model):
"""
>>> import datetime
>>> d = datetime.datetime(2007, 8, 24, 16, 46, 34, 762627)
# new instance, tz from model method
>>> t = UTCDateTimeTest(updated=d)
>>> t.save()
>>> t.updated
datetime.datetime(2007, 8, 24, 16, 46, 34, 762627)
>>> t.updated_utc
datetime.datetime(2007, 8, 24, 14, 46, 34, 762627)
>>> t.updated_tz
'Europe/Rome'
>>> t.updated_timezone
<DstTzInfo 'Europe/Rome' CET+1:00:00 STD>
>>> t.updated_offset_aware
datetime.datetime(2007, 8, 24, 16, 46, 34, 762627, tzinfo=<DstTzInfo 'Europe/Rome' CEST+2:00:00 DST>)
>>> t.updated_utc_offset_aware
datetime.datetime(2007, 8, 24, 14, 46, 34, 762627, tzinfo=<UTC>)
>>>
"""
updated = UTCDateTimeField(default_tz='get_tz')
def get_tz(self):
return 'Europe/Rome'
- models
- fields
- datetime
- timezone
- field
- utc