fix coverage - add docs for DRF integration

Author: bckohan

README.rst

@@ -30,7 +30,7 @@
 .. _enumerations: https://docs.python.org/3/library/enum.html#enum.Enum
 .. _ValueError: https://docs.python.org/3/library/exceptions.html#ValueError
 .. _DRY: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
-
+.. _DRF: https://www.django-rest-framework.org
 
 Django Enum
 ###########
@@ -182,11 +182,15 @@ Installation
 .. note::
 
     ``django-enum`` has several optional dependencies that are not pulled in
-    by default. To utilize the
-    `enum-properties <https://pypi.org/project/enum-properties/>`_ choice types
-    you must `pip install enum-properties` and to use the ``EnumFilter`` type
-    for `django-filter <https://pypi.org/project/django-filter/>`_ you
-    must `pip install django-filter`.
+    by default. ``EnumFields`` work seamlessly with all Django apps that
+    work with model fields with choices. Optional integrations are provided
+    with several popular libraries to extend this basic functionality. To
+    utilize the `enum-properties <https://pypi.org/project/enum-properties/>`_
+    choice types you must `pip install enum-properties` and to use the
+    ``EnumFilter`` type for
+    `django-filter <https://pypi.org/project/django-filter/>`_ you
+    must `pip install django-filter`. And to use the DRF_ serializer field you
+    must `pip install djangorestframework`.
 
 If features are utilized that require a missing optional dependency an
 exception will be thrown.

django_enum/tests/settings.py

@@ -56,7 +56,7 @@
 try:
     import rest_framework
     INSTALLED_APPS.insert(0, 'rest_framework')
-except (ImportError, ModuleNotFoundError):
+except (ImportError, ModuleNotFoundError):  # pragma: no cover
     pass
 
 try:

doc/source/index.rst

@@ -134,10 +134,15 @@ Installation
 .. note::
 
     ``django-enum`` has several optional dependencies that are not pulled in
-    by default. To utilize the
-    enum-properties_ choice types you must `pip install enum-properties` and
-    to use the ``EnumFilter`` type for django-filter_ you must
-    `pip install django-filter`.
+    by default. ``EnumFields`` work seamlessly with all Django apps that
+    work with model fields with choices. Optional integrations are provided
+    with several popular libraries to extend this basic functionality. To
+    utilize the `enum-properties <https://pypi.org/project/enum-properties/>`_
+    choice types you must `pip install enum-properties` and to use the
+    ``EnumFilter`` type for
+    `django-filter <https://pypi.org/project/django-filter/>`_ you
+    must `pip install django-filter`. And to use the DRF_ serializer field you
+    must `pip install djangorestframework`.
 
 If features are utilized that require a missing optional dependency an
 exception will be thrown.

doc/source/reference.rst

@@ -45,3 +45,14 @@ Forms
    :undoc-members:
    :show-inheritance:
    :private-members:
+
+
+Serializer Fields
+-----------------
+
+.. automodule:: django_enum.drf
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:
+

doc/source/refs.rst

@@ -14,3 +14,5 @@
 .. _DRY: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
 .. _enum-properties: https://pypi.org/project/enum-properties
 .. _django-filter: https://pypi.org/project/django-filter
+.. _DRF: https://www.django-rest-framework.org
+

doc/source/usage.rst

@@ -290,6 +290,37 @@ would define our form like so:
     </select>
 
 
+.. _rest_framework:
+
+Django Rest Framework
+#####################
+
+By default DRF_ ``ModelSerializer`` will use a ``ChoiceField`` to represent an
+``EnumField``. This works great, but it will not accept symmetric enumeration
+values. A serializer field ``EnumField`` is provided that will. The dependency
+on DRF_ is optional so to use the provided serializer field you must install
+DRF_:
+
+.. code:: bash
+
+    pip install djangorestframework
+
+.. code-block::
+
+    from django_enum.drf import EnumField
+    from rest_framework import serializers
+
+    class ExampleSerializer(serializers.Serializer):
+
+        color = EnumField(TextChoicesExample.Color)
+
+    ser = ExampleSerializer(data={'color': (1, 0, 0)})
+    assert ser.is_valid()
+
+The serializer ``EnumField`` accepts any arguments that ``ChoiceField``. It
+also accepts the ``strict`` parameter that behaves the same as the model
+field's ``strict`` parameter.
+
 .. _filtering:
 
 Filtering