[Django] #33193: Clarify enumeration types are true Python Enums

Django

unread,

Oct 14, 2021, 8:13:50 AM10/14/21

to django-...@googlegroups.com

#33193: Clarify enumeration types are true Python Enums
------------------------------------------------+------------------------
Reporter: johnthagen | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 3.2
Severity: Normal | Keywords: enum
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
------------------------------------------------+------------------------
https://docs.djangoproject.com/en/3.2/ref/models/fields/#field-choices-
enum-types

I was originally hesitant to use the Django "enumeration fields" when I
first read about them because to me the documentation made it sound like
they were "similar" to Python Enums, but something different. I value
using core data types for interop with other non-Django specific code, so
I continued to use django-enumfields (https://github.com/hzdg/django-
enumfields) for several releases. This allowed me to use true Python Enums
which are familiar to use to developers not as versed in Django.

Recently I dug into the Django source code more deeply after hearing about
them again and discovered that indeed the Choices type is really just an
Enum with a little extra magic and some extra helper methods applied to
them (and as such can be used as a normal Python Enum as well).

{{{
class ChoicesMeta(enum.EnumMeta):
"""A metaclass for creating a enum choices."""

...

class Choices(enum.Enum, metaclass=ChoicesMeta):
"""Class for creating enumerated choices."""
}}}

I would recommend modifying the docs in some way, for example:

> These work similar to enum from Python’s standard library, but with some
modifications:

Could be reworded:

> These are true `Enum`s from Python's standard library, but with some
additional extensions added:

--
Ticket URL: <https://code.djangoproject.com/ticket/33193>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

Django

unread,

Oct 14, 2021, 8:58:50 AM10/14/21

to django-...@googlegroups.com

#33193: Clarify enumeration types are true Python Enums

-------------------------------------+-------------------------------------

Comment (by johnthagen):

Continuing some research, I learned that Django won't return an `Enum`
instance from a field decorated using a `Choices` `Enum` (as described at
the bottom of https://stackoverflow.com/a/58051918), unlike `django-
enumfields` (https://pypi.org/project/django-enumfields/). Since the user
doesn't get an `Enum` instance back out directly, perhaps the way the docs
are currently worded is in fact appropriate.

--
Ticket URL: <https://code.djangoproject.com/ticket/33193#comment:1>

Django

unread,

Oct 14, 2021, 11:29:30 AM10/14/21

to django-...@googlegroups.com

#33193: Clarify enumeration types are true Python Enums

-------------------------------------+-------------------------------------
Changes (by Mariusz Felisiak):