Better choices library for Django web framework
Project description
Django Better Choices
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'
@classmethod
def get_help_text(cls):
return tuple(
value.help_text
for value in cls.values()
if hasattr(value, 'help_text')
)
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 ofChoices
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-magicstr
methods are not supported inChoices.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
Choices.Subset
is a subclass oftuple
, which is translated to inner choices class after definition. All internal or custom choices class methods or properties will be available in a subset class (see "Custom methods" section).
Extract subset
Subsets of choices can be dynamically extracted using a special extract()
method.
PAGE_STATUS.extract('CREATED', 'ON_HOLD') # ~= PAGE_STATUS.VALID
PAGE_STATUS.VALID.extract('ON_HOLD') # Choices('PAGE_STATUS.VALID.Subset', ON_HOLD)
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, value.__choice_entry__ )
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 )
Custom methods
All custom choices class methods or properties (non-values) will be available in all subsets.
PAGE_STATUS.get_help_text()
PAGE_STATUS.VALID.get_help_text()
PAGE.STATUS.extract('PENDING', 'ON_HOLD').get_help_text()
PAGE.STATUS.VALID.extract('ON_HOLD').get_help_text()
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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for django-better-choices-1.10.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9d8b16932857aee32b9c0b58b338905d7815a4757a1950a5a684a7dfea4553b6 |
|
MD5 | 6c63c26f3be24b650f24131e18e17ec7 |
|
BLAKE2b-256 | 7a1177e8cee432b82db2e438f0615166ff165aa9062949304ff07d921a8e4192 |
Hashes for django_better_choices-1.10-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c7e42c3bf08cd09ac1202812b9eda742620de6a3bdc4698cb77df9418dde1c67 |
|
MD5 | 312c5ad963d406bc60990483beb5d662 |
|
BLAKE2b-256 | 90c3ab5c8f5d7ea5bc1a1b08affdb19b06dbd347255ec838e839d3f73d5d95ee |