| single |
# django-timezone-field
[CI]
[codecov]
[pypi downloads]
[pypi python support]
[pypi django support]
A Django app providing DB, form, and REST framework fields for
[`zoneinfo`] and [`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`],
which itself defaults to `False`
- Django >= 5.X: django plans to
[drop support for `pytz` altogether],
and this app will likely do the same.
When switching between `pytz` and `zoneinfo`, in general a
[data migration] is _not_ needed, as both
libraries recognize the same set of strings as valid timezones. Exceptions
to that include if your local system has an
unusual set of time zones installed, or if you are using the `Factory`
timezone which `zoneinfo` recognizes but `pytz`
does not.
## 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:
my_model.tz4 # value returned as zoneinfo:
zoneinfo.ZoneInfo(key='America/Vancouver')
```
### 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
zoneinfo objects
my_form = MyForm({"tz3": "Europe/Berlin", "tz4": "Europe/Berlin"})
my_form.full_clean() # validates against pytz.common_timezones by
default
my_form.cleaned_data["tz3"] # value returned as pytz timezone:
my_form.cleaned_data["tz4"] # value returned as zoneinfo:
zoneinfo.ZoneInfo(key='Europe/Berlin')
```
### REST Framework Serializer Field
```python
|