add integration tests for all examples and implement coerce parameter

Author: bckohan

README.rst

@@ -100,7 +100,7 @@ possible very rich enumeration fields.
     from django_enum import TextChoices  # use instead of Django's TextChoices
     from django.db import models
 
-    class MyModel(models.Model):
+    class TextChoicesExample(models.Model):
 
         class Color(TextChoices, s('rgb'), s('hex', case_fold=True)):
 
@@ -115,8 +115,12 @@ 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))
+    instance = TextChoicesExample.objects.create(
+        color=TextChoicesExample.Color('FF0000')
+    )
+    assert instance.color == TextChoicesExample.Color('Red')
+    assert instance.color == TextChoicesExample.Color('R')
+    assert instance.color == TextChoicesExample.Color((1, 0, 0))
 
     # direct comparison to any symmetric value also works
     assert instance.color == 'Red'

django_enum/fields.py

@@ -61,6 +61,7 @@ class EnumMixin(
 
     enum: Optional[Type[Choices]] = None
     strict: bool = True
+    coerce: bool = True
 
     def _coerce_to_value_type(self, value: Any) -> Choices:
         """Coerce the value to the enumerations value type"""
@@ -76,16 +77,22 @@ def __init__(
             *args,
             enum: Optional[Type[Choices]] = None,
             strict: bool = strict,
+            coerce: bool = coerce,
             **kwargs
     ):
         self.enum = enum
         self.strict = strict if enum else False
+        self.coerce = coerce if enum else False
         if self.enum is not None:
             kwargs.setdefault('choices', enum.choices if enum else [])
         super().__init__(*args, **kwargs)
 
-    def _try_coerce(self, value: Any) -> Union[Choices, Any]:
-        if self.enum is not None and not isinstance(value, self.enum):
+    def _try_coerce(self, value: Any, force: bool = False) -> Union[Choices, Any]:
+        if (
+            (self.coerce or force)
+            and self.enum is not None
+            and not isinstance(value, self.enum)
+        ):
             try:
                 value = self.enum(value)
             except (TypeError, ValueError):
@@ -167,7 +174,7 @@ def to_python(self, value: Any) -> Union[Choices, Any]:
         :raises ValidationError: If the value is not mappable to a valid
             enumeration
         """
-        if self.enum is None or isinstance(value, self.enum) or value is None:
+        if value is None:
             return value
 
         try:
@@ -196,10 +203,10 @@ def validate(self, value: Any, model_instance: Model):
             if err.code != 'invalid_choice':
                 raise err
         try:
-            self.to_python(value)
-        except ValidationError as err:
+            self._try_coerce(value, force=True)
+        except ValueError as err:
             raise ValidationError(
-                err.message,
+                str(err),
                 code='invalid_choice',
                 params={'value': value}
             ) from err

django_enum/tests/examples/migrations/0001_initial.py

@@ -1,7 +1,7 @@
-# Generated by Django 3.2.14 on 2022-08-09 02:32
+# Generated by Django 3.2.14 on 2022-08-09 03:04
 
-import django_enum.fields
 from django.db import migrations, models
+import django_enum.fields
 
 
 class Migration(migrations.Migration):
@@ -19,4 +19,33 @@ class Migration(migrations.Migration):
                 ('style', django_enum.fields.EnumPositiveSmallIntegerField(choices=[(1, 'Streets'), (2, 'Outdoors'), (3, 'Light'), (4, 'Dark'), (5, 'Satellite'), (6, 'Satellite Streets'), (7, 'Navigation Day'), (8, 'Navigation Night')], default=1)),
             ],
         ),
+        migrations.CreateModel(
+            name='MyModel',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('txt_enum', django_enum.fields.EnumCharField(blank=True, choices=[('V0', 'Value 0'), ('V1', 'Value 1'), ('V2', 'Value 2')], max_length=2, null=True)),
+                ('int_enum', django_enum.fields.EnumPositiveSmallIntegerField(choices=[(1, 'One'), (2, 'Two'), (3, 'Three')])),
+            ],
+        ),
+        migrations.CreateModel(
+            name='NoCoerceExample',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('non_strict', django_enum.fields.EnumCharField(choices=[('1', 'One'), ('2', 'Two')], max_length=10)),
+            ],
+        ),
+        migrations.CreateModel(
+            name='StrictExample',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('non_strict', django_enum.fields.EnumCharField(choices=[('1', 'One'), ('2', 'Two')], max_length=10)),
+            ],
+        ),
+        migrations.CreateModel(
+            name='TextChoicesExample',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('color', django_enum.fields.EnumCharField(choices=[('R', 'Red'), ('G', 'Green'), ('B', 'Blue')], max_length=1)),
+            ],
+        ),
     ]

django_enum/tests/examples/models.py

@@ -1,5 +1,5 @@
 from django.db import models
-from django_enum import EnumField, IntegerChoices
+from django_enum import EnumField, IntegerChoices, TextChoices
 from enum_properties import p, s
 
 
@@ -34,3 +34,75 @@ def __str__(self):
             return self.uri
 
     style = EnumField(MapBoxStyle, default=MapBoxStyle.STREETS)
+
+
+class StrictExample(models.Model):
+
+    class EnumType(TextChoices):
+
+        ONE = '1', 'One'
+        TWO = '2', 'Two'
+
+    non_strict = EnumField(
+        EnumType,
+        strict=False,
+        # it might be necessary to override max_length also, otherwise
+        # max_length will be 1
+        max_length=10
+    )
+
+
+class NoCoerceExample(models.Model):
+
+    class EnumType(TextChoices):
+
+        ONE = '1', 'One'
+        TWO = '2', 'Two'
+
+    non_strict = EnumField(
+        EnumType,
+        strict=False,
+        coerce=False,
+        # it might be necessary to override max_length also, otherwise
+        # max_length will be 1
+        max_length=10
+    )
+
+
+class TextChoicesExample(models.Model):
+
+    class Color(TextChoices, s('rgb'), s('hex', case_fold=True)):
+
+        # name   value   label       rgb       hex
+        RED     = 'R',   'Red',   (1, 0, 0), 'ff0000'
+        GREEN   = 'G',   'Green', (0, 1, 0), '00ff00'
+        BLUE    = 'B',   'Blue',  (0, 0, 1), '0000ff'
+
+        # any named s() values in the Enum's inheritance become properties on
+        # each value, and the enumeration value may be instantiated from the
+        # property's value
+
+    color = EnumField(Color)
+
+
+class MyModel(models.Model):
+
+    class TextEnum(models.TextChoices):
+
+        VALUE0 = 'V0', 'Value 0'
+        VALUE1 = 'V1', 'Value 1'
+        VALUE2 = 'V2', 'Value 2'
+
+    class IntEnum(models.IntegerChoices):
+
+        ONE   = 1, 'One'
+        TWO   = 2, 'Two',
+        THREE = 3, 'Three'
+
+    # this is equivalent to:
+    #  CharField(max_length=2, choices=TextEnum.choices, null=True, blank=True)
+    txt_enum = EnumField(TextEnum, null=True, blank=True)
+
+    # this is equivalent to
+    #  PositiveSmallIntegerField(choices=IntEnum.choices)
+    int_enum = EnumField(IntEnum)

django_enum/tests/tests.py

@@ -2729,5 +2729,70 @@ def test_mapboxstyle(self):
                 'mapbox://styles/mapbox/satellite-streets-v11'
             )
 
+        def test_color(self):
+            from django_enum.tests.examples.models import TextChoicesExample
+
+            instance = TextChoicesExample.objects.create(
+                color=TextChoicesExample.Color('FF0000')
+            )
+            self.assertTrue(
+                instance.color == TextChoicesExample.Color('Red') ==
+                TextChoicesExample.Color('R') == TextChoicesExample.Color((1, 0, 0))
+            )
+
+            # direct comparison to any symmetric value also works
+            self.assertTrue(instance.color == 'Red')
+            self.assertTrue(instance.color == 'R')
+            self.assertTrue(instance.color == (1, 0, 0))
+
+            # save by any symmetric value
+            instance.color = 'FF0000'
+            instance.full_clean()
+            self.assertTrue(instance.color.hex == 'ff0000')
+            instance.save()
+
+        def test_strict(self):
+            from django_enum.tests.examples.models import StrictExample
+            obj = StrictExample()
+
+            # set to a valid EnumType value
+            obj.non_strict = '1'
+            obj.full_clean()
+            # when accessed from the db or after clean, will be an EnumType instance
+            self.assertTrue(obj.non_strict is StrictExample.EnumType.ONE)
+
+            # we can also store any string less than or equal to length 10
+            obj.non_strict = 'arbitrary'
+            obj.full_clean()  # no errors
+            # when accessed will be a str instance
+            self.assertTrue(obj.non_strict == 'arbitrary')
+
+        def test_basic(self):
+            from django_enum.tests.examples.models import MyModel
+            instance = MyModel.objects.create(
+                txt_enum=MyModel.TextEnum.VALUE1,
+                int_enum=3  # by-value assignment also works
+            )
+            instance.refresh_from_db()
+
+            self.assertTrue(instance.txt_enum == MyModel.TextEnum('V1'))
+            self.assertTrue(instance.txt_enum.label == 'Value 1')
+
+            self.assertTrue(instance.int_enum == MyModel.IntEnum['THREE'])
+            self.assertTrue(instance.int_enum.value == 3)
+
+        def test_no_coerce(self):
+            from django_enum.tests.examples.models import NoCoerceExample
+
+            obj = NoCoerceExample()
+            # set to a valid EnumType value
+            obj.non_strict = '1'
+            obj.full_clean()
+
+            # when accessed from the db or after clean, will be the primitive value
+            self.assertTrue(obj.non_strict == '1')
+            self.assertTrue(isinstance(obj.non_strict, str))
+            self.assertFalse(isinstance(obj.non_strict, NoCoerceExample.EnumType))
+
 else:  # pragma: no cover
     pass

doc/source/usage.rst

@@ -29,7 +29,7 @@ data where no ``Enum`` type coercion is possible.
 
 .. code-block:: python
 
-    class MyModel(models.Model):
+    class StrictExample(models.Model):
 
         class EnumType(TextChoices):
 
@@ -44,13 +44,13 @@ data where no ``Enum`` type coercion is possible.
             max_length=10
         )
 
-    obj = MyModel()
+    obj = StrictExample()
 
     # set to a valid EnumType value
     obj.non_strict = '1'
     obj.full_clean()
     # when accessed from the db or after clean, will be an EnumType instance
-    assert obj.non_strict is MyModel.EnumType.ONE
+    assert obj.non_strict is StrictExample.EnumType.ONE
 
     # we can also store any string less than or equal to length 10
     obj.non_strict = 'arbitrary'
@@ -59,33 +59,32 @@ data where no ``Enum`` type coercion is possible.
     assert obj.non_strict == 'arbitrary'
 
 
-..
-    ``coerce``
-    ----------
-
-    Setting this parameter to ``False`` will turn off the automatic conversion to
-    the field's ``Enum`` type while leaving all validation checks in place. It will
-    still be possible to set the field directly as an ``Enum`` instance:
+``coerce``
+----------
 
-    .. code-block:: python
+Setting this parameter to ``False`` will turn off the automatic conversion to
+the field's ``Enum`` type while leaving all validation checks in place. It will
+still be possible to set the field directly as an ``Enum`` instance:
 
-        non_strict = EnumField(
-            EnumType,
-            strict=False,
-            coerce=False,
-            # it might be necessary to override max_length also, otherwise
-            # max_length will be 1
-            max_length=10
-        )
+.. code-block:: python
 
-        # set to a valid EnumType value
-        obj.non_strict = '1'
-        obj.full_clean()
+    non_strict = EnumField(
+        EnumType,
+        strict=False,
+        coerce=False,
+        # it might be necessary to override max_length also, otherwise
+        # max_length will be 1
+        max_length=10
+    )
 
-        # when accessed from the db or after clean, will be the primitive value
-        assert obj.non_strict == '1'
-        assert isinstance(obj.non_strict, str)
+    # set to a valid EnumType value
+    obj.non_strict = '1'
+    obj.full_clean()
 
+    # when accessed from the db or after clean, will be the primitive value
+    assert obj.non_strict == '1'
+    assert isinstance(obj.non_strict, str)
+    assert not isinstance(obj.non_strict, StrictExample.EnumType)
 
 enum-properties
 ###############
@@ -108,7 +107,7 @@ values that can be symmetrically mapped back to enumeration values:
     from django_enum import TextChoices  # use instead of Django's TextChoices
     from django.db import models
 
-    class MyModel(models.Model):
+    class TextChoicesExample(models.Model):
 
         class Color(TextChoices, s('rgb'), s('hex', case_fold=True)):
 
@@ -123,8 +122,12 @@ values that can be symmetrically mapped back to enumeration values:
 
         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))
+    instance = TextChoicesExample.objects.create(
+        color=TextChoicesExample.Color('FF0000')
+    )
+    assert instance.color == TextChoicesExample.Color('Red')
+    assert instance.color == TextChoicesExample.Color('R')
+    assert instance.color == TextChoicesExample.Color((1, 0, 0))
 
     # direct comparison to any symmetric value also works
     assert instance.color == 'Red'