add Eccentric Enums docs and a test for custom enum types

Author: bckohan

django_enum/tests/djenum/enums.py

@@ -1,6 +1,7 @@
 from datetime import date, datetime, time, timedelta
 from decimal import Decimal
 from enum import Enum, IntEnum, IntFlag
+from pathlib import Path
 
 from django.db.models import IntegerChoices, TextChoices
 from django.db.models.enums import Choices
@@ -326,3 +327,49 @@ class MultiWithNone(Enum):
     VAL2 = '2.0'
     VAL3 = 3.0
     VAL4 = Decimal('4.5')
+
+
+class PathEnum(Enum):
+
+    USR = Path('/usr')
+    USR_LOCAL = Path('/usr/local')
+    USR_LOCAL_BIN = Path('/usr/local/bin')
+
+
+class StrProps:
+    """
+    Wrap a string with some properties.
+    """
+
+    _str = ''
+
+    def __init__(self, string):
+        self._str = string
+
+    def __str__(self):
+        return self._str
+
+    @property
+    def upper(self):
+        return self._str.upper()
+
+    @property
+    def lower(self):
+        return self._str.lower()
+
+    def __eq__(self, other):
+        if isinstance(other, str):
+            return self._str == other
+        if other is not None:
+            return self._str == other._str
+        return False
+
+    def deconstruct(self):
+        return 'django_enum.tests.djenum.enums.StrProps', (self._str,), {}
+
+
+class StrPropsEnum(Enum):
+
+    STR1 = StrProps('str1')
+    STR2 = StrProps('str2')
+    STR3 = StrProps('str3')

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

@@ -1,9 +1,11 @@
-# Generated by Django 4.2.4 on 2023-08-08 01:51
+# Generated by Django 3.2.20 on 2023-08-08 16:45
 
 import datetime
+import pathlib
 from decimal import Decimal
 
 import django_enum.fields
+import django_enum.tests.djenum.enums
 from django.db import migrations, models
 
 
@@ -30,6 +32,14 @@ class Migration(migrations.Migration):
                 ('non_strict_int', django_enum.fields.EnumPositiveSmallIntegerField(blank=True, choices=[(0, 'Value 1'), (2, 'Value 2'), (32767, 'Value 32767')], default=5, null=True)),
             ],
         ),
+        migrations.CreateModel(
+            name='CustomPrimitiveTestModel',
+            fields=[
+                ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('path', django_enum.fields.EnumCharField(choices=[(pathlib.PurePosixPath('/usr'), 'USR'), (pathlib.PurePosixPath('/usr/local'), 'USR_LOCAL'), (pathlib.PurePosixPath('/usr/local/bin'), 'USR_LOCAL_BIN')], max_length=14)),
+                ('str_props', django_enum.fields.EnumCharField(choices=[(django_enum.tests.djenum.enums.StrProps('str1'), 'STR1'), (django_enum.tests.djenum.enums.StrProps('str2'), 'STR2'), (django_enum.tests.djenum.enums.StrProps('str3'), 'STR3')], max_length=4)),
+            ],
+        ),
         migrations.CreateModel(
             name='EmptyEnumValueTester',
             fields=[
@@ -196,7 +206,7 @@ class Migration(migrations.Migration):
         migrations.AddField(
             model_name='enumflagtesterrelated',
             name='related_flags',
-            field=models.ManyToManyField(related_name='related_flags', to='django_enum_tests_djenum.enumflagtester'),
+            field=models.ManyToManyField(related_name='related_flags', to='django_enum_tests_djenum.EnumFlagTester'),
         ),
         migrations.AddConstraint(
             model_name='emptyenumvaluetester',
@@ -210,6 +220,14 @@ class Migration(migrations.Migration):
             model_name='emptyenumvaluetester',
             constraint=models.CheckConstraint(check=models.Q(('none_int_enum_non_null__in', [None, 2]), ('none_int_enum_non_null__isnull', True), _connector='OR'), name='s_djenum_EmptyEnumValueTester_none_int_enum_non_null_NoneIntEnum'),
         ),
+        migrations.AddConstraint(
+            model_name='customprimitivetestmodel',
+            constraint=models.CheckConstraint(check=models.Q(('path__in', ['/usr', '/usr/local', '/usr/local/bin'])), name='django_enum_tests_djenum_CustomPrimitiveTestModel_path_PathEnum'),
+        ),
+        migrations.AddConstraint(
+            model_name='customprimitivetestmodel',
+            constraint=models.CheckConstraint(check=models.Q(('str_props__in', ['str1', 'str2', 'str3'])), name='num_tests_djenum_CustomPrimitiveTestModel_str_props_StrPropsEnum'),
+        ),
         migrations.AddConstraint(
             model_name='baddefault',
             constraint=models.CheckConstraint(check=models.Q(('non_strict_int__in', [0, 2, 32767]), ('non_strict_int__isnull', True), _connector='OR'), name='ango_enum_tests_djenum_BadDefault_non_strict_int_SmallPosIntEnum'),

django_enum/tests/djenum/models.py

@@ -24,12 +24,15 @@
     MultiPrimitiveEnum,
     MultiWithNone,
     NegativeFlagEnum,
+    PathEnum,
     PosIntEnum,
     PositiveFlagEnum,
     SmallIntEnum,
     SmallNegativeFlagEnum,
     SmallPosIntEnum,
     SmallPositiveFlagEnum,
+    StrProps,
+    StrPropsEnum,
     TextEnum,
     TimeEnum,
 )
@@ -394,3 +397,10 @@ class MultiPrimitiveTestModel(models.Model):
         constrained=False,
         strict=False
     )
+
+
+class CustomPrimitiveTestModel(models.Model):
+
+    path = EnumField(PathEnum, primitive=str)
+
+    str_props = EnumField(StrPropsEnum, primitive=str)

django_enum/tests/tests.py

@@ -406,6 +406,63 @@ def test_enum_choice_field(self):
         self.assertEqual(form_field3.choices, choices(MultiWithNone))
         self.assertEqual(form_field3.primitive, str)
 
+    def test_custom_primitive(self):
+        from django_enum.tests.djenum.enums import (
+            PathEnum,
+            StrProps,
+            StrPropsEnum,
+        )
+        from django_enum.tests.djenum.models import CustomPrimitiveTestModel
+
+        obj = CustomPrimitiveTestModel.objects.create(
+            path='/usr/local',
+            str_props='str1'
+        )
+        self.assertEqual(obj.path, PathEnum.USR_LOCAL)
+        self.assertEqual(obj.str_props, StrPropsEnum.STR1)
+
+        obj2 = CustomPrimitiveTestModel.objects.create(
+            path=PathEnum.USR,
+            str_props=StrPropsEnum.STR2
+        )
+        self.assertEqual(obj2.path, PathEnum.USR)
+        self.assertEqual(obj2.str_props, StrPropsEnum.STR2)
+
+        obj3 = CustomPrimitiveTestModel.objects.create(
+            path=Path('/usr/local/bin'),
+            str_props=StrProps('str3')
+        )
+        self.assertEqual(obj3.path, PathEnum.USR_LOCAL_BIN)
+        self.assertEqual(obj3.str_props, StrPropsEnum.STR3)
+
+        self.assertEqual(
+            obj,
+            CustomPrimitiveTestModel.objects.get(path='/usr/local')
+        )
+        self.assertEqual(
+            obj,
+            CustomPrimitiveTestModel.objects.get(str_props='str1')
+        )
+
+        self.assertEqual(
+            obj2,
+            CustomPrimitiveTestModel.objects.get(path=PathEnum.USR)
+        )
+        self.assertEqual(
+            obj2,
+            CustomPrimitiveTestModel.objects.get(str_props=StrPropsEnum.STR2)
+        )
+
+        self.assertEqual(
+            obj3,
+            CustomPrimitiveTestModel.objects.get(path=Path('/usr/local/bin')),
+        )
+
+        self.assertEqual(
+            obj3,
+            CustomPrimitiveTestModel.objects.get(str_props=StrProps('str3')),
+        )
+
 
 class TestEnumCompat(TestCase):
     """ Test that django_enum allows non-choice derived enums to be used """

doc/source/eccentric_enums.py

@@ -0,0 +1,159 @@
+.. include:: refs.rst
+
+.. _eccentric_enums:
+
+======================
+Eccentric Enumerations
+======================
+
+Python's Enum_ type is extremely lenient. Enumeration values may be any
+hashable type and values of the same enumeration may be of different types.
+
+For use in databases it is recommended to use more strict enumeration types
+that only allow a single value type of either string or integer. If additional
+properties need to be associated with enumeration values, a library like
+enum-properties_ should be used to store them on the enumeration value classes.
+
+However, the goal of django-enum is to provide as complete a bridge as possible
+between Python and the database so eccentric enumerations are supported with
+caveats. The following enumeration value types are supported out of the box,
+and map to the obvious Django model field type:
+
+* :class:`int`
+* :class:`str`
+* :class:`float`
+* :class:`datetime.date`
+* :class:`datetime.datetime`
+* :class:`datetime.time`
+* :class:`datetime.timedelta`
+* :class:`decimal.Decimal`
+
+While it is mostly not advisable to use eccentric enumerations, there may be
+some compelling reasons to do so. For example, it may make sense in
+situations where the database will be used in a non-Django context and the
+enumeration values need to retain their native meaning.
+
+
+Mixed Value Enumerations
+========================
+
+Mixed value enumerations are supported. For example:
+
+.. code-block:: python
+
+    from enum import Enum
+
+    class EccentricEnum(Enum):
+
+        NONE = None
+        VAL1 = 1
+        VAL2 = '2.0'
+        VAL3 = 3.0
+        VAL4 = Decimal('4.5')
+
+
+``EnumField`` will determine the most appropriate database column type to store
+the enumeration by trying each of the supported primitive types in order and
+selecting the first one that is symmetrically coercible to and from each
+enumeration value. None values are allowed and do not take part in the
+primitive type selection. In the above example, the database column type would
+be a string.
+
+.. note::
+
+    If none of the supported primitive types are symmetrically coercible
+    ``EnumField`` will not be able to determine an appropriate column type and
+    a ``ValueError`` will be raised.
+
+In these cases, or to override the primitive type selection made by
+``EnumField``, pass the ``primitive`` parameter. It may be necessary to extend
+one of the supported primitives to make it coercible. It may also be necessary
+to override the Enum_'s ``_missing_`` method:
+
+.. code-block:: python
+
+    # eccentric will be a string
+    eccentric_str = EnumField(EccentricEnum)
+
+    # primitive will be a float
+    eccentric_float = EnumField(EccentricEnum, primitive=float)
+
+In the above case since None is an enumeration value, ``EnumField`` will
+automatically set null=True on the model field.
+
+Custom Enumeration Values
+=========================
+
+.. warning::
+    There is almost certainly a better way to do what you might be trying to do
+    by writing a custom enumeration value - for example consider using
+    enum-properties_ to make your enumeration types more robust by pushing more
+    of this functionality on the Enum_ class itself.
+
+If you must use a custom value type, you can by specifying a symmetrically
+coercible primitive type. For example Path is already symmetrically coercible
+to str so this works:
+
+.. code-block:: python
+
+    class MyModel(models.Model):
+
+        class PathEnum(Enum):
+
+            USR = Path('/usr')
+            USR_LOCAL = Path('/usr/local')
+            USR_LOCAL_BIN = Path('/usr/local/bin')
+
+        path = EnumField(PathEnum, primitive=str)
+
+
+A fully custom value might look like the following (admittedly contrived)
+example:
+
+.. code-block:: python
+
+    class StrProps:
+        """
+        Wrap a string with some properties.
+        """
+
+        _str = ''
+
+        def __init__(self, string):
+            self._str = string
+
+        def __str__(self):
+            """ coercion to str - str(StrProps('str1')) == 'str1' """
+            return self._str
+
+        @property
+        def upper(self):
+            return self._str.upper()
+
+        @property
+        def lower(self):
+            return self._str.lower()
+
+        def __eq__(self, other):
+            """ Make sure StrProps('str1') == 'str1' """
+            if isinstance(other, str):
+                return self._str == other
+            if other is not None:
+                return self._str == other._str
+            return False
+
+        def deconstruct(self):
+            """Necessary to construct choices and default in migration files"""
+            return 'my_module.StrProps', (self._str,), {}
+
+
+    class MyModel(models.Model):
+
+        class StrPropsEnum(Enum):
+
+            STR1 = StrProps('str1')
+            STR2 = StrProps('str2')
+            STR3 = StrProps('str3')
+
+        str_props = EnumField(StrPropsEnum, primitive=str)
+

doc/source/eccentric_enums.rst

@@ -182,5 +182,6 @@ exception will be thrown.
    usage
    examples
    performance
+   eccentric_enums
    reference
    changelog

doc/source/index.rst

@@ -79,7 +79,7 @@ does a full table scan:
 
    Query performance comparison without indexing. In this scenario, with a 16
    flag bitmask compared to 16 boolean columns, each of the three query types
-   perform roughly 20% faster on PostgreSQL.
+   perform roughly 20-40% faster on PostgreSQL.
 
 
 Indexed Exact Queries