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.

Requirements

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

Install

pip install django-better-choices

Usage

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_review = PAGE_STATUS.INTERNAL_STATUS.REVIEW
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
PAGE_STATUS.CREATED == PAGE_STATUS.CREATED  # 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
PAGE_STATUS.CREATED 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)
page.status = PAGE_STATUS.PENDING
page.save()

Tests

Run python tests.py for testing.

License

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.

Source Distribution

django-better-choices-1.8.tar.gz (5.6 kB view hashes)

Uploaded Source

Built Distribution

django_better_choices-1.8-py3-none-any.whl (7.3 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page