Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

Python's Enum with extra powers to play nice with labels and choices fields

Project Description

Choices Enum

Python’s Enum with extra powers to play nice with labels and choices fields.


Install choicesenum using pip:

$ pip install choicesenum


  • An ChoicesEnum that can be used to create constant groups.
  • ChoicesEnum can define labels to be used in choices fields.
  • Django fields included: EnumCharField and EnumIntegerField.
  • Support (tested) for Python 2.7, 3.4, 3.5 and 3.6.
  • Support (tested) for Django 1.6.1 (with south), 1.7, 1.8, 1.9, 1.10 and 1.11.

Usage examples

Example with HttpStatuses:

class HttpStatuses(ChoicesEnum):
    OK = 200
    BAD_REQUEST = 400
    FORBIDDEN = 403

All Enum types can be compared against their values:

assert HttpStatuses.OK == 200
assert HttpStatuses.BAD_REQUEST == 400
assert HttpStatuses.UNAUTHORIZED == 401
assert HttpStatuses.FORBIDDEN == 403

status_code = HttpStatuses.OK
assert 200 <= status_code <= 300

All Enum types have by default a display derived from the enum identifier:

assert HttpStatuses.OK.display == 'Ok'
assert HttpStatuses.BAD_REQUEST.display == 'Bad request'
assert HttpStatuses.UNAUTHORIZED.display == 'Unauthorized'
assert HttpStatuses.FORBIDDEN.display == 'Forbidden'

You can easily define your own custom display for an Enum item using a tuple:

class HttpStatuses(ChoicesEnum):
    OK = 200, 'Everything is fine'
    BAD_REQUEST = 400, 'You did a mistake'
    UNAUTHORIZED = 401, 'I know your IP'
    FORBIDDEN = 403

assert HttpStatuses.OK.display == 'Everything is fine'
assert HttpStatuses.BAD_REQUEST.display == 'You did a mistake'
assert HttpStatuses.UNAUTHORIZED.display == 'I know your IP'
assert HttpStatuses.FORBIDDEN.display == 'Forbidden'

You can declare custom properties and methods:

class HttpStatuses(ChoicesEnum):
    OK = 200, 'Everything is fine'
    BAD_REQUEST = 400, 'You did a mistake'
    UNAUTHORIZED = 401, 'I know your IP'
    FORBIDDEN = 403

    def is_error(self):
        return self >= self.BAD_REQUEST

assert HttpStatuses.OK.is_error is False
assert HttpStatuses.BAD_REQUEST.is_error is True
assert HttpStatuses.UNAUTHORIZED.is_error is True

Example with Colors:

from choicesenum import ChoicesEnum

class Colors(ChoicesEnum):
    # For fixed order in  py2.7, py3.4+ are ordered by default
    _order_ = 'RED GREEN BLUE'

    RED = '#f00', 'Vermelho'
    GREEN = '#0f0', 'Verde'
    BLUE = '#00f', 'Azul'

assert Colors.RED == '#f00'
assert Colors.GREEN == '#0f0'
assert Colors.BLUE == '#00f'

assert Colors.RED.display == 'Vermelho'
assert Colors.GREEN.display == 'Verde'
assert Colors.BLUE.display == 'Azul'

Use .choices() method to receive a list of tuples (item, display):

# choices
assert list(Colors.choices()) == [
    ('#f00', 'Vermelho'),
    ('#0f0', 'Verde'),
    ('#00f', 'Azul'),

For each enum item, a dynamic property is_<enum_item> is generated to allow quick boolean checks:

color = Colors.RED
assert color.is_red
assert not color.is_blue
assert not color.is_green

if color.is_red:
    print 'Is red!'

The enum item can be used whenever the value is needed:

assert u'Currrent color is {c} ({c.display})'.format(c=color) ==\
       u'Currrent color is #f00 (Vermelho)'

Usage with the custom Django fields:

from django.db import models
from choicesenum.django.fields import EnumCharField

class ColorModel(models.Model):
    color = EnumCharField(

instance = ColorModel()
assert instance.color ==  Colors.GREEN
assert instance.color.is_green is True
assert instance.color.value == Colors.GREEN.value == '#0f0'
assert instance.color.display == Colors.GREEN.display

instance.color = '#f00'
assert instance.color == '#f00'
assert instance.color.value == '#f00'
assert instance.color.display == 'Vermelho'

Is guaranteed that the field value is always a ChoicesEnum item. Pay attention that the field will only accept valid values for the Enum in use, so if your field allow null, your enum should also:

from django.db import models
from choicesenum import ChoicesEnum
from choicesenum.django.fields import EnumIntegerField

class UserStatus(ChoicesEnum):
    UNDEFINED = None
    PENDING = 1
    ACTIVE = 2
    INACTIVE = 3
    DELETED = 4

class User(models.Model):
    status = EnumIntegerField(enum=UserStatus, null=True, )

instance = User()
assert instance.status.is_undefined is True
assert instance.status.value is None
assert instance.status == UserStatus.UNDEFINED
assert instance.status.display == 'Undefined'

# again...
instance.status = None
assert instance.status.is_undefined is True

Usage with Graphene Enums:

UserStatusEnum = graphene.Enum.from_enum(UserStatus)


0.2.0 (2017-09-11)

  • ChoicesEnum items are comparable by their values (==, !=, >, >=, <, <=) (thanks @jodal).
  • +``ChoicesEnum.values``: Returns all the Enum’s raw values (eq: [x.value for x in Enum]).

0.1.7 (2017-09-10)

  • Fix: ChoicesEnum is now hashable (thanks @jodal).

0.1.6 (2017-09-08)

  • Fix: Proxy __len__ calls to the inner enum value.

0.1.5 (2017-09-05)

  • +ChoicesEnum.description: Alias for label, allow enum descriptors to be used by Graphene.

0.1.4 (2017-08-28)

  • Fix South migrations for Django 1.6.
  • ChoicesEnum repr can be used to reconstruct an instance (item == eval(repr(item))).

0.1.3 (2017-08-28)

  • Fix sdist not including sub-modules (django contrib).

0.1.2 (2017-08-27)

  • README fixes and improvements.

0.1.0 (2017-08-27)

  • First release on PyPI.
Release History

Release History

This version
History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


History Node


Download Files

Download Files

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

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
choicesenum-0.2.0-py2.py3-none-any.whl (10.2 kB) Copy SHA256 Checksum SHA256 py2.py3 Wheel Sep 11, 2017
choicesenum-0.2.0.tar.gz (21.8 kB) Copy SHA256 Checksum SHA256 Source Sep 11, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting