fix type hint on EnumField, add lots of documentation and example tests

Author: bckohan

README.rst

@@ -82,11 +82,11 @@ accessible as their enumeration type rather than by-value:*
     )
     instance.refresh_from_db()
 
-    instance.txt_enum == MyModel.TextEnum('V1')
-    instance.txt_enum.label == 'Value 1'
+    assert instance.txt_enum == MyModel.TextEnum('V1')
+    assert instance.txt_enum.label == 'Value 1'
 
-    instance.int_enum == MyModel.IntEnum['THREE']
-    instance.int_enum.value == 3
+    assert instance.int_enum == MyModel.IntEnum['THREE']
+    assert instance.int_enum.value == 3
 
 
 `django-enum <https://django-enum.readthedocs.io/en/latest/>`_ also provides
@@ -116,12 +116,17 @@ possible very rich enumeration fields.
         color = EnumField(Color)
 
     instance = MyModel.objects.create(color=MyModel.Color('FF0000'))
-    instance.color == MyModel.Color('Red') == MyModel.Color('R') == MyModel.Color((1, 0, 0))
+    assert instance.color == MyModel.Color('Red') == MyModel.Color('R') == MyModel.Color((1, 0, 0))
 
-    # save back by any symmetric value
+    # direct comparison to any symmetric value also works
+    assert instance.color == 'Red'
+    assert instance.color == 'R'
+    assert instance.color == (1, 0, 0)
+
+    # save by any symmetric value
     instance.color = 'FF0000'
     instance.full_clean()
-    instance.color.hex == 'ff0000'
+    assert instance.color.hex == 'ff0000'
     instance.save()
 
 

django_enum/fields.py

@@ -311,7 +311,7 @@ def __new__(mcs, enum: Choices) -> Field:  # pylint: disable=R0911
 
 
 def EnumField(  # pylint: disable=C0103
-        enum: Choices,
+        enum: Type[Choices],
         *field_args,
         **field_kwargs
 ) -> Field:

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

@@ -1,4 +1,4 @@
-# Generated by Django 3.2.14 on 2022-07-26 03:42
+# Generated by Django 3.2.14 on 2022-08-09 00:32
 
 import django_enum.fields
 from django.db import migrations, models
@@ -32,6 +32,7 @@ class Migration(migrations.Migration):
                 ('dj_int_enum', django_enum.fields.EnumPositiveSmallIntegerField(choices=[(1, 'One'), (2, 'Two'), (3, 'Three')], default=1)),
                 ('dj_text_enum', django_enum.fields.EnumCharField(choices=[('A', 'Label A'), ('B', 'Label B'), ('C', 'Label C')], default='A', max_length=1)),
                 ('non_strict_int', django_enum.fields.EnumPositiveSmallIntegerField(blank=True, choices=[(0, 'Value 1'), (2, 'Value 2'), (32767, 'Value 32767')], default=None, null=True)),
+                ('non_strict_text', django_enum.fields.EnumCharField(blank=True, choices=[('V1', 'Value1'), ('V22', 'Value2'), ('V333', 'Value3'), ('D', 'Default')], default='', max_length=12)),
             ],
             options={
                 'ordering': ('id',),

django_enum/tests/djenum/models.py

@@ -78,6 +78,15 @@ class EnumTester(models.Model):
         blank=True
     )
 
+    non_strict_text = EnumField(
+        TextEnum,
+        max_length=12,
+        strict=False,
+        null=False,
+        default='',
+        blank=True
+    )
+
     def get_absolute_url(self):
         return reverse('django_enum_tests_djenum:enum-detail', kwargs={'pk': self.pk})
 

django_enum/tests/examples/__init__.py

@@ -0,0 +1,6 @@
+from django.apps import AppConfig
+
+
+class ExamplesConfig(AppConfig):
+    name = 'django_enum.tests.examples'
+    label = name.replace('.', '_')

django_enum/tests/examples/apps.py

@@ -0,0 +1,22 @@
+# Generated by Django 3.2.14 on 2022-08-09 02:32
+
+import django_enum.fields
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Map',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('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)),
+            ],
+        ),
+    ]

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

@@ -0,0 +1,36 @@
+from django.db import models
+from django_enum import EnumField, IntegerChoices
+from enum_properties import p, s
+
+
+class Map(models.Model):
+
+    class MapBoxStyle(
+        IntegerChoices,
+        s('slug', case_fold=True),
+        s('label', case_fold=True),
+        p('version')
+    ):
+        """
+        https://docs.mapbox.com/api/maps/styles/
+        """
+        _symmetric_builtins_ = ['name', 'uri']
+
+        # name             value    slug                 label         version
+        STREETS           =  1,   'streets',           'Streets',           11
+        OUTDOORS          =  2,   'outdoors',          'Outdoors',          11
+        LIGHT             =  3,   'light',             'Light',             10
+        DARK              =  4,   'dark',              'Dark',              10
+        SATELLITE         =  5,   'satellite',         'Satellite',          9
+        SATELLITE_STREETS =  6,   'satellite-streets', 'Satellite Streets', 11
+        NAVIGATION_DAY    =  7,   'navigation-day',    'Navigation Day',     1
+        NAVIGATION_NIGHT  =  8,   'navigation-night',  'Navigation Night',   1
+
+        @property
+        def uri(self):
+            return f'mapbox://styles/mapbox/{self.slug}-v{self.version}'
+
+        def __str__(self):
+            return self.uri
+
+    style = EnumField(MapBoxStyle, default=MapBoxStyle.STREETS)

django_enum/tests/examples/migrations/__init__.py

@@ -57,6 +57,7 @@
     import enum_properties
     INSTALLED_APPS.insert(0, 'django_enum.tests.enum_prop')
     INSTALLED_APPS.insert(0, 'django_enum.tests.edit_tests')
+    INSTALLED_APPS.insert(0, 'django_enum.tests.examples')
 except (ImportError, ModuleNotFoundError):  # pragma: no cover
     pass