add docs on hash equivalency to fix #123

Author: bckohan

doc/source/howto/admin.rst

@@ -0,0 +1,13 @@
+.. include:: ../refs.rst
+
+.. _admin:
+
+================
+Use Django Admin
+================
+
+:class:`~django_enum.fields.EnumField` will mostly just work in the Django
+:mod:`~django.contrib.admin`. There is
+`one issue <https://github.com/django-commons/django-enum/issues/123>`_ where :ref:`enums that are
+not hash equivalent <hash_equivalency>` will not render value labels correctly in the
+:class:`~django.contrib.admin.ModelAdmin` :attr:`~django.contrib.admin.ModelAdmin.list_display`.

doc/source/howto/external.rst

@@ -29,3 +29,34 @@ The list of choice tuples for each field are:
     values assigned depend on the order of declaration. This means that if the order changes
     existing database values will no longer align with the enumeration values. When control over the
     values is not certain it is a good idea to add integration tests that look for value changes.
+
+.. _hash_equivalency:
+
+Hash Equivalency
+----------------
+
+.. tip::
+
+    It is a good idea to make sure your enumeration instances are hash equivalent to their
+    primitive values. You can do this simply by inheriting from their primitive value
+    (e.g. ``class MyEnum(str, Enum):``) or by using :class:`~enum.StrEnum` and
+    :class:`~enum.IntEnum` types. Any enumeration defined using :doc:`enum-properties:index`
+    will be hash equivalent to its values by default.
+
+:class:`~django_enum.fields.EnumField` automatically sets the choices tuple on the field. Django_
+has logic in a number of places that handles fields with choices in a special way
+(e.g. :ref:`in the admin <admin>`). For example, the choices may be converted to a dictionary
+mapping values to labels. The values will be the primitive values of the enumeration not
+enumeration instances and the current value of the field which may be an enumeration instance will
+be searched for in the dictionary. This will fail if the enumeration instance is not hash
+equivalent to its value.
+
+To control the hashing behavior of an object, you must override its :meth:`~object.__hash__` and
+:meth:`~object.__eq__` methods.
+
+For example:
+
+.. literalinclude:: ../../../tests/examples/models/hash_equivalency.py
+
+.. literalinclude:: ../../../tests/examples/hash_equivalency_howto.py
+    :lines: 3-

doc/source/howto/index.rst

@@ -45,3 +45,4 @@ are possible with :class:`~django_enum.fields.EnumField`. See :ref:`enum_props`.
    integrations
    migrations
    urls
+   admin

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "django-enum"
-version = "2.2.2"
+version = "2.2.3"
 description = "Full and natural support for enumerations as Django model fields."
 requires-python = ">=3.9,<4.0"
 authors = [

src/django_enum/__init__.py

@@ -16,7 +16,7 @@
 
 __all__ = ["EnumField"]
 
-VERSION = (2, 2, 2)
+VERSION = (2, 2, 3)
 
 __title__ = "Django Enum"
 __version__ = ".".join(str(i) for i in VERSION)

tests/examples/hash_equivalency_howto.py

@@ -0,0 +1,37 @@
+from .models.hash_equivalency import HashEquivalencyExample
+
+
+obj = HashEquivalencyExample.objects.create(
+    not_hash_eq=HashEquivalencyExample.NotHashEq.VALUE1,
+    hash_eq=HashEquivalencyExample.HashEq.VALUE1,
+    hash_eq_str=HashEquivalencyExample.HashEqStr.VALUE1
+)
+
+# direct comparisons to values do not work
+assert obj.not_hash_eq != "V1"
+
+# unless you have provided __eq__ or inherited from the primitive
+assert obj.hash_eq == obj.hash_eq_str == "V1"
+
+# here is the problem that can break some Django internals in rare instances:
+assert dict(HashEquivalencyExample._meta.get_field("not_hash_eq").flatchoices) == {
+    "V1": "VALUE1",
+    "V2": "VALUE2",
+    "V3": "VALUE3"
+}
+
+try:
+    dict(HashEquivalencyExample._meta.get_field("not_hash_eq").flatchoices)[
+        HashEquivalencyExample.NotHashEq.VALUE1
+    ]
+    assert False
+except KeyError:
+    assert True
+
+# if we've made our enum hash equivalent though, this works:
+assert dict(HashEquivalencyExample._meta.get_field("hash_eq").flatchoices)[
+    HashEquivalencyExample.HashEq.VALUE1
+] == "VALUE1"
+assert dict(HashEquivalencyExample._meta.get_field("hash_eq_str").flatchoices)[
+    HashEquivalencyExample.HashEqStr.VALUE1
+] == "VALUE1"

tests/examples/models/__init__.py

@@ -11,6 +11,7 @@
 from .gnss import GNSSReceiver, Constellation
 from .gnss_vanilla import GNSSReceiverBasic
 from .equivalency import EquivalencyExample
+from .hash_equivalency import HashEquivalencyExample
 from .extern import ExternalChoices
 from .flag_howto import Group
 from .text_choices import TextChoicesExample
@@ -37,6 +38,7 @@
     "Constellation",
     "GNSSReceiverBasic",
     "EquivalencyExample",
+    "HashEquivalencyExample",
     "ExternalChoices",
     "Group",
     "TextChoicesExample",

tests/examples/models/hash_equivalency.py

@@ -0,0 +1,55 @@
+from enum import Enum
+from django.db.models import Model
+from django_enum import EnumField
+
+
+class HashEquivalencyExample(Model):
+    """
+    This example model defines three enum fields. The first uses an enum that
+    is not hash equivalent to its values. The second two are.
+    """
+
+    class NotHashEq(Enum):
+        """
+        Enums that inherit only from :class:`~enum.Enum` are not hash equivalent
+        to their values by default.
+        """
+
+        VALUE1 = "V1"
+        VALUE2 = "V2"
+        VALUE3 = "V3"
+
+    class HashEq(Enum):
+        """
+        We can force our Enum to be hash equivalent by overriding the necessary
+        dunder methods..
+        """
+
+        VALUE1 = "V1"
+        VALUE2 = "V2"
+        VALUE3 = "V3"
+
+        def __hash__(self):
+            return hash(self.value)
+
+        def __eq__(self, value) -> bool:
+            if isinstance(value, self.__class__):
+                return self.value == value.value
+            try:
+                return self.value == self.__class__(value).value
+            except (ValueError, TypeError):
+                return False
+
+    class HashEqStr(str, Enum):  # or StrEnum on py 3.11+
+        """
+        Or we can inherit from the primitive value type.
+        """
+
+        VALUE1 = "V1"
+        VALUE2 = "V2"
+        VALUE3 = "V3"
+
+
+    not_hash_eq = EnumField(NotHashEq)
+    hash_eq = EnumField(HashEq)
+    hash_eq_str = EnumField(HashEqStr)

tests/test_examples.py

@@ -304,6 +304,9 @@ def test_gnss_tutorial_vanilla(self):
     def test_equivalency_howto(self):
         from tests.examples import equivalency_howto
 
+    def test_hash_equivalency_howto(self):
+        from tests.examples import hash_equivalency_howto
+
     def test_extern_howto(self):
         from tests.examples import extern_howto