Description

# django-timezone-field [](https://github.com/mfogel/django-timezone-field/actions) [](https://codecov.io/gh/mfogel/django-timezone-field) [](https://pypi.python.org/pypi/django-timezone-field/) [](https://pypi.python.org/pypi/django-timezone-field/) [](https://pypi.python.org/pypi/django-timezone-field/) A Django app providing DB, form, and REST framework fields for [`zoneinfo`](https://docs.python.org/3/library/zoneinfo.html) and [`pytz`](http://pypi.python.org/pypi/pytz/) timezone objects. ## The transition from `pytz` to `zoneinfo` Like Django, this app supports both `pytz` and `zoneinfo` objects while the community transitions away from `pytz` to `zoneinfo`. All exposed fields and functions that return a timezone object accept an optional boolean kwarg `use_pytz`. If not explicitly specified, the default value used for `use_pytz` matches Django's behavior: - Django <= 3.X: `use_pytz` defaults to `True` - Django == 4.X: `use_pytz` defaults to the value of [`django.conf.settings.USE_DEPRECATED_PYTZ`](https://docs.djangoproject.com/en/4.0/ref/settings/#use-deprecated-pytz), which itself defaults to `False` - Django >= 5.X: [drops support for `pytz` altogether](https://docs.djangoproject.com/en/5.0/releases/5.0/#features-removed-in-5-0), and this app has done the same. Note that this app does _not_ declare `pytz` to be a dependency, so if you're using this app with `use_pytz=True`, you'll need to ensure `pytz` is included in the environment yourself. ### Differences in recognized timezones between `pytz` and `zoneinfo` `pytz` and `zoneinfo` search for timezone data differently. - `pytz` bundles and searches within its own copy of the [IANA timezone DB](https://www.iana.org/time-zones) - `zoneinfo` first searches the local system's timezone DB for a match. If no match is found, it then searches within the [`tzdata`](https://pypi.org/project/tzdata/) package _if it is installed_. The `tzdata` package contains a copy of the IANA timezone DB. If the local system's timezone DB doesn't cover the entire IANA timezone DB and the `tzdata` package is not installed, you may run across errors like `ZoneInfoNotFoundError: 'No time zone found with key Pacific/Kanton'` for seemingly valid timezones when transitioning from `pytz` to `zoneinfo`. The easy fix is to add `tzdata` to your project with `poetry add tzdata` or `pip install tzdata`. Assuming you have the `tzdata` package installed if needed, no [data migration](https://docs.djangoproject.com/en/4.0/topics/migrations/#data-migrations) should be necessary when switching from `pytz` to `zoneinfo`. ## Examples ### Database Field ```python import zoneinfo import pytz from django.db import models from timezone_field import TimeZoneField class MyModel(models.Model): tz1 = TimeZoneField(default="Asia/Dubai") # defaults supported, in ModelForm renders like "Asia/Dubai" tz2 = TimeZoneField(choices_display="WITH_GMT_OFFSET") # in ModelForm renders like "GMT+04:00 Asia/Dubai" tz3 = TimeZoneField(use_pytz=True) # returns pytz timezone objects tz4 = TimeZoneField(use_pytz=False) # returns zoneinfo objects my_model = MyModel( tz2="America/Vancouver", # assignment of a string tz3=pytz.timezone("America/Vancouver"), # assignment of a pytz timezone tz4=zoneinfo.ZoneInfo("America/Vancouver"), # assignment of a zoneinfo ) my_model.full_clean() # validates against pytz.common_timezones by default my_model.save() # values stored in DB as strings my_model.tz3 # value returned as pytz timezone: <DstTzInfo 'America/Vancouver' LMT-1 day, 15:48:00 STD> my_model.tz4 # value returned as zoneinfo: zoneinfo.ZoneInfo(key='America/Vancouver') my_model.tz1 = "UTC" # assignment of a string, immediately converted to timezone object my_model.tz1 # zoneinfo.ZoneInfo(key='UTC') or pytz.utc, depending on use_pytz default my_model.tz2 = "Invalid/Not_A_Zone" # immediately raises ValidationError ``` ### Form Field ```python from django import forms from timezone_field import TimeZoneFormField class MyForm(forms.Form): tz1 = TimeZoneFormField() # renders like "Asia/Dubai" tz2 = TimeZoneFormField(choices_display="WITH_GMT_OFFSET") # renders like "GMT+04:00 Asia/Dubai" tz3 = TimeZoneFormField(use_pytz=True) # returns pytz timezone objects tz4 = TimeZoneFormField(use_pytz=False) # returns zonei