1# django-timezone-field 2 3[![CI](https://github.com/mfogel/django-timezone-field/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mfogel/django-timezone-field/actions) 4[![codecov](https://codecov.io/gh/mfogel/django-timezone-field/branch/main/graph/badge.svg?token=Rwekzmim3l)](https://codecov.io/gh/mfogel/django-timezone-field) 5[![pypi downloads](https://img.shields.io/pypi/dm/django-timezone-field.svg)](https://pypi.python.org/pypi/django-timezone-field/) 6[![pypi python support](https://img.shields.io/pypi/pyversions/django-timezone-field.svg)](https://pypi.python.org/pypi/django-timezone-field/) 7[![pypi django support](https://img.shields.io/pypi/djversions/django-timezone-field.svg)](https://pypi.python.org/pypi/django-timezone-field/) 8 9A Django app providing database, form and serializer fields for [pytz](http://pypi.python.org/pypi/pytz/) timezone objects. 10 11## Examples 12 13### Database Field 14 15```py 16import pytz 17from django.db import models 18from timezone_field import TimeZoneField 19 20class MyModel(models.Model): 21 tz1 = TimeZoneField(default='Europe/London') # defaults supported 22 tz2 = TimeZoneField() # in ModelForm displays like "America/Los Angeles" 23 tz3 = TimeZoneField(choices_display='WITH_GMT_OFFSET') # in ModelForm displays like "GMT-08:00 America/Los Angeles" 24 25my_model = MyModel( 26 tz1='America/Los_Angeles', # assignment of a string 27 tz2=pytz.timezone('Turkey'), # assignment of a pytz.DstTzInfo 28 tz3=pytz.UTC, # assignment of pytz.UTC singleton 29) 30my_model.full_clean() # validates against pytz.common_timezones by default 31my_model.save() # values stored in DB as strings 32my_model.tz1 # values retrieved as pytz objects: <DstTzInfo 'America/Los_Angeles' PST-1 day, 16:00:00 STD> 33``` 34 35### Form Field 36 37```py 38from django import forms 39from timezone_field import TimeZoneFormField 40 41class MyForm(forms.Form): 42 tz = TimeZoneFormField() # displays like "America/Los Angeles" 43 tz2 = TimeZoneFormField(choices_display='WITH_GMT_OFFSET') # displays like "GMT-08:00 America/Los Angeles" 44 45my_form = MyForm({'tz': 'America/Los_Angeles'}) 46my_form.full_clean() # validates against pytz.common_timezones by default 47my_form.cleaned_data['tz'] # values retrieved as pytz objects: <DstTzInfo 'America/Los_Angeles' PST-1 day, 16:00:00 STD> 48``` 49 50### REST Framework Serializer Field 51 52```py 53import pytz 54from rest_framework import serializers 55from timezone_field.rest_framework import TimeZoneSerializerField 56 57class MySerializer(serializers.Serializer): 58 tz1 = TimeZoneSerializerField() 59 tz2 = TimeZoneSerializerField() 60 61my_serializer = MySerializer(data={ 62 'tz1': 'America/Argentina/Buenos_Aires', 63 'tz2': pytz.timezone('America/Argentina/Buenos_Aires'), 64}) 65my_serializer.is_valid() # true 66my_serializer.validated_data['tz1'] # <DstTzInfo 'America/Argentina/Buenos_Aires' LMT-1 day, 20:06:00 STD> 67my_serializer.validated_data['tz2'] # <DstTzInfo 'America/Argentina/Buenos_Aires' LMT-1 day, 20:06:00 STD> 68``` 69 70## Installation 71 72Install from [`pypi`](https://pypi.org/project/django-timezone-field/) 73 74```sh 75pip install django-timezone-field 76``` 77 78## Running the tests 79 80From the repository root, with [`poetry`](https://python-poetry.org/) 81 82```sh 83poetry install 84poetry run pytest 85``` 86 87## Changelog 88 89#### 4.2.3 (2022-01-13) 90 91* Fix sdist installs ([#78](https://github.com/mfogel/django-timezone-field/issues/78)) 92* Officially support python 3.10 93 94#### 4.2.1 (2021-07-07) 95 96* Reinstate `TimeZoneField.default_choices` ([#76](https://github.com/mfogel/django-timezone-field/issues/76)) 97 98#### 4.2 (2021-07-07) 99 100* Officially support django 3.2, python 3.9 101* Fix bug with field deconstruction ([#74](https://github.com/mfogel/django-timezone-field/issues/74)) 102* Housekeeping: use poetry, github actions, pytest 103 104#### 4.1.2 (2021-03-17) 105 106* Avoid `NonExistentTimeError` during DST transition ([#70](https://github.com/mfogel/django-timezone-field/issues/70)) 107 108#### 4.1.1 (2020-11-28) 109 110* Don't import `rest_framework` from package root ([#67](https://github.com/mfogel/django-timezone-field/issues/67)) 111 112#### 4.1 (2020-11-28) 113 114* Add Django REST Framework serializer field 115* Add new `choices_display` kwarg with supported values `WITH_GMT_OFFSET` and `STANDARD` 116* Deprecate `display_GMT_offset` kwarg 117 118#### 4.0 (2019-12-03) 119 120* Add support for django 3.0, python 3.8 121* Drop support for django 1.11, 2.0, 2.1, python 2.7, 3.4 122 123#### 3.1 (2019-10-02) 124 125* Officially support django 2.2 (already worked) 126* Add option to display TZ offsets in form field ([#46](https://github.com/mfogel/django-timezone-field/issues/46)) 127 128#### 3.0 (2018-09-15) 129 130* Support django 1.11, 2.0, 2.1 131* Add support for python 3.7 132* Change default human-readable timezone names to exclude underscores ([#32](https://github.com/mfogel/django-timezone-field/issues/32) & [#37](https://github.com/mfogel/django-timezone-field/issues/37)) 133 134#### 2.1 (2018-03-01) 135 136* Add support for django 1.10, 1.11 137* Add support for python 3.6 138* Add wheel support 139* Support bytes in DB fields ([#38](https://github.com/mfogel/django-timezone-field/issues/38) & [#39](https://github.com/mfogel/django-timezone-field/issues/39)) 140 141#### 2.0 (2016-01-31) 142 143* Drop support for django 1.7, add support for django 1.9 144* Drop support for python 3.2, 3.3, add support for python 3.5 145* Remove tests from source distribution 146 147#### 1.3 (2015-10-12) 148 149* Drop support for django 1.6, add support for django 1.8 150* Various [bug fixes](https://github.com/mfogel/django-timezone-field/issues?q=milestone%3A1.3) 151 152#### 1.2 (2015-02-05) 153 154* For form field, changed default list of accepted timezones from `pytz.all_timezones` to `pytz.common_timezones`, to match DB field behavior. 155 156#### 1.1 (2014-10-05) 157 158* Django 1.7 compatibility 159* Added support for formatting `choices` kwarg as `[[<str>, <str>], ...]`, in addition to previous format of `[[<pytz.timezone>, <str>], ...]`. 160* Changed default list of accepted timezones from `pytz.all_timezones` to `pytz.common_timezones`. If you have timezones in your DB that are in `pytz.all_timezones` but not in `pytz.common_timezones`, this is a backward-incompatible change. Old behavior can be restored by specifying `choices=[(tz, tz) for tz in pytz.all_timezones]` in your model definition. 161 162#### 1.0 (2013-08-04) 163 164* Initial release as `timezone_field`. 165 166## Credits 167 168Originally adapted from [Brian Rosner's django-timezones](https://github.com/brosner/django-timezones). 169 170Made possible thanks to the work of the [contributors](https://github.com/mfogel/django-timezone-field/graphs/contributors). 171