Django timezones localization app based on global cache (similar to django.utils.translation)
BSD-2-CLAUSE License
h1. django_tz
h2. WARNING
This app is deprecated - native time zones support was introduced in Django 1.4 (https://docs.djangoproject.com/en/dev/topics/i18n/timezones/).
h2. OVERVIEW
This app is derived from brosner/django-timezones application (http://github.com/brosner/django-timezones). It takes different approach to timezones localization, so I've separated those two apps for clarity.
django-tz manages timezones transitions in a manner similar to how django implements language switching. Timezone is stored in global cache and datetime values can be ,,localized'' according to it in templates with custom template filter or in forms with custom form fields. Because timezone localization works through form fields and template filter you can easily add it to an existing app.
,,What does this application do?''
h2. HOW DOES IT WORK?
h3. LocalizedDateTimeField
This multivalue form field decompresses given datetime value to datetime and timezone. It contains: DateTimeField and TimezoneField. TimezoneField is set by default to current global timezone (if given value has empty tzinfo) and datetime value is converted from default timezone (settings.TIME_ZONE) to selected timezone. After form submit this process is reversed.
There is also split (similar to SplitDateTimeField) version of this field (SplitLocalizedDateTimeField).
h3. to_global_tz
This template filter takes datetime value and assumes that is given in default timezone (settings.TIME_ZONE) and converts it to current global timezone value.
h3. set_timezone
This is simple view which is nearly copy of django.views.i18n.set_language. It caches timezone in session or cookie. Default middleware uses it to determine current timezone.
h2. USAGE
h3. Example:
Assume that we have Profile model which contains ,,timezone'' field and MeetUp model with ,,start'' field:
Now we want to switch timezone according to user settings for every request. This can be done through simple middleware:
When you want display your meet ups in template you can use to_global_tz filter which converts it to currently used timezone:
In forms you should use LocalizedDateTimeField (or it's split version), which is multi value field (datettime + timezone):
This form renders as follows:
I think that in most cases you don't want to show timezone subfield to the user. To hide it use HiddenInput widget:
h3. Use UTC
From pytz docs: ,,UTC is Universal Time, also known as Greenwich Mean Time or GMT in the United Kingdom. All other timezones are given as offsets from UTC. No daylight savings time occurs in UTC, making it a useful timezone to perform date arithmetic without worrying about the confusion and ambiguities caused by daylight savings time transitions, your country changing its timezone, or mobile computers that move roam through multiple timezones.''
I think it's better to keep all datetime values in UTC in database and convert them to other default timezone (for example with middleware and global cache).
h2. TESTING
Just add django_tz to INSTALLED_APPS and run: ./manage.py test django_tz.
h2. TODO