README.md

Django ChoiceField

A Django model field that casts enum values to its enum type. Supports all enum types shipped with Django and Python 3 native enum types.

---

Motivation

Have you also felt annoyed by having to convert Django's enumeration types back to its type? Using tricks seen below to cast it.

class Suit(models.IntegerChoices):
    DIAMOND = 1
    SPADE = 2
    HEART = 3
    CLUB = 4


class Card(models.Model):
    suit_kind = models.IntegerField(choices=Suit.choices, db_column="suit")

    @property
    def suit(self) -> Suit:
        return Suit(self.suit_kind)

This is what django-choicefield helps out with. While it additionally supports using Python's native enum.Enum to express column values.

Features

Using Django's enumeration types

import choicefield
from django.db import models


class Suit(models.IntegerChoices):
    DIAMOND = 1
    SPADE = 2
    HEART = 3
    CLUB = 4


class Card(models.Model):
    suit = choicefield.ChoiceField(Suit)


instance = Card.objects.create(suit=Suit.CLUB)
assert instance.suit is Suit.CLUB

There's also support for Django's models.TextChoices.

Using Python's native enumeration

import choicefield
from enum import Enum
from django.db import models


class Suit(int, Enum):
    DIAMOND = 1
    SPADE = 2
    HEART = 3
    CLUB = 4


class Card(models.Model):
    suit = choicefield.ChoiceField(Suit)


instance = Card.objects.create(suit=Suit.DIAMOND)
assert instance.suit is Suit.DIAMOND

Passing enum values

It's also possible to pass the value of an enum, which will be converted to its corresponding enum instance.

instance = Card(suit=2)
assert instance.suit is Suit.SPADE
instance.save()
assert instance.suit is Suit.SPADE
instance = Card.objects.get(suit=2)
assert instance.suit is Suit.SPADE

Getting stored database values

If you want to access the stored database values, without conversion to your enum type, you can use the registered __raw transformer.

Card.objects.values("suit__raw")
# <QuerySet [{'suit__raw': 2}]>

Getting unrecognized values from database

In case of e.g. a migration where an enum has changed by, say, removing a value. The database could have values not recognized by the registered enum. Thus it could be necessary to retrieve values without casting them to an enum instance, as it'd raise an error.

It can be done using the __raw transformer while also sidestepping enum validation in filter values by using Value expressions

Card.objects.filter(suit=Value(1337)).values_list("suit__raw", flat=True)
# <QuerySet [(1337,)]>

Installation

Using pip

$ pip install django-choicefield

Development

Running tests

Running the whole test matrix

$ tox

Setting up a development environment

$ tox -e dev

Running the test suite for one environment (non editable)

e.g. Django==4.0.x and Python3.11

$ tox -e django40-py311

Start a local example project

There are a couple of shortcut commands available using Taskfile, for your convenience.

e.g.

$ task manage -- createsuperuser
$ task runserver

After installing Taskfile you can run task --list-all to find all available commands.

Compatibility

django-choicefield is tested according to the table below

Django version	Python version
5.0.x	^3.10
4.2.x	^3.9
4.1.x	^3.9
4.0.x	^3.9
3.2.x	^3.9