Configure EnumFields

All parameters available to the equivalent model field with choices may be set directly in the EnumField instantiation. If not provided EnumField will set choices and max_length automatically.

The following EnumField specific parameters are available:

strict

By default all EnumField are strict. This means a ValidationError will be thrown anytime full_clean() is run on a model and a value is set for the field that can not be coerced to its native Enum type. To allow the field to store values that are not present in the fields Enum type we can pass strict=False.

Non-strict fields will be instances of the enumeration where a valid Enum value is present and the plain old data where no Enum type coercion is possible.

from django.db import models
from django_enum import EnumField


class StrictExample(models.Model):

    class EnumType(models.TextChoices):

        ONE = "1", "One"
        TWO = "2", "Two"

    non_strict = EnumField(
        EnumType,
        strict=False,
        # it might be necessary to override max_length also,
        # otherwise max_length will be 1
        max_length=10,
    )

obj = StrictExample()

# set to a valid EnumType value
obj.non_strict = '1'
# when accessed will be an EnumType instance
assert obj.non_strict is StrictExample.EnumType.ONE

# we can also store any string less than or equal to length 10
obj.non_strict = 'arbitrary'
obj.full_clean()  # no errors
# when accessed will be a str instance
assert obj.non_strict == 'arbitrary'

constrained

By default all strict EnumField are constrained. This means that CheckConstraints will be generated at the database level to ensure that the column will reject any value that is not present in the enumeration. This is a good idea for most use cases, but it can be turned off by setting constrained to False.

Note

This is new in version 2.0. If you are upgrading from a previous version, you may set this parameter to False to maintain the previous behavior.

primitive

EnumField dynamically determines the database column type by determining the most appropriate primitive type for the enumeration based on the enumeration values. You may override the primitive determined by EnumField by passing a type to the primitive parameter. You will likely not need to do this unless your enumeration is eccentric in some way.

coerce

Setting this parameter to False will turn off the automatic conversion to the field’s Enum type while leaving all validation checks in place. It will still be possible to set the field directly as an Enum instance and to filter by Enum instance or any symmetric value:

    non_strict = EnumField(
        EnumType,
        strict=False,
        coerce=False,
        # it might be necessary to override max_length also, otherwise
        # max_length will be 1
        max_length=10,
    )

# set to a valid EnumType value
obj.non_strict = '1'

# when accessed will be the primitive value
assert obj.non_strict == '1'
assert isinstance(obj.non_strict, str)
assert not isinstance(obj.non_strict, NoCoerceExample.EnumType)