Package: dj.choicee
This is a much clearer way to specify choices for fields in models and forms.
A basic example:>>>fromdj.choiceeimportChoices>>>classGender(Choices):..._=Choices.Choice......male=_("Male")...female=_("Female")...>>>Gender()[(1,'Male'),(2,'Female')]>>>Gender.male<Choice:male(id:1)>>>>Gender.female<Choice:female(id:2)>>>>Gender.male.id1>>>Gender.male.desc'Male'>>>Gender.male.raw'Male'>>>Gender.male.name'male'>>>Gender.from_name("male")<Choice:male(id:1)>>>>Gender.id_from_name("male")1>>>Gender.raw_from_name("male")'Male'>>>Gender.desc_from_name("male")'Male'>>>Gender.name_from_id(2)'female'>>>Gender.name_from_id(3)Traceback(mostrecentcalllast):...ValueError:Nothingfoundfor'3'.>>>Gender.from_name("perez")Traceback(mostrecentcalllast):...ValueError:Nothingfoundfor'perez'.You define a class of choices, specifying each choice as a class attribute.
Those attributes areintsubclasses, numbered automatically starting with
1.  The class provides several features which support the DRY principle:An object instantiated from the choices class is basically a list of(id, localized_description)pairs straight for consumption by Django.Each attribute defined can be retrieved directly from the class.Metadata (e.g. attribute name, raw and localized description, numeric ID) of
each attribute is accessible.Choices which are suffixed by_to avoid clashing with Python keywords
have this suffix automatically removed in their.nameattributesLookup functions are available to help getting attributes or their metadata.NoteThe_ = Choices.Choicetrick makes it possible fordjango-admin.pymakemessagesto find each choice description and include it in.pofiles for localization.  It masksgettextonly in the scope of the class so
the rest of the module can safely usegettextorgettext_lazy.  Having to
specify_each time is not a particularly pretty solution but it’s
explicit. Suggestions for a better approach are welcome.Grouping choicesOne of the worst problems with choices is their weak extensibility.  For
instance, an application defines a group of possible choices like this:>>>classLicense(Choices):..._=Choices.Choice......gpl=_("GPL")...bsd=_("BSD")...proprietary=_("Proprietary")...>>>License()[(1,'GPL'),(2,'BSD'),(3,'Proprietary')]All is well until the application goes live and after a while the developer
wants to include LGPL.  The natural choice would be to add it aftergplbut
when we do that, the indexing would break.  On the other hand, adding the new
entry at the end of the definition looks ugly and makes the resulting combo
boxes in the UI sorted in a counter-intuitive way.  Grouping lets us solve this
problem by explicitly defining the structure within a class of choices:>>>classLicense(Choices):..._=Choices.Choice......COPYLEFT=Choices.Group(0)...gpl=_("GPL")......PUBLIC_DOMAIN=Choices.Group(100)...bsd=_("BSD")......OSS=Choices.Group(200)...apache2=_("Apache 2")......COMMERCIAL=Choices.Group(300)...proprietary=_("Proprietary")...>>>License()[(1,'GPL'),(101,'BSD'),(201,'Apache 2'),(301,'Proprietary')]This enables the developer to include more licenses of each group later on:>>>classLicense(Choices):..._=Choices.Choice......COPYLEFT=Choices.Group(0)...gpl_any=_("GPL, any")...gpl2=_("GPL 2")...gpl3=_("GPL 3")...lgpl=_("LGPL")...agpl=_("Affero GPL")......PUBLIC_DOMAIN=Choices.Group(100)...bsd=_("BSD")...public_domain=_("Public domain")......OSS=Choices.Group(200)...apache2=_("Apache 2")...mozilla=_("MPL")......COMMERCIAL=Choices.Group(300)...proprietary=_("Proprietary")...>>>License()[(1,'GPL, any'),(2,'GPL 2'),(3,'GPL 3'),(4,'LGPL'),(5,'Affero GPL'),(101,'BSD'),(102,'Public domain'),(201,'Apache 2'),(202,'MPL'),(301,'Proprietary')]Note the behaviour:the developer renamed the GPL choice but its meaning and ID remained stableBSD, Apache and proprietary choices have their IDs unchangedthe resulting class is self-descriptive, readable and extensibleAs a bonus, the explicitly specified groups can be used when needed:>>>License.COPYLEFT<ChoiceGroup:COPYLEFT(id:0)>>>>License.gpl2inLicense.COPYLEFT.choicesTrue>>>[(c.id,c.desc)forcinLicense.COPYLEFT.choices][(1,'GPL, any'),(2,'GPL 2'),(3,'GPL 3'),(4,'LGPL'),(5,'Affero GPL')]ChoiceFieldChoices can be used with genericIntegerFieldandCharFieldinstances.
When you do that though, some minor API deficiencies show up fairly quickly.
First, when you define the field, you have to instanciate the choices class and
the default value has to be converted to the proper type explicitly:color=models.IntegerField(choices=Color(),default=Color.green.id)Second, when getting the attribute back from a model, it has to be converted to
aChoiceinstance to do anything interesting with it:>>>obj=Model.objects.get(pk=3)>>>obj.color3>>>Color.from_id(obj.color)<Choice:Blue(id:3,name:blue)>To overcome those problems aChoiceFieldis available in thedj.choicee.fieldspackage.  It is based on integers on the database level but
the API exposesChoiceinstances.  This helps both on the definition side:color=ChoiceField(choices=Color,default=Color.green)and on the access side:>>>obj=Model.objects.get(pk=3)>>>obj.color<Choice:Blue(id:3,name:blue)>>>>obj.color=Color.green>>>obj.save()>>>Model.objects.get(pk=3).color<Choice:Green(id:2,name:green)>For rendering forms, the field coerces to integer values.  That also means that
whereverChoiceinstances are accepted, integers are also fine.Advanced functionalityFilteringThe developer can specify all possible choices for future use and then filter
out only the currently applicable values on choices creation:>>>classLanguage(Choices):..._=Choices.Choice......de=_("German")...en=_("English")...fr=_("French")...pl=_("Polish")...>>>Language()[(1,'German'),(2,'English'),(3,'French'),(4,'Polish')]>>>Language(filter=("en","pl"))[(2,'English'),(4,'Polish')]This has the great advantage of keeping the IDs and sorting intact.Custom item formatOne can also change how the pairs are constructed by providing a factory
function.  For instance, to use the class of choices defined above for theLANGUAGESsetting insettings.py, one could specify:>>>Language(item=lambdachoice:(choice.name,choice.raw))[('de','German'),('en','English'),('fr','French'),('pl','Polish')]Extra attributes on choicesEach choice can receive extra arguments using theextra()method:>>>classPython(Choices):..._=Choices.Choice......cpython=_("CPython").extra(language='C')...pypy=_("PyPy").extra(language='Python')...jython=_("Jython").extra(language='Java')...iron_python=_("IronPython").extra(language='C#')This adds alanguageattribute to each choice so you can get it back like
this:>>>Python.jython.language'Java'This enables polymorphic attribute access later on when using models or forms.
For instance, suppose you have a simple model like:>>>classLibrary(models.Model):...name=models.CharField(max_length=100)...python_kind=models.IntegerField(choices=Python(),default=Python.cpython.id)In that case to get the implementation language back yo’d do:>>>library=Library.objects.get(name='dj.choicee')>>>Python.from_id(library.python_kind).language'C'That frees your user code of any conditionals or dictionaries that depend on the
state of the choices class.  If you would add another choice to it, no user code
needs to be changed to support it.  This also supports the DRY principle because
the choices class becomes the single place where configuration of that kind is
held.Extra attributes on choice groupsUnsurprisingly, choice groups can have extra attributes as well.  They are then
inherited by choices in such a group and can be overriden if necessary.  For
instance:>>>classProfileChange(Choices):..._=Choices.Choice......USER=Choices.Group(0).extra(icon='bookkeeping.png',is_public=True)...email=_("e-mail").extra(is_public=False)...first_name=_("first name")...last_name=_("last name")......BASIC_INFO=Choices.Group(10).extra(icon='bookkeeping.png',is_public=True)...birth_date=_("birth date").extra(icon='calendar.png')...gender=_("gender").extra(icon='male_female.png')...country=_("country")...city=_("city")......CONTACT_INFO=Choices.Group(20).extra(icon='contactbook.png',is_public=False)...skype=_("Skype ID")...icq=_("ICQ number")...msn=_("MSN login")...xfire=_("X-Fire login")...irc=_("IRC info").extra(is_public=True)In that case proper inheritance takes place:>>>ProfileChange.first_name.is_publicTrue>>>ProfileChange.email.is_publicFalse>>>ProfileChange.country.icon'bookkeeping.png'>>>ProfileChange.birth_date.icon'calendar.png'Predefined choicesThere are several classes of choices which are very common in web applications
so they are provided already:Country,GenderandLanguage.How do I run the tests?Installtoxthen run:$tox-epyChange Log1.0.0Pure Python 3 (drop Python 2 compatibility).Support only Python3.5+ and Django 2.0+Fork fromdj.choicesto new project.AuthorsOriginaldj.choicesauthorŁukasz Langa.Fork and drop legacy Python2 code:Nguyễn Hồng Quân.