change drf flagfield to multiplechoicefield, work on docs

Author: bckohan

doc/source/howto/index.rst

@@ -40,8 +40,8 @@ are possible with :class:`~django_enum.fields.EnumField`. See :ref:`enum_props`.
 
    external
    options
-   integrations
    flags
    forms
+   integrations
    migrations
    urls

doc/source/howto/integrations.rst

@@ -84,8 +84,13 @@ By default `DRF ModelSerializer
 `ChoiceField <https://www.django-rest-framework.org/api-guide/fields/#choicefield>`_ to represent an
 :class:`~django_enum.fields.EnumField`. This works great, but it will not accept :ref:`symmetric
 enumeration values <enum-properties:howto_symmetric_properties>`. A serializer field
-:class:`~django_enum.drf.EnumField` is provided that will. The dependency on DRF_ is optional so
-to use the provided serializer field you must install DRF_:
+:class:`django_enum.drf.EnumField` is provided that will. :class:`~django_enum.fields.FlagField`
+fields do not work well with DRF's builtin
+`MultipleChoiceField <https://www.django-rest-framework.org/api-guide/fields/#multiplechoicefield>`_
+so we provide also provide a :class:`django_enum.drf.FlagField`.
+
+The dependency on DRF_ is optional so to use the provided serializer field you must install DRF_:
+
 
 .. code:: bash
 
@@ -97,7 +102,7 @@ to use the provided serializer field you must install DRF_:
 
 
 
-The serializer :class:`~django_enum.drf.EnumField` accepts any arguments that
+The serializer :class:`django_enum.drf.EnumField` accepts any arguments that
 `ChoiceField <https://www.django-rest-framework.org/api-guide/fields/#choicefield>`_ does. It also
 accepts the ``strict`` parameter which behaves the same way as it does on the model field.
 
@@ -110,14 +115,28 @@ accepts the ``strict`` parameter which behaves the same way as it does on the mo
     2. You have non-strict model fields and want to allow your API to accept values outside of
        the enumeration.
 
+The :class:`django_enum.drf.EnumField` must be used for any :class:`~django_enum.fields.FlagField`
+fields. It will accept a composite integer or a list of any values coercible to a flag. The
+serialized output will be an composite integer holding the full bitfield.
+
+ModelSerializers
+~~~~~~~~~~~~~~~~
+
+An :class:`django_enum.drf.EnumFieldMixin` class is provided that when added to
+`ModelSerializers <https://www.django-rest-framework.org/api-guide/serializers/#modelserializer>`_
+will be sure that the serializer instantiates the correct django-enum serializer field type:
+
+.. literalinclude:: ../../../tests/examples/drf_modelserializer_howto.py
+    :lines: 3-
+
 .. _filtering:
 
 django-filter
 -------------
 
 As shown above, filtering by any value, enumeration type instance or symmetric value works with
 :doc:`Django's ORM <django:topics/db/queries>`. This is not natively true for the default
-:doc:`FilterSet <django-filter:ref/filterset>` from :doc:`django-filter <django-filter:index>`.
+:class:`django_filters.filterset.FilterSet` from :doc:`django-filter <django-filter:index>`.
 Those filter sets will only be filterable by direct enumeration value by default. An
 :class:`~django_enum.filters.EnumFilter` class is provided to enable filtering by symmetric property
 values, but since the dependency on :doc:`django-filter <django-filter:index>` is optional, you must
@@ -128,11 +147,24 @@ first install it:
        pip install django-filter
 
 .. literalinclude:: ../../../tests/examples/filterfield_howto.py
-    :lines: 3-
+    :lines: 2-
 
-An :class:`~django_enum.filters.FilterSet` class is also provided that uses
+A :class:`~django_enum.filters.FilterSet` class is also provided that uses
 :class:`~django_enum.filters.EnumFilter` for :class:`~django_enum.fields.EnumField` by default.
 So the above is also equivalent to:
 
 .. literalinclude:: ../../../tests/examples/filterset_howto.py
     :lines: 3-
+
+.. tip::
+
+    :class:`~django_enum.filters.FilterSet` may also be used as a mixin.
+
+
+FlagFields
+~~~~~~~~~~
+
+An :class:`~django_enum.filters.EnumFlagFilter` field for flag fields is also provided:
+
+.. literalinclude:: ../../../tests/examples/flagfilterfield_howto.py
+    :lines: 2-

doc/source/howto/migrations.rst

@@ -9,8 +9,11 @@ Write Migrations
 .. important::
 
     There is one rule for writing custom migration files for EnumFields:
-    *Never reference or import your enumeration classes in a migration file,
-    work with the primitive values instead*.
+    **Never reference or import your enumeration classes in a migration file,
+    work with the primitive values instead**. If your :class:`~enum.Enum` class
+    changes over time, this can break older migration files. Always working with
+    primitive values in migrations files will ensure that the migration will be
+    valid to the data as it existed when the migration was generated.
 
 The deconstructed :class:`~django_enum.fields.EnumField` only include the choices tuple in the
 migration files. This is because :class:`enum.Enum` classes may come and go or be
@@ -21,3 +24,15 @@ with choices.
 :class:`~django_enum.fields.EnumField` in migration files will not resolve the field values to
 enumeration types. The fields will be the primitive enumeration values as they
 are with any field with choices.
+
+
+Using :class:`enum.auto`
+------------------------
+
+If your :class:`~django_enum.fields.EnumField` is storing the value as the database column
+(default) it is best to avoid the usage of :class:`enum.auto` because the value for each
+enumerated instance may change which would bring your database out of sync with your
+codebase.
+
+If you have to use :class:`enum.auto` it is best to add integration tests to check for value
+changes.

doc/source/reference/forms.rst

@@ -6,8 +6,52 @@
 Forms
 =====
 
-.. automodule:: django_enum.forms
+Fields
+------
+
+.. autoclass:: django_enum.forms.ChoiceFieldMixin
+   :members:
+   :show-inheritance:
+
+.. autoclass:: django_enum.forms.EnumChoiceField
+   :members:
+   :show-inheritance:
+
+.. autoclass:: django_enum.forms.EnumFlagField
+   :members:
+   :show-inheritance:
+
+.. autoclass:: django_enum.forms.EnumMultipleChoiceField
+   :members:
+   :show-inheritance:
+
+Widgets
+-------
+
+.. autoclass:: django_enum.forms.NonStrictSelect
+   :members:
+   :show-inheritance:
+
+.. autoclass:: django_enum.forms.NonStrictSelectMultiple
+   :members:
+   :show-inheritance:
+
+.. autoclass:: django_enum.forms.FlagSelectMultiple
+   :members:
+   :show-inheritance:
+
+.. autoclass:: django_enum.forms.FlagCheckbox
+   :members:
+   :show-inheritance:
+
+.. autoclass:: django_enum.forms.NonStrictFlagSelectMultiple
+   :members:
+   :show-inheritance:
+
+.. autoclass:: django_enum.forms.NonStrictFlagCheckbox
+   :members:
+   :show-inheritance:
+
+.. autoclass:: django_enum.forms.NonStrictRadioSelect
    :members:
-   :undoc-members:
    :show-inheritance:
-   :private-members:

src/django_enum/drf.py

@@ -20,6 +20,7 @@
     Field,
     FloatField,
     IntegerField,
+    MultipleChoiceField,
     TimeField,
 )
 from rest_framework.serializers import ModelSerializer
@@ -175,7 +176,7 @@ def to_representation(self, value: Any) -> Any:
         return getattr(value, "value", value)
 
 
-class FlagField(ChoiceField):
+class FlagField(MultipleChoiceField):
     """
     A djangorestframework serializer field for :class:`~enum.Flag` types. If
     unspecified ModelSerializers will assign :class:`~django_enum.fields.FlagField`
@@ -264,7 +265,7 @@ def build_standard_field(self, field_name, model_field):
         To use this mixin, include it before ModelSerializer in your
         serializer's class hierarchy:
 
-        ..code-block:: python
+        .. code-block:: python
 
             from django_enum.drf import EnumFieldMixin
             from rest_framework.serializers import ModelSerializer

tests/examples/drf_modelserializer_howto.py

@@ -0,0 +1,18 @@
+from .models import TextChoicesExample
+
+from django_enum.drf import EnumFieldMixin
+from rest_framework import serializers
+
+
+class ExampleModelSerializer(EnumFieldMixin, serializers.Serializer):
+
+    class Meta:
+        model = TextChoicesExample
+
+
+ser = ExampleModelSerializer(
+    data={
+        'color': (1, 0, 0),
+    }
+)
+assert ser.is_valid()

tests/examples/drf_serializer_howto.py

@@ -1,13 +1,24 @@
-from .models import TextChoicesExample
+from .models import TextChoicesExample, Constellation
 
-from django_enum.drf import EnumField
+from django_enum.drf import EnumField, FlagField
 from rest_framework import serializers
 
 
 class ExampleSerializer(serializers.Serializer):
 
     color = EnumField(TextChoicesExample.Color)
+    
+    # from the flags tutorial
+    constellation = FlagField(Constellation)
 
 
-ser = ExampleSerializer(data={'color': (1, 0, 0)})
+ser = ExampleSerializer(
+    data={
+        'color': (1, 0, 0),
+        'constellation': [
+            Constellation.GALILEO.name,
+            Constellation.GPS.name
+        ]
+    }
+)
 assert ser.is_valid()

tests/examples/flagfilterfield_howto.py

@@ -0,0 +1,21 @@
+from .models import Constellation, GNSSReceiver
+from django_enum.filters import EnumFlagFilter
+from django_filters.views import FilterView
+from django_filters import FilterSet
+
+
+class FlagExampleFilterViewSet(FilterView):
+
+    class FlagExampleFilter(FilterSet):
+
+        constellation = EnumFlagFilter(enum=Constellation)
+
+        class Meta:
+            model = GNSSReceiver
+            fields = '__all__'
+
+    filterset_class = FlagExampleFilter
+    model = GNSSReceiver
+
+# now filtering by flags works:
+# e.g.:  /?constellation=GPS&constellation=GLONASS

tests/examples/urls_howto.py

@@ -4,6 +4,7 @@
     from .filterset_howto import (
         TextChoicesExampleFilterViewSet as TextChoicesExampleFilterSetViewSet
     )
+    from .flagfilterfield_howto import FlagExampleFilterViewSet
 
     app_name = "howto"
 
@@ -18,6 +19,7 @@
             TextChoicesExampleFilterSetViewSet.as_view(),
             name='filterset'
         ),
+        path('flagfilterfield/', FlagExampleFilterViewSet.as_View(), name="flagfilterfield")
     ]
 except ImportError:
     urlpatterns = []

tests/test_examples.py

@@ -305,6 +305,10 @@ def test_text_choices_howto(self):
     def test_drf_serializer_howto(self):
         from tests.examples import drf_serializer_howto
 
+    @pytest.mark.skipif(not DJANGO_REST_FRAMEWORK, reason="DRF not installed")
+    def test_drf_modelserializer_howto(self):
+        from tests.examples import drf_modelserializer_howto
+
     def _filterset_webcheck(self, name):
         from tests.examples.models import TextChoicesExample
         from django.urls import reverse
@@ -358,6 +362,13 @@ def test_filterfield_howto(self):
 
         self._filterset_webcheck("howto:filterfield")
 
+    @pytest.mark.skipif(not DJANGO_FILTERS, reason="django-filters not installed")
+    def test_flagfilterfield_howto(self):
+        from tests.examples import flagfilterfield_howto
+
+        # TODO
+        # self._filterset_webcheck("howto:flagfilterfield")
+
     @pytest.mark.skipif(not DJANGO_FILTERS, reason="django-filters not installed")
     def test_filterset_howto(self):
         from tests.examples import filterset_howto