feat: add Django REST Framework serializer field

Closes #65

Squashed commit of the following:

commit 1009c88
Author: Mike Fogel <mike@fogel.ca>
Date:   Fri Nov 20 11:08:00 2020 -0300

    feat: add docs

commit 7086221
Author: Mike Fogel <mike@fogel.ca>
Date:   Fri Nov 20 11:05:15 2020 -0300

    chore: add test, allow for easier imports

commit 9b9dc45
Author: starryrbs <1322096624@qq.com>
Date:   Mon Nov 16 14:45:29 2020 +0800

    fix the problem: line too long

commit 3506476
Merge: b425511 58542a9
Author: starryrbs <1322096624@qq.com>
Date:   Mon Nov 16 14:36:48 2020 +0800

    Merge remote-tracking branch 'origin/master'

commit b425511
Author: starryrbs <1322096624@qq.com>
Date:   Mon Nov 16 14:36:35 2020 +0800

    add django_rest_framework TimeZoneField  representation test

commit 58542a9
Merge: 1f0de71 63b8828
Author: starryrbs <35923714+starryrbs@users.noreply.github.com>
Date:   Mon Nov 16 14:23:29 2020 +0800

    Merge branch 'master' into master

commit 1f0de71
Author: starryrbs <1322096624@qq.com>
Date:   Mon Nov 16 14:18:44 2020 +0800

    add django_rest_framework TimeZoneField test

commit c87d384
Author: starryrbs <1322096624@qq.com>
Date:   Mon Nov 9 17:59:41 2020 +0800

    Add django rest framework support

README.rst

@@ -62,6 +62,28 @@ Form Field
     repr(tz)                               # "<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
 ------------
 
@@ -84,6 +106,10 @@ Installation
 Changelog
 ------------
 
+*   master
+
+    *   Add Django REST Framework serializer field
+
 *   4.0 (2019-12-03)
 
     *   Add support for django 3.0, python 3.8

setup.py

@@ -36,6 +36,9 @@ def find_version(*file_paths):
         'timezone_field',
     ],
     install_requires=['django>=2.2', 'pytz'],
+    extras_require={
+        'rest_framework': ['djangorestframework>=3.0.0']
+    },
     python_requires='>=3.5',
     classifiers=[
         'Development Status :: 4 - Beta',

tests/settings.py

@@ -37,6 +37,7 @@
     'django.contrib.staticfiles',
     'timezone_field',
     'tests',
+    'rest_framework'
 )
 
 MIDDLEWARE_CLASSES = (

tests/tests.py

@@ -7,8 +7,11 @@
 from django.db import models
 from django.db.migrations.writer import MigrationWriter
 from django.test import TestCase
+from rest_framework import serializers
 
-from timezone_field import TimeZoneField, TimeZoneFormField
+from timezone_field import (
+    TimeZoneField, TimeZoneFormField, TimeZoneSerializerField,
+)
 from timezone_field.utils import add_gmt_offset_to_choices
 from tests.models import TestModel
 
@@ -81,8 +84,8 @@ def test_default_human_readable_choices_dont_have_underscores(self):
 class TestFormInvalidChoice(forms.Form):
     tz = TimeZoneFormField(
         choices=(
-            [(tz, tz) for tz in pytz.all_timezones] +
-            [(INVALID_TZ, pytz.UTC)]
+            [(tz, tz) for tz in pytz.all_timezones]
+            + [(INVALID_TZ, pytz.UTC)]
         )
     )
 
@@ -453,3 +456,29 @@ def test_add_gmt_offset_to_choices(self):
         ]
         for i in range(len(expected)):
             self.assertEqual(expected[i], result[i][1])
+
+
+class TimeZoneSerializer(serializers.Serializer):
+    tz = TimeZoneSerializerField()
+
+
+class TimeZoneSerializerFieldTestCase(TestCase):
+    def test_invalid_str(self):
+        serializer = TimeZoneSerializer(data={'tz': INVALID_TZ})
+        self.assertFalse(serializer.is_valid())
+
+    def test_valid(self):
+        serializer = TimeZoneSerializer(data={'tz': PST})
+        self.assertTrue(serializer.is_valid())
+        self.assertEqual(serializer.validated_data['tz'], PST_tz)
+
+    def test_valid_representation(self):
+        serializer = TimeZoneSerializer(data={'tz': PST})
+        self.assertTrue(serializer.is_valid())
+        self.assertEqual(serializer.data['tz'], PST)
+
+    def test_valid_with_timezone_object(self):
+        serializer = TimeZoneSerializer(data={'tz': PST_tz})
+        self.assertTrue(serializer.is_valid())
+        self.assertEqual(serializer.data['tz'], PST)
+        self.assertEqual(serializer.validated_data['tz'], PST_tz)

timezone_field/__init__.py

@@ -1,5 +1,6 @@
 from timezone_field.fields import TimeZoneField
 from timezone_field.forms import TimeZoneFormField
+from timezone_field.rest_framework import TimeZoneSerializerField
 
 __version__ = '4.0'
-__all__ = ['TimeZoneField', 'TimeZoneFormField']
+__all__ = ['TimeZoneField', 'TimeZoneFormField', 'TimeZoneSerializerField']

timezone_field/rest_framework.py

@@ -0,0 +1,19 @@
+import pytz
+from django.utils.translation import gettext_lazy as _
+from django.utils.encoding import force_str
+from rest_framework.fields import Field
+
+
+class TimeZoneSerializerField(Field):
+    default_error_messages = {
+        'invalid': _('A valid timezone is required.'),
+    }
+
+    def to_internal_value(self, data):
+        try:
+            return pytz.timezone(force_str(data))
+        except pytz.UnknownTimeZoneError:
+            self.fail('invalid')
+
+    def to_representation(self, value):
+        return str(value)

tox.ini

@@ -13,6 +13,7 @@ envlist =
 commands = coverage run --include='*/timezone_field/*' {envbindir}/django-admin.py test tests
 deps =
     coverage
+    djangorestframework>=3.0.0
     django22: django>=2.2.17,<2.3
     django30: django>=3.0.0,<3.1
     django31: django>=3.1.0,<3.2