Moving to Django 3.0’s Field.choices Enumeration Types

One of the headline features of Django 3.0 is its Enumerations for model field choices. They’re a nicer way of defining and constraining model Field.choices.

Previously, Django recommended defining some ‘constants’ on your model class to feed into choices. You would add these as separate class variables and combine them into a list of choices paired with their display strings:

from django.db import models


class Book(models.Model):
    UNPUBLISHED = "UN"
    PUBLISHED = "PB"
    STATUS_CHOICES = [
        (UNPUBLISHED, "Unpublished"),
        (PUBLISHED, "Published"),
    ]
    status = models.CharField(
        max_length=2,
        choices=STATUS_CHOICES,
        default=UNPUBLISHED,
    )

Then your other could use those constants, for example:

unpublished_books = Book.objects.filter(status=Book.UNPUBLISHED)

If you wanted to use the same set of values for multiple models, you would probably move to the module level:

from django.db import models

UNPUBLISHED = "UN"
PUBLISHED = "PB"
STATUS_CHOICES = [
    (UNPUBLISHED, "Unpublished"),
    (PUBLISHED, "Published"),
]


class Book(models.Model):
    status = models.CharField(
        max_length=2,
        choices=STATUS_CHOICES,
        default=UNPUBLISHED,
    )


class Pamphlet(models.Model):
    status = models.CharField(
        max_length=2,
        choices=STATUS_CHOICES,
        default=PUBLISHED,
    )

This leaves a bunch of constants related only by their position in the class or module. It’s a bit against The Zen of Python’s final edict:

Namespaces are one honking great idea – let’s do more of those!

It also leaves us missing some useful functionality. For example there’s no easy way to convert a value into its display label.

Update (2020-01-28): As pointed out by Airith on Redit, model instances do provide get_FOO_display() methods to convert values to display labels.

Packages like django-choices and django-enumfields exist to solve these problems. I’ve also seen a couple custom implementations of similar functionality on other projects.

Django 3.0 now provides a Choices class with two subclasses IntegerChoices and TextChoices. These extend Python’s Enum types with extra constraints and functionality to make them suitable for Field.choices.

To convert our example, we want to subclass TextChoices, because the values are strings stored in a CharField. We then define how names map to values and display labels as class attributes:

from django.db import models


class Status(models.TextChoices):
    UNPUBLISHED = "UN", "Unpublished"
    PUBLISHED = "PB", "Published"


class Book(models.Model):
    status = models.CharField(
        max_length=2,
        choices=Status.choices,
        default=Status.UNPUBLISHED,
    )


class Pamphlet(models.Model):
    status = models.CharField(
        max_length=2,
        choices=Status.choices,
        default=Status.PUBLISHED,
    )

We can test we converted correctly by checking no migration changes are detected:

$ python manage.py makemigrations --dry-run
No changes detected

If we had added, removed, or reordered any members, this would have been detected as changes in the fields. This is because the migration framework only sees the choices list generated by Status.choices, not the enumeration classes.

QuerySet filters can be updated to use the Choices class:

unpublished_books = Book.objects.filter(status=Status.UNPUBLISHED)

We can also convert values to their display labels easily:

In [2]: book = Book.objects.latest('id')

In [3]: Status(book.status)
Out[3]: <Status.UNPUBLISHED: 'UN'>

In [4]: Status(book.status).label
Out[4]: 'Unpublished'

Clearer and cleaner!

Read my book Boost Your Git DX to Git better.

One summary email a week, no spam, I pinky promise.

Related posts:

• Django’s Field Choices Don’t Constrain Your Data
• A Single File Asynchronous Django Application
• How to Add Database Modifications Beyond Migrations to Your Django Project

Tags: django