django-enumfield
Provides an enumeration Django model field (using IntegerField
) with reusable enums and transition validation.
Installation
Currently, we test Django versions 2.2-4.1 and Python versions 3.7-3.11.
Install django-enumfield
in your Python environment:
$ pip install django-enumfield
Upgrading from django-enumfield 1.x? See the migration guide
For use with Django versions prior to 1.8 use version
1.2.1
For use with Django versions prior to 1.11 use version
1.5
Usage
Create an Enum
-class and pass it as first argument to the Django model EnumField
.
from django.db import models
from django_enumfield import enum
class BeerStyle(enum.Enum):
LAGER = 0
STOUT = 1
WEISSBIER = 2
class Beer(models.Model):
style = enum.EnumField(BeerStyle, default=BeerStyle.LAGER)
print(BeerStyle.get("LAGER"))
print(BeerStyle.get(1))
print(BeerStyle.get(BeerStyle.WEISSBIER))
print(BeerStyle(1))
print(BeerStyle["LAGER"])
print(BeerStyle.LAGER.value)
print(BeerStyle.LAGER.name)
For more information about Python 3 enums
(which our Enum
inherits, IntEnum
to be specific)
checkout the docs.
Setting the default value
You can also set default value on your enum class using __default__
attribute
from django.db import models
from django_enumfield import enum
class BeerStyle(enum.Enum):
LAGER = 0
STOUT = 1
WEISSBIER = 2
__default__ = LAGER
class BeerStyleNoDefault(enum.Enum):
LAGER = 0
class Beer(models.Model):
style_default_lager = enum.EnumField(BeerStyle)
style_default_stout = enum.EnumField(BeerStyle, default=BeerStyle.STOUT)
style_default_null = enum.EnumField(BeerStyleNoDefault, null=True, blank=True)
assert BeerStyle.default() == BeerStyle.LAGER
beer = Beer.objects.create()
assert beer.style_default_larger == BeerStyle.LAGER
assert beer.style_default_stout == BeerStyle.STOUT
assert beer.style_default_null is None
Labels
You can use your own labels for Enum
items
from django.utils.translation import gettext_lazy
from django_enumfield import enum
class Animals(enum.Enum):
CAT = 1
DOG = 2
SHARK = 3
__labels__ = {
CAT: gettext_lazy("Cat"),
DOG: gettext_lazy("Dog"),
}
print(Animals.CAT.label)
print(Animals.SHARK.label)
print(Animals.get_label(2))
print(Animals.get_label("DOG"))
Validate transitions
The Enum
-class provides the possibility to use transition validation.
from django.db import models
from django_enumfield import enum
from django_enumfield.exceptions import InvalidStatusOperationError
class PersonStatus(enum.Enum):
ALIVE = 1
DEAD = 2
REANIMATED = 3
__transitions__ = {
DEAD: (ALIVE,),
REANIMATED: (DEAD,)
}
class Person(models.Model):
status = enum.EnumField(PersonStatus)
person = Person.objects.create(status=PersonStatus.ALIVE)
try:
person.status = PersonStatus.REANIMATED
except InvalidStatusOperationError:
print("Person status can not go from ALIVE to REANIMATED")
else:
person.save()
In forms
The Enum
-class can also be used without the EnumField
. This is very useful in Django form ChoiceField
s.
from django import forms
from django_enumfield import enum
from django_enumfield.forms.fields import EnumChoiceField
class GenderEnum(enum.Enum):
MALE = 1
FEMALE = 2
__labels__ = {
MALE: "Male",
FEMALE: "Female",
}
class PersonForm(forms.Form):
gender = EnumChoiceField(GenderEnum)
Rendering PersonForm
in a template will generate a select-box with "Male" and "Female" as option labels for the gender field.
Local Development Environment
Make sure black and isort is installed in your env with pip install -e .[dev]
.
Before committing run make format
to apply black and isort to all files.