oblalex / candv

Create complex enum-like constants in Python

candv: Constants & Values

candv allows to create complex enum-like constants.

In contrast to other methods of defining constants, candv helps to organize and to document classes of constants.

This is done by providing iteration and lookup facilities for containers of constants.

Additionally, candv provides an ability to attach human-readable names, descriptions, arbitrary values, and methods to constants.

Inspired by Constants from Twisted and Form Fields from Django.

Installation

Available as a PyPI package:

pip install candv

Brief overview

The most basic definition of constants:

from candv import Constants
from candv import SimpleConstant

class TEAM(Constants):
  RED  = SimpleConstant()
  BLUE = SimpleConstant()

And usage:

TEAM.RED                 # <constant 'TEAM.RED'>
TEAM['RED']              # <constant 'TEAM.RED'>
TEAM.get('RED')          # <constant 'TEAM.RED'>
TEAM.get('GREEN')        # None
TEAM.RED.name            # 'RED'
TEAM.RED.full_name       # 'TEAM.RED'
TEAM.RED.to_primitive()  # {'name': 'RED'}
TEAM.RED.container       # <constants container 'TEAM'>

TEAM                     # <constants container 'TEAM'>
TEAM.name                # 'TEAM'
TEAM.full_name           # 'TEAM'
len(TEAM)                # 2
TEAM.has_name('RED')     # True

TEAM.names()             # ['RED', 'BLUE']
TEAM.iternames()         # <odict_iterator object at 0x7f451013e0e0>

TEAM.constants()         # [<constant 'TEAM.RED'>, <constant 'TEAM.BLUE'>]
TEAM.iterconstants()     # <odict_iterator object at 0x7f45100f3450>

TEAM.items()             # [('RED', <constant 'TEAM.RED'>), ('BLUE', <constant 'TEAM.BLUE'>)]
TEAM.iteritems()         # <odict_iterator object at 0x7f451013bdb0>

TEAM.to_primitive()      # {'name': 'TEAM', 'items': [{'name': 'RED'}, {'name': 'BLUE'}]}

Using with values:

from candv import Values
from candv import ValueConstant

class TEAM(Values):
  RED  = ValueConstant(1)
  BLUE = ValueConstant(2)


TEAM.values()            # [1, 2]
TEAM.itervalues()        # <map object at 0x7f450ffdb1c0>

TEAM.get_by_value(1)     # <constant 'TEAM.RED'>
TEAM.filter_by_value(1)  # [<constant 'TEAM.RED'>]

TEAM.RED.value           # 1
TEAM.RED.to_primitive()  # {'name': 'RED', 'value': 1}

Using with human-readable names:

from candv import Constants
from candv import VerboseConstant

class Countries(Constants):
  au = VerboseConstant("Australia")
  uk = VerboseConstant("United Kingdom")
  us = VerboseConstant("United States")


Countries.au.name            # 'au'
Countries.au.verbose_name    # 'Australia'
Countries.au.help_text       # None
Countries.au.to_primitive()  # {'name': 'au', 'verbose_name': 'Australia', 'help_text': None}

With values and names:

from candv import Values
from candv import VerboseValueConstant

class SkillLevel(Values):
  rki = VerboseValueConstant(0, "rookie")
  avg = VerboseValueConstant(1, "average")
  vtn = VerboseValueConstant(2, "veteran")
  ace = VerboseValueConstant(3, "ace")


SkillLevel.avg.value           #  1
SkillLevel.avg.name            # 'avg'
SkillLevel.avg.full_name       # 'SkillLevel.avg'
SkillLevel.avg.verbose_name    # 'average'
SkillLevel.avg.help_text       # None
SkillLevel.avg.to_primitive()  # {'name': 'avg', 'value': 1, 'verbose_name': 'average', 'help_text': None}

Plays well with verboselib or, say, Django translation strings:

from candv import Constants
from candv import VerboseConstant

from verboselib import Translations


translations = Translations(
  domain="the_app",
  locale_dir_path="locale",
)
_ = translations.gettext_lazy


class UnitType(Constants):
  aircraft = VerboseConstant(_("aircraft"))
  ship     = VerboseConstant(_("ship"))
  train    = VerboseConstant(_("train"))
  vehicle  = VerboseConstant(_("vehicle"))

Supports custom methods:

from candv import Constants
from candv import SimpleConstant

class SupportedLanguages(Constants):
  en = SimpleConstant()
  ru = SimpleConstant()

  @classmethod
  def get_default(cls):
    return cls.en


SupportedLanguages.get_default()  # <constant 'SupportedLanguages.en'>

And custom types of constants:

from candv import Constants
from candv import SimpleConstant
from candv import with_constant_class

class MissionStatus(SimpleConstant):
  ...

class MissionStatuses(with_constant_class(MissionStatus), Constants):
  not_loaded = MissionStatus()
  loaded     = MissionStatus()
  playing    = MissionStatus()

It's also possible to define hierarchies:

from candv import Constants
from candv import SimpleConstant

class STATUS(Constants):
  SUCCESS = SimpleConstant()
  ERROR   = SimpleConstant().to_group(Constants,

    INVALID   = SimpleConstant(),
    NOT_FOUND = SimpleConstant(),
    INTERNAL  = SimpleConstant(),
  )


STATUS.names()                   # ['SUCCESS', 'ERROR']
STATUS.ERROR                     # <constants group 'STATUS.ERROR'>
STATUS.ERROR.full_name           # 'STATUS.ERROR'
STATUS.ERROR.INTERNAL            # <constant 'STATUS.ERROR.INTERNAL'>
STATUS.ERROR.INTERNAL.full_name  # 'STATUS.ERROR.INTERNAL'
STATUS.ERROR.names()             # ['INVALID', 'NOT_FOUND', 'INTERNAL']

More info

Visit the docs for full information.

See django-candv-choices for using as choices in django.

See django-rf-candv-choices for using as choices in django-rest-framework.

candv's Issues

Dynamic values

Provide ability to set dynamic values for constants using some storage (e.g. integrate with Redis, django-constance or whatsoever).

Initialization of non-'constant_class' constants

Constants which are not instances of container's constant_class are not initialized. E.g.

>>> from candv import Values, SimpleConstant
>>> class FOO(Values):
...     BAR = SimpleConstant()
...     
... 
>>> FOO.BAR

>>> FOO.BAR.name
>>> repr(FOO.BAR)
''

Despite FOO.BAR is invalid, it still needs to be initialized.

'with_constant_class' mixin factory

Add ability to specify class of constants via dynamic mixin, e.g. this:

class FOO(Constants):
    constant_class = FOO_CONSTANT

    ONE = FOO_CONSTANT()
    TWO = FOO_CONSTANT()

with decorator will look like:

class FOO(with_constant_class(FOO_CONSTANT), Constants):    
    ONE = FOO_CONSTANT()
    TWO = FOO_CONSTANT()

Improve or reimplement support of groups

Constants must be equal no matter how they are loaded

Assume you have the following package structure:

.
└── x
    ├── __init__.py
    └── y
        ├── __init__.py
        └── constants.py

where x.y.constants.py contains the following:

# -*- coding: utf-8 -*-

from candv import Constants, SimpleConstant


class FOO_TYPES(Constants):
    PRIMARY = SimpleConstant()
    SECONDARY = SimpleConstant()

If x is in Python's path, and you import constants from x.y and simply from y, then their module will differ and comparison of constants will fail:

>>> import sys
>>> sys.path.insert(0, './x')
>>> from x.y.constants import FOO_TYPES as X_TYPES
>>> from y.constants import FOO_TYPES as Y_TYPES
>>> X_TYPES.__module__
'x.y.constants'
>>> Y_TYPES.__module__
'y.constants'
>>> X_TYPES.PRIMARY
<constant 'FOO_TYPES.PRIMARY'>
>>> Y_TYPES.PRIMARY
<constant 'FOO_TYPES.PRIMARY'>
>>> X_TYPES.PRIMARY == Y_TYPES.PRIMARY
False

Solution: constants base must implement own __hash__ and __eq__ magic methods, whose result will be based on full name of constant.

Default value for getters

Add support of default values for such methods as get_by_name, get_by_value, etc.

Improve/add reprresentation of objects

Add ability to get:

• name of container (alias for __name__)
• full name of container
• __repr__ of a container
• __repr__ of a group
• full name of a constant, which will include name of container

Provide support for constants comparison

Public container reference

Make constant's reference to own container public instead of protected.

Provide support for serialization