fix #72, fix #95, fix #96, fix #98, fix #99

Author: bckohan

.github/workflows/test.yml

@@ -35,6 +35,7 @@ jobs:
           - '3.2' # LTS April 2024
           - '4.2' # LTS April 2026
           - '5.1' # December 2025
+          - '5.2b1'
         exclude:
           - django-version: '4.2'
             postgres-version: '9.6'
@@ -55,8 +56,16 @@ jobs:
           - postgres-version: '9.6'
             django-version: '5.1'
 
+          - postgres-version: '9.6'
+            django-version: '5.2b1'
+            
+          - postgres-version: '12'
+            django-version: '5.2b1'
+
           - python-version: '3.9'
             django-version: '5.1'
+          - python-version: '3.9'
+            django-version: '5.2b1'
           - python-version: '3.13'
             django-version: '3.2'
           - python-version: '3.13'

README.md

@@ -24,23 +24,23 @@
 
 🚨 **See [migration guide](https://django-enum.readthedocs.io/en/latest/changelog.html#migration-1-x-to-2-x) for notes on 1.x to 2.x migration.** 🚨
 
-Full and natural support for [enumerations](https://docs.python.org/3/library/enum.html#enum.Enum) as Django model fields.
+Full and natural support for [PEP435](https://peps.python.org/pep-0435) [enumerations](https://docs.python.org/3/library/enum.html#enum.Enum) as [Django](https://www.djangoproject.com) model fields.
 
-Many packages aim to ease usage of Python enumerations as model fields. Most were superseded when Django provided ``TextChoices`` and ``IntegerChoices`` types. The motivation for [django-enum](https://django-enum.readthedocs.io) was to:
+Many packages aim to ease usage of Python enumerations as model fields. Most were superseded when Django provided [TextChoices](https://docs.djangoproject.com/en/stable/ref/models/fields/#field-choices-enum-types) and [IntegerChoices](https://docs.djangoproject.com/en/stable/ref/models/fields/#field-choices-enum-types) types. The motivation for [django-enum](https://pypi.org/project/enum-properties) was to:
 
-* Work with any Python PEP 435 Enum including those that do not derive from Django's TextChoices and IntegerChoices.
-* Coerce fields to instances of the Enum type by default.
-* Allow strict adherence to Enum values to be disabled.
+* Work with any [Enum](https://docs.python.org/3/library/enum.html#enum.Enum) including those that do not derive from Django's [TextChoices](https://docs.djangoproject.com/en/stable/ref/models/fields/#field-choices-enum-types) and [IntegerChoices](https://docs.djangoproject.com/en/stable/ref/models/fields/#field-choices-enum-types).
+* Coerce fields to instances of the [Enum](https://docs.python.org/3/library/enum.html#enum.Enum) type by default.
+* Allow strict adherence to [Enum](https://docs.python.org/3/library/enum.html#enum.Enum) values to be disabled.
 * Handle migrations appropriately. (See [migrations](https://django-enum.readthedocs.io/en/latest/usage.html#migrations))
-* Integrate as fully as possible with [Django's](https://www.djangoproject.com) existing level of enum support.
-* Support [enum-properties](https://pypi.org/project/enum-properties) to enable richer enumeration types. (A less awkward alternative to dataclass enumerations with more features)
+* Integrate as fully as possible with Django's [existing level of enum support](https://docs.djangoproject.com/en/stable/ref/models/fields/#field-choices-enum-types).
+* Support [enum-properties](https://pypi.org/project/enum-properties) to enable richer enumeration types. (A less awkward alternative to [dataclass enumerations](https://docs.python.org/3/howto/enum.html#enum-dataclass-support) with more features)
 * Represent enum fields with the smallest possible column type.
-* Support bit mask queries using standard Python Flag enumerations.
+* Support [bit field](https://en.wikipedia.org/wiki/Bit_field) queries using standard Python Flag enumerations.
 * Be as simple and light-weight an extension to core [Django](https://www.djangoproject.com) as possible.
-* Enforce enumeration value consistency at the database level using check constraints by default.
+* Enforce enumeration value consistency at the database level using [check constraints](https://docs.djangoproject.com/en/stable/ref/models/constraints) by default.
 * (TODO) Support native database enumeration column types when available.
 
-[django-enum](https://django-enum.readthedocs.io) works in concert with [Django's](https://www.djangoproject.com) built in ``TextChoices`` and ``IntegerChoices`` to provide a new model field type, ``EnumField``, that resolves the correct native [Django](https://www.djangoproject.com) field type for the given enumeration based on its value type and range. For example, ``IntegerChoices`` that contain values between 0 and 32767 become [PositiveSmallIntegerField](https://docs.djangoproject.com/en/stable/ref/models/fields/#positivesmallintegerfield).
+[django-enum](https://pypi.org/project/enum-properties) provides a new model field type, [EnumField](https://django-enum.rtfd.io/en/stable/reference/fields.html#django_enum.fields.EnumField), that allows you to treat almost any [PEP435](https://peps.python.org/pep-0435) enumeration as a database column. [EnumField](https://django-enum.rtfd.io/en/stable/reference/fields.html#django_enum.fields.EnumField) resolves the correct native [Django](https://www.djangoproject.com) field type for the given enumeration based on its value type and range. For example, [IntegerChoices](https://docs.djangoproject.com/en/stable/ref/models/fields/#field-choices-enum-types) that contain values between 0 and 32767 become [PositiveSmallIntegerField](https://docs.djangoproject.com/en/stable/ref/models/fields/#positivesmallintegerfield).
 
 ```python
 
@@ -70,7 +70,7 @@ Many packages aim to ease usage of Python enumerations as model fields. Most wer
         int_enum = EnumField(IntEnum, default=IntEnum.ONE)
 ```
 
-``EnumField`` **is more than just an alias. The fields are now assignable and accessible as their enumeration type rather than by-value:**
+[EnumField](https://django-enum.rtfd.io/en/stable/reference/fields.html#django_enum.fields.EnumField) **is more than just an alias. The fields are now assignable and accessible as their enumeration type rather than by-value:**
 
 ```python
 
@@ -86,9 +86,9 @@ Many packages aim to ease usage of Python enumerations as model fields. Most wer
     assert instance.int_enum.value == 3
 ```
 
-## Flag Support
+## Flag Support (BitFields)
 
-[Flag](https://docs.python.org/3/library/enum.html#enum.Flag) types are also seamlessly supported! This allows a database column to behave like a bit mask and is an alternative to multiple boolean columns. There are mostly positive performance implications for using a bit mask instead of booleans depending on the size of the bit mask and the types of queries you will run against it. For bit masks more than a few bits long the size reduction both speeds up queries and reduces the required storage space. See the documentation for [discussion and benchmarks](https://django-enum.readthedocs.io/en/latest/performance.html#flags).
+[Flag](https://docs.python.org/3/library/enum.html#enum.Flag) types are also seamlessly supported! This allows a database column to behave like a bit field and is an alternative to having multiple boolean columns. There are positive performance implications for using a bit field instead of booleans proportional on the size of the bit field and the types of queries you will run against it. For bit fields more than a few bits long the size reduction both speeds up queries and reduces the required storage space. See the documentation for [discussion and benchmarks](https://django-enum.readthedocs.io/en/latest/performance.html#flags).
 
 ```python
 
@@ -112,7 +112,7 @@ Many packages aim to ease usage of Python enumerations as model fields. Most wer
 
 ## Complex Enumerations
 
-[django-enum](https://django-enum.readthedocs.io) supports enum types that do not derive from Django's ``IntegerChoices`` and ``TextChoices``. This allows us to use other libs like [enum-properties](https://pypi.org/project/enum-properties) which makes possible very rich enumeration fields:
+[django-enum](https://pypi.org/project/django-enum) supports enum types that do not derive from Django's [IntegerChoices](https://docs.djangoproject.com/en/stable/ref/models/fields/#field-choices-enum-types) and [TextChoices](https://docs.djangoproject.com/en/stable/ref/models/fields/#field-choices-enum-types). This allows us to use other libs like [enum-properties](https://pypi.org/project/enum-properties) which makes possible very rich enumeration fields:
 
 ``?> pip install enum-properties``
 
@@ -176,7 +176,7 @@ Many packages aim to ease usage of Python enumerations as model fields. Most wer
     assert TextChoicesExample.objects.filter(color='FF0000').first() == instance
 ```
 
-While they should be unnecessary if you need to integrate with code that expects an interface fully compatible with Django's ``TextChoices`` and ``IntegerChoices`` django-enum provides ``TextChoices``, ``IntegerChoices``, ``FlagChoices`` and ``FloatChoices`` types that derive from enum-properties and Django's ``Choices``. So the above enumeration could also be written:
+While they should be unnecessary if you need to integrate with code that expects an interface fully compatible with Django's [TextChoices](https://docs.djangoproject.com/en/stable/ref/models/fields/#field-choices-enum-types) and [IntegerChoices](https://docs.djangoproject.com/en/stable/ref/models/fields/#field-choices-enum-types) [django-enum](https://pypi.org/project/django-enum) provides [TextChoices](https://django-enum.rtfd.io/en/stable/reference/choices.html#django_enum.choices.TextChoices), [IntegerChoices](https://django-enum.rtfd.io/en/stable/reference/choices.html#django_enum.choices.IntegerChoices), [FlagChoices](https://django-enum.rtfd.io/en/stable/reference/choices.html#django_enum.choices.FlagChoices) and [FloatChoices](https://django-enum.rtfd.io/en/stable/reference/choices.html#django_enum.choices.FloatChoices) types that derive from enum-properties and Django's ``Choices``. So the above enumeration could also be written:
 
 ```python
 
@@ -204,23 +204,30 @@ While they should be unnecessary if you need to integrate with code that expects
    pip install django-enum
 ```
 
-``django-enum`` has several optional dependencies that are not pulled in by default. ``EnumFields`` work seamlessly with all Django apps that work with model fields with choices without any additional work. Optional integrations are provided with several popular libraries to extend this basic functionality.
+[django-enum](https://pypi.org/project/django-enum) has several optional dependencies that are not installed by default. [EnumField](https://django-enum.rtfd.io/en/stable/reference/fields.html#django_enum.fields.EnumField) works seamlessly with all Django apps that work with model fields with choices without any additional work. Optional integrations are provided with several popular libraries to extend this basic functionality, these include:
 
-Integrations are provided that leverage [enum-properties](https://pypi.org/project/enum-properties) to make enumerations do more work and to provide extended functionality for [django-filter](https://pypi.org/project/django-filter) and [djangorestframework](https://www.django-rest-framework.org).
 
-```bash
-    pip install enum-properties
-    pip install django-filter
-    pip install djangorestframework
-```
+* [enum-properties](https://pypi.org/project/enum-properties)
+    ```bash
+    > pip install "django-enum[properties]"
+    ```
+* [django-filter](https://pypi.org/project/django-filter)
+* [djangorestframework](https://www.django-rest-framework.org)
+
 
-## Continuous Integration
+## Database Support
+
+[![Postgres](https://img.shields.io/badge/Postgres-9.6%2B-blue)](https://www.postgresql.org/)
+[![MySQL](https://img.shields.io/badge/MySQL-5.7%2B-blue)](https://www.mysql.com/)
+[![MariaDB](https://img.shields.io/badge/MariaDB-10.2%2B-blue)](https://mariadb.org/)
+[![SQLite](https://img.shields.io/badge/SQLite-3.8%2B-blue)](https://www.sqlite.org/)
+[![Oracle](https://img.shields.io/badge/Oracle-18%2B-blue)](https://www.oracle.com/database/)
 
-Like with Django, Postgres is the preferred database for support. The full test suite is run against all combinations of currently supported versions of Django, Python, and Postgres as well as psycopg3 and psycopg2. The other RDBMS supported by Django are also tested including SQLite, MySQL, MariaDB and Oracle. For these RDBMS (with the exception of Oracle), tests are run against the minimum and maximum supported version combinations to maximize coverage breadth.
+Like with [Django](https://www.djangoproject.com), [PostgreSQL](https://www.postgresql.org) is the preferred database for support. The full test suite is run against all combinations of currently supported versions of [Django](https://www.djangoproject.com), [Python](https://www.python.org), and [PostgreSQL](https://www.postgresql.org) as well as [psycopg3](https://pypi.org/project/psycopg) and [psycopg2](https://pypi.org/project/psycopg2). The other RDBMS supported by [Django](https://www.djangoproject.com) are also tested including [SQLite](https://www.sqlite.org), [MySQL](https://www.mysql.com), [MariaDB](https://mariadb.org) and [Oracle](https://www.oracle.com/database). For these RDBMS (with the exception of [Oracle](https://www.oracle.com/database), tests are run against the minimum and maximum supported version combinations to maximize coverage breadth.
 
 **See the [latest test runs](https://github.com/bckohan/django-enum/actions/workflows/test.yml) for our current test matrix**
 
-*For Oracle, only the latest version of the free database is tested against the minimum and maximum supported versions of Python, Django and the cx-Oracle driver.*
+For [Oracle](https://www.oracle.com/database), only the latest version of the free database is tested against the minimum and maximum supported versions of Python, Django and the [cx-Oracle](https://pypi.org/project/cx-Oracle) driver.
 
 ## Further Reading
 

doc/source/changelog.rst

@@ -4,9 +4,10 @@
 Change Log
 ==========
 
-v2.2.0 (2025-03-07)
+v2.2.0 (2025-03-XX)
 ===================
 
+* Implemented `Test all example code in the docs <https://github.com/bckohan/django-enum/issues/99>`_
 * Implemented `Use intersphinx for doc references <https://github.com/bckohan/django-enum/issues/98>`_
 * Implemented `Support Django 5.2 <https://github.com/bckohan/django-enum/issues/96>`_
 * Implemented `Upgrade to enum-properties >=2.2 <https://github.com/bckohan/django-enum/issues/95>`_

doc/source/conf.py

@@ -28,11 +28,9 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'django_enum'
-copyright = f'2022-{datetime.now().year}, Brian Kohan'
-author = 'Brian Kohan'
-
-# The full version, including alpha/beta/rc tags
+project = django_enum.__title__
+copyright = django_enum.__copyright__
+author = django_enum.__author__
 release = django_enum.__version__
 
 
@@ -83,6 +81,7 @@
     ),
     "enum-properties": ("https://enum-properties.readthedocs.io/en/stable", None),
     "django-render-static": ("https://django-render-static.readthedocs.io/en/stable", None),
+    "django-filter": ("https://django-filter.readthedocs.io/en/stable", None),
     "python": ('https://docs.python.org/3', None)
 }
 

doc/source/eccentric.rst

@@ -0,0 +1,106 @@
+.. include:: refs.rst
+
+.. _eccentric:
+
+===============
+Eccentric Enums
+===============
+
+Python's :class:`enum.Enum` type is extremely lenient. Enumeration values may be any hashable type
+and values of the same enumeration may be of different types.
+
+.. tip::
+
+    We define an eccentric enumeration to be any enumeration where the value type is not a simple
+    string or integer or where the enumeration values are not all of the same type.
+
+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 :doc:`enum-properties:index` should be used to store them on the
+enumeration value classes.
+
+However, the goal of django-enum_ is to provide as complete of 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
+:ref:`model field type <ref/models/fields:field types>`.
+
+* :class:`int`
+* :class:`str`
+* :class:`float`
+* :class:`datetime.date`
+* :class:`datetime.datetime`
+* :class:`datetime.time`
+* :class:`datetime.timedelta`
+* :class:`decimal.Decimal`
+
+You should avoid eccentric enums if possible, but there may be some compelling reasons to use them.
+For example, for unusual data types it may make sense in situations where the database will be used
+in a non-Python context and the enumeration values need to retain their native meaning. Or you may
+not have direct control over the enumeration you want to store.
+
+Mixed Value Enumerations
+========================
+
+Mixed value enumerations are supported. For example:
+
+.. literalinclude:: ../../tests/examples/models/mixed_value.py
+    :language: python
+
+
+:class:`~django_enum.fields.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 default to a string.
+
+.. note::
+
+    If none of the supported primitive types are symmetrically coercible
+    :class:`~django_enum.fields.EnumField` will not be able to determine an appropriate column
+    type and a :exc:`ValueError` will be raised.
+
+In these cases, or to override the primitive type selection made by
+:class:`~django_enum.fields.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 :class:`enum.Enum` class's :meth:`~enum.Enum._missing_` method:
+
+.. literalinclude:: ../../tests/examples/mixed_value_example.py
+    :language: python
+    :lines: 4-
+
+In the above case since ``None`` is an enumeration value, :class:`~django_enum.fields.EnumField`
+will automatically set null=True on the model field.
+
+The above yields::
+
+    obj.eccentric_str=<MixedValueEnum.NONE: None>
+    obj.eccentric_float=<MixedValueEnum.NONE: None>
+    obj.eccentric_str=<MixedValueEnum.VAL1: 1>
+    obj.eccentric_float=<MixedValueEnum.VAL1: 1>
+    obj.eccentric_str=<MixedValueEnum.VAL2: '2.0'>
+    obj.eccentric_float=<MixedValueEnum.VAL2: '2.0'>
+    obj.eccentric_str=<MixedValueEnum.VAL3: 3.0>
+    obj.eccentric_float=<MixedValueEnum.VAL3: 3.0>
+    obj.eccentric_str=<MixedValueEnum.VAL4: Decimal('4.5')>
+    obj.eccentric_float=<MixedValueEnum.VAL4: Decimal('4.5')>
+
+Custom Enum Value Types
+=======================
+
+.. 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 :doc:`enum-properties:index` to make your
+    enumeration types more robust by pushing more of this functionality on the :class:`enum.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:
+
+.. literalinclude:: ../../tests/examples/models/path_value.py
+    :language: python
+
+
+A fully custom value might look like the following contrived example:
+
+.. literalinclude:: ../../tests/examples/models/custom_value.py
+    :language: python