Skip to main content

ChoiceField for Django models

Project description

Django ChoiceField

CI Build Status PyPI Package Python versions


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")

    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.


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
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.

# <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,)]>


Using pip

$ pip install django-choicefield


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.


$ task manage -- createsuperuser
$ task runserver

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


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

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_choicefield-0.2.3.tar.gz (16.4 kB view hashes)

Uploaded source

Built Distribution

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page