Grouping choices

One of the worst problems with choices is their weak extensibility. For instance, an application defines a group of possible choices like this:

>>> class License(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 after gpl but 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:

>>> class License(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:

>>> class License(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 stable

• BSD, Apache and proprietary choices have their IDs unchanged

• the resulting class is self-descriptive, readable and extensible

As a bonus, the explicitly specified groups can be used when needed:

>>> License.COPYLEFT
<ChoiceGroup: COPYLEFT (id: 0)>
>>> License.gpl2 in License.COPYLEFT.choices
True
>>> [(c.id, c.desc) for c in License.COPYLEFT.choices]
[(1, 'GPL, any'), (2, 'GPL 2'), (3, 'GPL 3'), (4, 'LGPL'),
 (5, 'Affero GPL')]

ChoiceField

Choices can be used with generic IntegerField and CharField instances. 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 a Choice instance to do anything interesting with it:

>>> obj = Model.objects.get(pk=3)
>>> obj.color
3
>>> Color.from_id(obj.color)
<Choice: Blue (id: 3, name: blue)>

To overcome those problems a ChoiceField is available in the dj.choicee.fields package. It is based on integers on the database level but the API exposes Choice instances. 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 wherever Choice instances are accepted, integers are also fine.

Advanced functionality

>>> class Language(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')]

>>> Language(item=lambda choice: (choice.name, choice.raw))
[('de', 'German'), ('en', 'English'), ('fr', 'French'),
 ('pl', 'Polish')]

>>> class Python(Choices):
...   _ = Choices.Choice
...
...   cpython = _("CPython").extra(language='C')
...   pypy = _("PyPy").extra(language='Python')
...   jython = _("Jython").extra(language='Java')
...   iron_python = _("IronPython").extra(language='C#')

>>> Python.jython.language
'Java'

>>> class Library(models.Model):
...   name = models.CharField(max_length=100)
...   python_kind = models.IntegerField(choices=Python(), default=Python.cpython.id)

>>> library = Library.objects.get(name='dj.choicee')
>>> Python.from_id(library.python_kind).language
'C'

>>> class ProfileChange(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)

>>> ProfileChange.first_name.is_public
True
>>> ProfileChange.email.is_public
False
>>> ProfileChange.country.icon
'bookkeeping.png'
>>> ProfileChange.birth_date.icon
'calendar.png'

Predefined choices

There are several classes of choices which are very common in web applications so they are provided already: Country, Gender and Language.

How do I run the tests?

Install tox then run:

$ tox -e py

Change Log

Authors

• Original dj.choices author Łukasz Langa.

• Fork and drop legacy Python2 code: Nguyễn Hồng Quân.