django-timezone-field
=====================

.. image:: https://img.shields.io/travis/mfogel/django-timezone-field.svg
   :target: https://travis-ci.org/mfogel/django-timezone-field/

.. image:: https://img.shields.io/coveralls/mfogel/django-timezone-field.svg
   :target: https://coveralls.io/r/mfogel/django-timezone-field/

.. image:: https://img.shields.io/pypi/dm/django-timezone-field.svg
   :target: https://pypi.python.org/pypi/django-timezone-field/

A Django app providing database and form fields for `pytz`__ timezone objects.

Examples
--------

Database Field
~~~~~~~~~~~~~~

.. code:: python

    import pytz
    from django.db import models
    from timezone_field import TimeZoneField

    class MyModel(models.Model):
        tz1 = TimeZoneField(default='Europe/London')            # defaults supported
        tz2 = TimeZoneField()                                   # in ModelForm displays like "America/Los Angeles"
        tz3 = TimeZoneField(choices_display='WITH_GMT_OFFSET')  # in ModelForm displays like "GMT-08:00 America/Los Angeles"

    my_model = MyModel(
        tz1='America/Los_Angeles',    # assignment of a string
        tz2=pytz.timezone('Turkey'),  # assignment of a pytz.DstTzInfo
        tz3=pytz.UTC,                 # assignment of pytz.UTC singleton
    )
    my_model.full_clean() # validates against pytz.common_timezones by default
    my_model.save()       # values stored in DB as strings
    my_model.tz1          # values retrieved as pytz objects: <DstTzInfo 'America/Los_Angeles' PST-1 day, 16:00:00 STD>


Form Field
~~~~~~~~~~

.. code:: python

    from django import forms
    from timezone_field import TimeZoneFormField

    class MyForm(forms.Form):
        tz = TimeZoneFormField()                                    # displays like "America/Los Angeles"
        tz2 = TimeZoneFormField(choices_display='WITH_GMT_OFFSET')  # displays like "GMT-08:00 America/Los Angeles"

    my_form = MyForm({'tz': 'America/Los_Angeles'})
    my_form.full_clean()        # validates against pytz.common_timezones by default
    my_form.cleaned_data['tz']  # values retrieved as pytz objects: <DstTzInfo 'America/Los_Angeles' PST-1 day, 16:00:00 STD>


REST Framework Serializer Field
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

    import pytz
    from rest_framework import serializers
    from timezone_field import TimeZoneSerializerField

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

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


Installation
------------

#.  From `pypi`__ using `pip`__:

    .. code:: sh

        pip install django-timezone-field

#.  Add `timezone_field` to your `settings.INSTALLED_APPS`__:

    .. code:: python

        INSTALLED_APPS = (
            ...
            'timezone_field',
            ...
        )

Changelog
------------

*   4.1 (2020-11-28)

    *   Add Django REST Framework serializer field
    *   Add new `choices_display` kwarg with supported values `WITH_GMT_OFFSET` and `STANDARD`
    *   Deprecate `display_GMT_offset` kwarg

*   4.0 (2019-12-03)

    *   Add support for django 3.0, python 3.8
    *   Drop support for django 1.11, 2.0, 2.1, python 2.7, 3.4

*   3.1 (2019-10-02)

    *   Officially support django 2.2 (already worked)
    *   Add option to display TZ offsets in form field `#46`__

*   3.0 (2018-09-15)

    *   Support django 1.11, 2.0, 2.1
    *   Add support for python 3.7
    *   Change default human-readable timezone names to exclude underscores
        (`#32`__ & `#37`__)

*   2.1 (2018-03-01)

    *   Add support for django 1.10, 1.11
    *   Add support for python 3.6
    *   Add wheel support
    *   Support bytes in DB fields (`#38`__ & `#39`__)

*   2.0 (2016-01-31)

    *   Drop support for django 1.7, add support for django 1.9
    *   Drop support for python 3.2, 3.3, add support for python 3.5
    *   Remove tests from source distribution

*   1.3 (2015-10-12)

    *   Drop support for django 1.6, add support for django 1.8
    *   Various `bug fixes`__

*   1.2 (2015-02-05)

    *   For form field, changed default list of accepted timezones from
        `pytz.all_timezones` to `pytz.common_timezones`, to match DB field
        behavior.

*   1.1 (2014-10-05)

    *   Django 1.7 compatibility
    *   Added support for formatting `choices` kwarg as `[[<str>, <str>], ...]`,
        in addition to previous format of `[[<pytz.timezone>, <str>], ...]`.
    *   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.

*   1.0 (2013-08-04)

    *   Initial release as `timezone_field`.


Running the Tests
-----------------

#.  Install `tox`__.

#.  From the repository root, run

    .. code:: sh

        tox

    Postgres will need to be running locally, and sqlite will need to be
    installed in order for tox to do its job.

Found a Bug?
------------

To file a bug or submit a patch, please head over to `django-timezone-field on github`__.

Credits
-------

Originally adapted from `Brian Rosner's django-timezones`__. The full list of contributors is available on `github`__.


__ http://pypi.python.org/pypi/pytz/
__ http://pypi.python.org/pypi/django-timezone-field/
__ http://www.pip-installer.org/
__ https://docs.djangoproject.com/en/dev/ref/settings/#installed-apps
__ https://github.com/mfogel/django-timezone-field/issues/46
__ https://github.com/mfogel/django-timezone-field/issues/32
__ https://github.com/mfogel/django-timezone-field/issues/37
__ https://github.com/mfogel/django-timezone-field/issues/38
__ https://github.com/mfogel/django-timezone-field/issues/39
__ https://github.com/mfogel/django-timezone-field/issues?q=milestone%3A1.3
__ https://tox.readthedocs.org/
__ https://github.com/mfogel/django-timezone-field/
__ https://github.com/brosner/django-timezones/
__ https://github.com/mfogel/django-timezone-field/graphs/contributors
