Skip to main content

Better choices library for Django web framework

Project description

Django Better Choices

PyPI PyPI - Python Version Build Status codecov License

Better choices library for Django web framework.


This library was written for Python 3.7+ and will not work in any earlier versions.


pip install django-better-choices


To start defining better choices, you need first to import the Choices class.

from django_better_choices import Choices

Class definition

The choices can be defined with overriding Choices class.

class PAGE_STATUS(Choices):
    CREATED = 'Created'
    PENDING = Choices.Value('Pending', help_text='This set status to pending')
    ON_HOLD = Choices.Value('On Hold', value='custom_on_hold')

    VALID = Choices.Subset('CREATED', ON_HOLD)

    class INTERNAL_STATUS(Choices):
        REVIEW = 'On Review'

Overridden choices classes cannot be initialised.

Inline definition

Alternatively, the choices can be defined dynamically by creating new Choices object.

PAGE_STATUS = Choices('PAGE_STATUS', SUCCESS='Success', FAIL='Error')

The first name parameter of Choices constructor is optional and required only for better representation of the returned object.

Value accessors

You can access choices values using dot notation and with getattr().

value_created = PAGE_STATUS.CREATED
value_on_hold = getattr(PAGE_STATUS, 'ON_HOLD')

Values and value parameters

Choices.Value is a subclass of str and equals to its value. In addition to display parameter, other optional parameters can be specified in Choices.Value constructor (see class definition example).

print( PAGE_STATUS.CREATED )                # 'created'
print( PAGE_STATUS.ON_HOLD )                # 'custom_on_hold'
print( PAGE_STATUS.PENDING.display )        # 'Pending'
print( PAGE_STATUS.PENDING.help_text )      # 'This set status to pending'

PAGE_STATUS.ON_HOLD == 'custom_on_hold'     # True

Choices.Value is an immutable string class, which object cannot be modified after initialisation. Standard non-magic str methods are not supported in Choices.Value, in other cases its object behaves like a normal string, e.g. {'val1': 'something'}[CHOICES.VAL1] == 'something'.

Search in choices

Search in choices is performed by value.

'created' in PAGE_STATUS                    # True
'custom_on_hold' in PAGE_STATUS             # True
'on_hold' in PAGE_STATUS                    # False
value = PAGE_STATUS['custom_on_hold']       # Choices.Value
key, value = PAGE_STATUS.find('created')    # ('CREATED', Choices.Value)

Search in subsets

Subsets are used to group several values together (see class definition example) and search by a specific value.

'custom_on_hold' in PAGE_STATUS.VALID       # True
index = PAGE_STATUS.VALID.index('created')  # 0

Choices.Subset is a subclass of frozetset, which cannot be modified after initialisation. Unlike original Python sets, instances of Choices.Subset maintain the order of values.

Choices iteration

Choices class implements __iter__ magic method, hence choices are iterable that yield (value, display). Methods items(), keys() and values() can be used to return tuples of keys and values combinations.

for value, display in PAGE_STATUS:
    print( value, display )

for key, value in PAGE_STATUS.items():
    print( key, value, value.display )

for key in PAGE_STATUS.keys():
    print( key )

for value in PAGE_STATUS.values():
    print( value, value.display )

Additional displays() method is provided for choices and subsets to extract values display strings.

for display in PAGE_STATUS.displays():
    print( display )

for display in PAGE_STATUS.SUBSET.displays():
    print( display )

Django model fields

Better choices are not different to the original Django choices in terms of usage in models.

class Page(models.Model):
    status = models.CharField(choices=PAGE_STATUS, default=PAGE_STATUS.CREATED)

Better choices are fully supported by Django migrations.

Saving choices on models

Better choices are compatible with standard Django models manipulation.

page = Page.objects.get(pk=1)


Run python for testing.


Library is available under the MIT license. The included LICENSE file describes this in detail.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-better-choices, version 1.8
Filename, size File type Python version Upload date Hashes
Filename, size django_better_choices-1.8-py3-none-any.whl (7.3 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size django-better-choices-1.8.tar.gz (5.6 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page