Django EnumChoiceField Documentation · enum_class, which should be a subclass of enum.Enum. It is...
Transcript of Django EnumChoiceField Documentation · enum_class, which should be a subclass of enum.Enum. It is...
![Page 1: Django EnumChoiceField Documentation · enum_class, which should be a subclass of enum.Enum. It is recommended that this enum subclasses ChoiceEnum, but this is not required. When](https://reader034.fdocuments.us/reader034/viewer/2022042221/5ec74d4434b7044cbd5f3ac1/html5/thumbnails/1.jpg)
Django EnumChoiceFieldDocumentation
Release 2.0.0
Tim Heap
Dec 30, 2019
![Page 2: Django EnumChoiceField Documentation · enum_class, which should be a subclass of enum.Enum. It is recommended that this enum subclasses ChoiceEnum, but this is not required. When](https://reader034.fdocuments.us/reader034/viewer/2022042221/5ec74d4434b7044cbd5f3ac1/html5/thumbnails/2.jpg)
![Page 3: Django EnumChoiceField Documentation · enum_class, which should be a subclass of enum.Enum. It is recommended that this enum subclasses ChoiceEnum, but this is not required. When](https://reader034.fdocuments.us/reader034/viewer/2022042221/5ec74d4434b7044cbd5f3ac1/html5/thumbnails/3.jpg)
CONTENTS
1 Setup 3
2 Usage 5
3 EnumChoiceField 7
4 Enum classes 9
5 ORM Queries 11
6 Using with the Django admin 13
Python Module Index 15
Index 17
i
![Page 4: Django EnumChoiceField Documentation · enum_class, which should be a subclass of enum.Enum. It is recommended that this enum subclasses ChoiceEnum, but this is not required. When](https://reader034.fdocuments.us/reader034/viewer/2022042221/5ec74d4434b7044cbd5f3ac1/html5/thumbnails/4.jpg)
ii
![Page 5: Django EnumChoiceField Documentation · enum_class, which should be a subclass of enum.Enum. It is recommended that this enum subclasses ChoiceEnum, but this is not required. When](https://reader034.fdocuments.us/reader034/viewer/2022042221/5ec74d4434b7044cbd5f3ac1/html5/thumbnails/5.jpg)
Django EnumChoiceField Documentation, Release 2.0.0
For a quick example, check out the code below:
from enumchoicefield import ChoiceEnum, EnumChoiceField
class Fruit(ChoiceEnum):apple = "Apple"banana = "Banana"orange = "Orange"
class Profile(models.Model):name = models.CharField(max_length=100)favourite_fruit = EnumChoiceField(Fruit, default=Fruit.banana)
citrus_lovers = Profile.objects.filter(favourite_fruit=Fruit.orange)
Contents:
CONTENTS 1
![Page 6: Django EnumChoiceField Documentation · enum_class, which should be a subclass of enum.Enum. It is recommended that this enum subclasses ChoiceEnum, but this is not required. When](https://reader034.fdocuments.us/reader034/viewer/2022042221/5ec74d4434b7044cbd5f3ac1/html5/thumbnails/6.jpg)
Django EnumChoiceField Documentation, Release 2.0.0
2 CONTENTS
![Page 7: Django EnumChoiceField Documentation · enum_class, which should be a subclass of enum.Enum. It is recommended that this enum subclasses ChoiceEnum, but this is not required. When](https://reader034.fdocuments.us/reader034/viewer/2022042221/5ec74d4434b7044cbd5f3ac1/html5/thumbnails/7.jpg)
CHAPTER
ONE
SETUP
django-enumchoicefield is compatible with Django 1.8 and higher, Python 2.7, and Python 3.4 and higher.
You can install django-enumchoicefield using pip:
$ pip install django-enumchoicefield
On Python 2.7, you will also need to install enum34:
$ pip install enum34
3
![Page 8: Django EnumChoiceField Documentation · enum_class, which should be a subclass of enum.Enum. It is recommended that this enum subclasses ChoiceEnum, but this is not required. When](https://reader034.fdocuments.us/reader034/viewer/2022042221/5ec74d4434b7044cbd5f3ac1/html5/thumbnails/8.jpg)
Django EnumChoiceField Documentation, Release 2.0.0
4 Chapter 1. Setup
![Page 9: Django EnumChoiceField Documentation · enum_class, which should be a subclass of enum.Enum. It is recommended that this enum subclasses ChoiceEnum, but this is not required. When](https://reader034.fdocuments.us/reader034/viewer/2022042221/5ec74d4434b7044cbd5f3ac1/html5/thumbnails/9.jpg)
CHAPTER
TWO
USAGE
The following code outlines the most simple usecase of EnumChoiceField:
from enumchoicefield import ChoiceEnum, EnumChoiceField
class Fruit(ChoiceEnum):apple = "Apple"banana = "Banana"orange = "Orange"
class Profile(models.Model):name = models.CharField(max_length=100)favourite_fruit = EnumChoiceField(Fruit, default=Fruit.banana)
citrus_lovers = Profile.objects.filter(favourite_fruit=Fruit.orange)
The enumerations should extend the ChoiceEnum class. For each member in the enumeration, their human-readablename should be their value. This human-readable name will be used when presenting forms to the user.
For more advanced usage, refer to the documentation on EnumChoiceField, Enum classes, or ORM Queries.
5
![Page 10: Django EnumChoiceField Documentation · enum_class, which should be a subclass of enum.Enum. It is recommended that this enum subclasses ChoiceEnum, but this is not required. When](https://reader034.fdocuments.us/reader034/viewer/2022042221/5ec74d4434b7044cbd5f3ac1/html5/thumbnails/10.jpg)
Django EnumChoiceField Documentation, Release 2.0.0
6 Chapter 2. Usage
![Page 11: Django EnumChoiceField Documentation · enum_class, which should be a subclass of enum.Enum. It is recommended that this enum subclasses ChoiceEnum, but this is not required. When](https://reader034.fdocuments.us/reader034/viewer/2022042221/5ec74d4434b7044cbd5f3ac1/html5/thumbnails/11.jpg)
CHAPTER
THREE
ENUMCHOICEFIELD
class enumchoicefield.fields.EnumChoiceField(enum_class, ...)Create an EnumChoiceField. This field generates choices from an enum.Enum.
The EnumChoiceField extends django.db.models.Field. It accepts one additional argument:enum_class, which should be a subclass of enum.Enum. It is recommended that this enum subclassesChoiceEnum, but this is not required.
When saving enum members to the database, The chosen member is stored in the database using its nameattribute. This keeps the database representation stable when adding and removing enum members.
A max_length is automatically generated from the longest name. If you add a new enum member with alonger name, or remove the longest member, the generated max_length will change. To prevent this, you canmanually set a max_length argument, and this will be used instead.
If a default choice is supplied, the enum class must have a deconstruct method. If the enum inherits fromDeconstructableEnum, this will be handled for you.
The display value for the Enums is taken from the str representation of each value. By default this is somethinglike MyEnum.foo, which is not very user friendly. PrettyEnum makes defining a human-readable strrepresentation easy.
7
![Page 12: Django EnumChoiceField Documentation · enum_class, which should be a subclass of enum.Enum. It is recommended that this enum subclasses ChoiceEnum, but this is not required. When](https://reader034.fdocuments.us/reader034/viewer/2022042221/5ec74d4434b7044cbd5f3ac1/html5/thumbnails/12.jpg)
Django EnumChoiceField Documentation, Release 2.0.0
8 Chapter 3. EnumChoiceField
![Page 13: Django EnumChoiceField Documentation · enum_class, which should be a subclass of enum.Enum. It is recommended that this enum subclasses ChoiceEnum, but this is not required. When](https://reader034.fdocuments.us/reader034/viewer/2022042221/5ec74d4434b7044cbd5f3ac1/html5/thumbnails/13.jpg)
CHAPTER
FOUR
ENUM CLASSES
class enumchoicefield.enum.PrettyEnumA PrettyEnum makes defining nice, human-readable names for enum members easy. To use it, subclassPrettyEnum and declare the enum members with their human-readable name as their value:
class Fruit(PrettyEnum):apple = "Apple"banana = "Banana"orange = "Orange"
The members’ values will be automatically set to ascending integers, starting at one. In the example above,Fruit.apple.value is 1, and Fruit.orange.value is 3.
class enumchoicefield.enum.DeconstructableEnum
deconstruct()a DeconstructableEnum defines deconstruct(), compatible with Django migrations. If youwant to set a default for an EnumChoiceField, the enum must be deconstructable.
class enumchoicefield.enum.ChoiceEnuma ChoiceEnum extends both PrettyEnum and DeconstructableEnum. It is recommended to use aChoiceEnum subclass with EnumChoiceField, but this is not required.
9
![Page 14: Django EnumChoiceField Documentation · enum_class, which should be a subclass of enum.Enum. It is recommended that this enum subclasses ChoiceEnum, but this is not required. When](https://reader034.fdocuments.us/reader034/viewer/2022042221/5ec74d4434b7044cbd5f3ac1/html5/thumbnails/14.jpg)
Django EnumChoiceField Documentation, Release 2.0.0
10 Chapter 4. Enum classes
![Page 15: Django EnumChoiceField Documentation · enum_class, which should be a subclass of enum.Enum. It is recommended that this enum subclasses ChoiceEnum, but this is not required. When](https://reader034.fdocuments.us/reader034/viewer/2022042221/5ec74d4434b7044cbd5f3ac1/html5/thumbnails/15.jpg)
CHAPTER
FIVE
ORM QUERIES
You can filter and search for enum members using standard Django ORM queries. The following queries demonstratesome 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])
5.1 Ordering
Ordering on a EnumChoiceField field will order results alphabetically by the names of the enum members, whichis probably not useful. To order results by an enum value, enumchoicefield.utils.order_enum() can beused.
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')
11
![Page 16: Django EnumChoiceField Documentation · enum_class, which should be a subclass of enum.Enum. It is recommended that this enum subclasses ChoiceEnum, but this is not required. When](https://reader034.fdocuments.us/reader034/viewer/2022042221/5ec74d4434b7044cbd5f3ac1/html5/thumbnails/16.jpg)
Django EnumChoiceField Documentation, Release 2.0.0
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.
5.2 Undefined behaviour
Internally, the enum member is stored as a CharField using the name attribute. Any operation that CharFields supportare also supported by an EnumChoiceField. Not all of these operations make sense, such as contains, gt, andstartswith, and may not behave in a sensible manner.
12 Chapter 5. ORM Queries
![Page 17: Django EnumChoiceField Documentation · enum_class, which should be a subclass of enum.Enum. It is recommended that this enum subclasses ChoiceEnum, but this is not required. When](https://reader034.fdocuments.us/reader034/viewer/2022042221/5ec74d4434b7044cbd5f3ac1/html5/thumbnails/17.jpg)
CHAPTER
SIX
USING WITH THE DJANGO ADMIN
EnumChoiceFields are compatible with the Django admin out of the box, with one exception. If you want to usea EnumChoiceField in a list_filter, you need to use the EnumListFilter.
class enumchoicefield.admin.EnumListFilter(*args, **kwargs)A FieldListFilter for use in Django admin in combination with an EnumChoiceField. Use like:
class FooModelAdmin(ModelAdmin):list_filter = [
('enum_field', EnumListFilter),]
13
![Page 18: Django EnumChoiceField Documentation · enum_class, which should be a subclass of enum.Enum. It is recommended that this enum subclasses ChoiceEnum, but this is not required. When](https://reader034.fdocuments.us/reader034/viewer/2022042221/5ec74d4434b7044cbd5f3ac1/html5/thumbnails/18.jpg)
Django EnumChoiceField Documentation, Release 2.0.0
14 Chapter 6. Using with the Django admin
![Page 19: Django EnumChoiceField Documentation · enum_class, which should be a subclass of enum.Enum. It is recommended that this enum subclasses ChoiceEnum, but this is not required. When](https://reader034.fdocuments.us/reader034/viewer/2022042221/5ec74d4434b7044cbd5f3ac1/html5/thumbnails/19.jpg)
PYTHON MODULE INDEX
eenumchoicefield.enum, 9enumchoicefield.fields, 7enumchoicefield.utils, 11
15
![Page 20: Django EnumChoiceField Documentation · enum_class, which should be a subclass of enum.Enum. It is recommended that this enum subclasses ChoiceEnum, but this is not required. When](https://reader034.fdocuments.us/reader034/viewer/2022042221/5ec74d4434b7044cbd5f3ac1/html5/thumbnails/20.jpg)
Django EnumChoiceField Documentation, Release 2.0.0
16 Python Module Index
![Page 21: Django EnumChoiceField Documentation · enum_class, which should be a subclass of enum.Enum. It is recommended that this enum subclasses ChoiceEnum, but this is not required. When](https://reader034.fdocuments.us/reader034/viewer/2022042221/5ec74d4434b7044cbd5f3ac1/html5/thumbnails/21.jpg)
INDEX
CChoiceEnum (class in enumchoicefield.enum), 9
Ddeconstruct() (enumchoice-
field.enum.DeconstructableEnum method),9
DeconstructableEnum (class in enumchoice-field.enum), 9
EEnumChoiceField (class in enumchoicefield.fields), 7enumchoicefield.enum (module), 9enumchoicefield.fields (module), 7enumchoicefield.utils (module), 11EnumListFilter (class in enumchoicefield.admin),
13
Oorder_enum() (in module enumchoicefield.utils), 11
PPrettyEnum (class in enumchoicefield.enum), 9
17