docs for intial release finalized, few more example tests

Author: bckohan

README.rst

@@ -130,9 +130,27 @@ possible very rich enumeration fields.
     # save by any symmetric value
     instance.color = 'FF0000'
     instance.full_clean()
+
+    # access any enum property right from the model field
     assert instance.color.hex == 'ff0000'
+
+    # this also works!
+    assert instance.color == 'ff0000'
+
+    # and so does this!
+    assert instance.color == 'FF0000'
+
     instance.save()
 
+    # filtering works by any symmetric value or enum type instance
+    assert TextChoicesExample.objects.filter(
+        color=TextChoicesExample.Color.RED
+    ).first() == instance
+
+    assert TextChoicesExample.objects.filter(color=(1, 0, 0)).first() == instance
+
+    assert TextChoicesExample.objects.filter(color='FF0000').first() == instance
+
 
 .. note::
 

django_enum/__init__.py

@@ -14,6 +14,10 @@
     IntegerChoices,
     TextChoices,
 )
+from django_enum.filters import (
+    FilterSet,
+    EnumFilter
+)
 from django_enum.fields import (
     EnumBigIntegerField,
     EnumCharField,
@@ -41,7 +45,9 @@
     'IntegerChoices',
     'FloatChoices',
     'DjangoEnumPropertiesMeta',
-    'EnumChoiceField'
+    'EnumChoiceField',
+    'FilterSet',
+    'EnumFilter'
 ]
 
 VERSION = (1, 0, 0)

django_enum/filters.py

@@ -35,7 +35,11 @@ class Color(TextChoices, s('rgb'), s('hex', case_fold=True)):
 
         def __init__(self, *, enum, **kwargs):
             self.enum = enum
-            super().__init__(enum=enum, choices=self.enum.choices, **kwargs)
+            super().__init__(
+                enum=enum,
+                choices=kwargs.pop('choices', self.enum.choices),
+                **kwargs
+            )
 
 
     class FilterSet(filterset.FilterSet):

django_enum/tests/tests.py

@@ -2977,9 +2977,51 @@ def test_color(self):
             # save by any symmetric value
             instance.color = 'FF0000'
             instance.full_clean()
+
+            # access any property right from the model field
             self.assertTrue(instance.color.hex == 'ff0000')
+
+            # this also works!
+            self.assertTrue(instance.color == 'ff0000')
+
+            # and so does this!
+            self.assertTrue(instance.color == 'FF0000')
+
             instance.save()
 
+            self.assertTrue(
+                TextChoicesExample.objects.filter(
+                    color=TextChoicesExample.Color.RED
+                ).first() == instance
+            )
+
+            self.assertTrue(
+                TextChoicesExample.objects.filter(
+                    color=(1, 0, 0)
+                ).first() == instance
+            )
+
+            self.assertTrue(
+                TextChoicesExample.objects.filter(
+                    color='FF0000'
+                ).first() == instance
+            )
+
+            from django_enum import EnumChoiceField
+            from django.forms import ModelForm
+
+            class TextChoicesExampleForm(ModelForm):
+                color = EnumChoiceField(TextChoicesExample.Color)
+
+                class Meta:
+                    model = TextChoicesExample
+                    fields = '__all__'
+
+            # this is possible
+            form = TextChoicesExampleForm({'color': 'FF0000'})
+            form.save()
+            self.assertTrue(form.instance.color == TextChoicesExample.Color.RED)
+
         def test_strict(self):
             from django_enum.tests.examples.models import StrictExample
             obj = StrictExample()
@@ -3010,6 +3052,16 @@ def test_basic(self):
             self.assertTrue(instance.int_enum == MyModel.IntEnum['THREE'])
             self.assertTrue(instance.int_enum.value == 3)
 
+            self.assertRaises(
+                ValueError,
+                MyModel.objects.create,
+                txt_enum='AA',
+                int_enum=3
+            )
+
+            instance.txt_enum='AA'
+            self.assertRaises(ValidationError, instance.full_clean)
+
         def test_no_coerce(self):
             from django_enum.tests.examples.models import NoCoerceExample
 

doc/source/index.rst

@@ -84,14 +84,25 @@ enum-properties_ which makes possible very rich enumeration fields.
         color = EnumField(Color)
 
     instance = MyModel.objects.create(color=MyModel.Color('FF0000'))
-    assert instance.color == MyModel.Color('Red') == MyModel.Color('R') == MyModel.Color((1, 0, 0))
 
-    # save back by any symmetric value
+    assert instance.color == TextChoicesExample.Color('Red')
+    assert instance.color == TextChoicesExample.Color('R')
+    assert instance.color == TextChoicesExample.Color((1, 0, 0))
+
+    # save by any symmetric value or enum type instance
     instance.color = 'FF0000'
     instance.full_clean()
     assert instance.color.hex == 'ff0000'
     instance.save()
 
+    # filtering works by any symmetric value or enum type instance
+    assert TextChoicesExample.objects.filter(
+        color=TextChoicesExample.Color.RED
+    ).first() == instance
+
+    assert TextChoicesExample.objects.filter(color=(1, 0, 0)).first() == instance
+
+    assert TextChoicesExample.objects.filter(color='FF0000').first() == instance
 
 .. note::
 
@@ -125,8 +136,7 @@ Installation
     ``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 <https://pypi.org/project/django-filter/>`_ you must
+    to use the ``EnumFilter`` type for django-filter_ you must
     `pip install django-filter`.
 
 If features are utilized that require a missing optional dependency an

doc/source/refs.rst

@@ -13,3 +13,4 @@
 .. _full_clean: https://docs.djangoproject.com/en/stable/ref/models/instances/#django.db.models.Model.full_clean
 .. _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