search

mfogel / django-timezone-field

A Django app providing DB, form, and REST framework fields for zoneinfo and pytz timezone objects.
BSD 2-Clause "Simplified" License
397 stars 96 forks source link
django python timezones

readme

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:

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.

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 should be necessary when switching from pytz to zoneinfo.

Examples

Database Field

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

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: <DstTzInfo 'Europe/Berlin' LMT+0:53:00 STD>
my_form.cleaned_data["tz4"]  # value returned as zoneinfo: zoneinfo.ZoneInfo(key='Europe/Berlin')

REST Framework Serializer Field

from rest_framework import serializers
from timezone_field.rest_framework import TimeZoneSerializerField

class MySerializer(serializers.Serializer):
    tz1 = TimeZoneSerializerField(use_pytz=True)
    tz2 = TimeZoneSerializerField(use_pytz=False)

my_serializer = MySerializer(data={
    "tz1": "America/Argentina/Buenos_Aires",
    "tz2": "America/Argentina/Buenos_Aires",
})
my_serializer.is_valid()
my_serializer.validated_data["tz1"]  # <DstTzInfo 'America/Argentina/Buenos_Aires' LMT-1 day, 20:06:00 STD>
my_serializer.validated_data["tz2"]  # zoneinfo.ZoneInfo(key='America/Argentina/Buenos_Aires')

Installation

Releases are hosted on pypi and can be installed using various python packaging tools.

# with poetry
poetry add django-timezone-field

# with pip
pip install django-timezone-field

Running the tests

From the repository root, with poetry:

poetry install
poetry run pytest

Changelog

7.0 (2024-07-07)

6.1.0 (2023-11-25)

6.0.1 (2023-09-07)

6.0 (2023-08-20)

5.1 (2023-06-18)

5.0 (2022-02-08)

4.2.3 (2022-01-13)

4.2.1 (2021-07-07)

4.2 (2021-07-07)

4.1.2 (2021-03-17)

4.1.1 (2020-11-28)

4.1 (2020-11-28)

4.0 (2019-12-03)

3.1 (2019-10-02)

3.0 (2018-09-15)

2.1 (2018-03-01)

2.0 (2016-01-31)

1.3 (2015-10-12)

1.2 (2015-02-05)

1.1 (2014-10-05)

1.0 (2013-08-04)

Credits

Originally adapted from Brian Rosner's django-timezones.

Made possible thanks to the work of the contributors.