Time zones¶
Time zone support was added in Django 1.4, allowing you to store and handle local dates and times. It is highly recommended to store your time objects timezone-aware. Django handles this for you, but it does not provide a way for a user to save their timezone. This module adds support for this.
This module highly recommends you install pytz
along with it, but it is not required. By default, the module
uses the set of common timezones as reported by pytz.common_timezones
. If this is not available, the set as
provided by the CLDR is used instead.
This module provides two different types to store your timezones. The models.TimezoneField
model field uses
the default timezone database and the default form field requests the user to select a timezone based on their location.
This is the recommended approach and most consistent with how timezones are stored internally. You are ensured that you
will always be in the same timezone, and when a location changes its timezone, it is automatically applied.
The other option is to use metazones. These are defined by CLDR and often span multiple cities, i.e. you don’t pick the city and let the system figure out which timezone you are in based on the location, but let the user pick a timezone. This has the advantage that it is more intuitive for the user and results in a much shorter dropdown menu, but has the obvious disadvantage that it does not update automatically when a timezone is changed. It is also unsuitable for accurate historic dates.
The model field uses a datetime.tzinfo
Python object as representation, unless use_tzinfo is set to
False
. If pytz
is not available, setting use_tzinfo to False
is required, as it is not
possible to convert between timezone names and datetime.tzinfo
objects without it.
-
class
internationalflavor.timezone.models.
TimezoneField
(timezones=None, exclude=None, use_tzinfo=True, *args, **kwargs)¶ A model field that allows users to choose their timezone. By default, all timezones in the set of common timezones of pytz are available. Use the
timezones
argument to specify your own timezones, and useexclude
to exclude specific zones.If
use_tzinfo
isTrue
, an instance ofdatetime.tzinfo
is returned. This requirespytz
to be installed. Ifuse_tzinfo
isFalse
, a string is returned instead.
-
class
internationalflavor.timezone.forms.
TimezoneFormField
(timezones=None, exclude=None, *args, **kwargs)¶
-
class
internationalflavor.timezone.models.
MetazoneField
(metazones=None, exclude=None, use_tzinfo=True, display_format='name', *args, **kwargs)¶ A model field that allows users to choose their metazone. By default, all metazones in the CLDR set are available. Use the
metazones
argument to specify your own metazones, and useexclude
to exclude specific zones.If
use_tzinfo
isTrue
, an instance ofdatetime.tzinfo
is returned. This requirespytz
to be installed. Note, however, that only one exemplar timezone tzinfo is returned for the metazone. The exemplar timezone may change over time as cities change their timezones.If
use_tzinfo
isFalse
, a string is returned instead.
-
class
internationalflavor.timezone.forms.
MetazoneFormField
(metazones=None, exclude=None, display_format='name', *args, **kwargs)¶
See also
- Django: Time zones
- Django documentation on time zones