ORM Queries

You can filter and search for enum members using standard Django ORM queries. The following queries demonstrate some of what is possible:

from enumchoicefield import ChoiceEnum, EnumChoiceField

class Fruit(ChoiceEnum):
    apple = "Apple"
    banana = "Banana"
    lemon = "Lemon"
    lime = "Lime"
    orange = "Orange"

class Profile(models.Model):
    name = models.CharField(max_length=100)
    favourite_fruit = EnumChoiceField(Fruit, default=Fruit.banana)


apple_lovers = Profile.objects.filter(favourite_fruit=Fruit.apple)
banana_haters = Profile.objects.exclude(favourite_fruit=Fruit.banana)

citrus_fans = Profile.objects.filter(
    favourite_fruit__in=[Fruit.orange, Fruit.lemon, Fruit.lime])

Ordering

Ordering on a EnumChoiceField field will order results alphabetically by the names of the enum members, which is probably not useful. To order results by an enum value, enumchoicefield.utils.order_enum() can be used.

enumchoicefield.utils.order_enum(field, members)

Make an annotation value that can be used to sort by an enum field.

field

The name of an EnumChoiceField.

members

An iterable of Enum members in the order to sort by.

Use like:

desired_order = [MyEnum.bar, MyEnum.baz, MyEnum.foo]
ChoiceModel.objects\
    .annotate(my_order=order_enum('choice', desired_order))\
    .order_by('my_order')

As Enums are iterable, members can be the Enum itself if the default ordering is desired:

ChoiceModel.objects\
    .annotate(my_order=order_enum('choice', MyEnum))\
    .order_by('my_order')

Warning

On Python 2, Enums may not have a consistent order, depending upon how they were defined. You can set an explicit order using __order__ to fix this. See the enum34 docs for more information.

Any enum members not present in the list of members will be sorted to the end of the results.

Undefined behaviour

Internally, the enum member is stored as a CharField using the name attribute. Any operation that CharFields support are also supported by an EnumChoiceField. Not all of these operations make sense, such as contains, gt, and startswith, and may not behave in a sensible manner.