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 name
s 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 theenum34
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.