DOCSEARCHbyAlgolia
Submit Docs

django-timezone-field

repository·main·Indexed 19 days ago

https://github.com/mfogel/django-timezone-field

A Django application providing database, form, and Django REST Framework fields for handling IANA timezone objects. It supports both zoneinfo and pytz libraries, offering TimeZoneField for models, TimeZoneFormField for forms, and TimeZoneSerializerField for API serialization.

Tokens
1.3K
Snippets
4
Records
5
Agent score
15%

What's inside django-timezone-field

  1. Transition from pytz to zoneinfo

    main

    This project supports both pytz and zoneinfo to facilitate the community transition.

    Behavior of use_pytz

    All exposed fields and functions accept an optional boolean use_pytz kwarg. If not specified, the default depends on your Django version:

    • Django <= 3.X: Defaults to True.
    • Django == 4.X: Defaults to the value of django.conf.settings.USE_DEPRECATED_PYTZ (which defaults to False).
    • Django >= 5.X: pytz support is dropped; use_pytz is effectively ignored as only zoneinfo is supported.

    Note: This package does not depend on pytz. If you set use_pytz=True, you must ensure pytz is installed in your environment.

    Handling Missing Timezones in zoneinfo

    zoneinfo searches the local system's timezone DB first, then the tzdata package. If you encounter ZoneInfoNotFoundError for valid timezones, install the tzdata package:

    # Using poetry
poetry add tzdata

# Using pip
pip install tzdata

  3. Use TimeZoneFormField in Django Forms

    main

    Use TimeZoneFormField for handling timezone selection in Django forms. It supports the same use_pytz and choices_display arguments as the model 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

  4. Use TimeZoneField in Django Models

    main

    The TimeZoneField stores timezone values as strings in the database but returns timezone objects when accessed. You can control whether it returns pytz or zoneinfo objects using the use_pytz keyword argument.

    Key features:

    • default: Set a default timezone string.
    • choices_display: Controls how timezones are rendered in forms. Use "WITH_GMT_OFFSET" to include the offset (e.g., GMT+04:00 Asia/Dubai) or "STANDARD" for standard names.
    • use_pytz: Boolean. If True, returns pytz objects. If False, returns zoneinfo objects. Note that for Django >= 5.X, pytz is no longer supported and this field will only return zoneinfo objects.
    from django.db import models
from timezone_field import TimeZoneField

class MyModel(models.Model):
    tz1 = TimeZoneField(default="Asia/Dubai")               # defaults supported
    tz2 = TimeZoneField(choices_display="WITH_GMT_OFFSET")  # renders like "GMT+04:00 Asia/Dubai"
    tz3 = TimeZoneField(use_pytz=True)                      # returns pytz timezone objects
    tz4 = TimeZoneField(use_pytz=False)                     # returns zoneinfo objects

# Assignment examples
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
)

  5. Use TimeZoneSerializerField in Django REST Framework

    main

    For API serialization, use TimeZoneSerializerField from timezone_field.rest_framework. It allows you to specify whether the serialized data should be treated as pytz or zoneinfo objects via use_pytz.

    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)