Values

New in version 0.4.

django-configurations allows you to optionally reduce the amount of validation and setup code in your settings.py by using Value classes. They have the ability to handle values from the process environment of your software (os.environ) and work well in projects that follow the Twelve-Factor methodology.

Overview

Here is an example (from a settings.py):

from configurations import values

DEBUG = values.BooleanValue(True)

As you can see all you have to do is to wrap your settings value in a call to one of the included values classes. When Django’s process starts up it will automatically make sure the passed-in value validates correctly – in the above case checks if the value is really a boolean.

You can safely use other Value instances as the default setting value:

from configurations import values

DEBUG = values.BooleanValue(True)
TEMPLATE_DEBUG = values.BooleanValue(DEBUG)

See the list of built-in value classes for more information.

Environment variables

To separate configuration from your application you should use environment variables to override settings values if needed. Unfortunately environment variables are string based so they are not easily mapped to the Python based settings system Django uses.

Luckily django-configurations’ Value subclasses have the ability to handle environment variables for the most common use cases.

Default behavior

For example, imagine you’d like to override the ROOT_URLCONF setting on your staging server to be able to debug a problem with your in-development code. You’re also using a web server that passes the environment variables from the shell it was started from into your Django WSGI process.

Each Value class instance has an environ option, that when set to True (default) django-configurations will look for an uppercase environment variable named like the Value instance’s name, prefixed with DJANGO_. So imagine the following example:

from configurations import values

# ..
ROOT_URLCONF = values.Value('mysite.urls')

django-configurations will try to read the DJANGO_ROOT_URLCONF environment variable when deciding which value the ROOT_URLCONF setting should have.

When you run your web server simply specify that environment variable (e.g. in your init script):

DJANGO_ROOT_URLCONF=mysite.debugging_urls gunicorn mysite.wsgi:application

Disabling environment variables

To disable django-configurations’ automatic use of environment variables, you can specify the environ parameter of the Value class. For example this would disable it for the TIME_ZONE setting value:

TIME_ZONE = values.Value('UTC', environ=False)

Custom environment variable names

To support legacy systems, integrate with other parts of your sofware stack or simply better match your taste in naming public configuration variables, django-configurations allows you to use the environ_name parameter of the Value class to change the name of the environment variable it looks for. For example this would enforce a specific environment variable name instead of using the name of the Value instance.:

TIME_ZONE = values.Value('UTC', environ_name='MYSITE_TZ')

Custom environment variable prefixes

In case you just want to change the default environment variable name prefix of DJANGO to something to your likening, use the environ_prefix parameter of the Value instance. Here it’ll look for the MYSITE_TIME_ZONE environment variable (instead of DJANGO_TIME_ZONE):

TIME_ZONE = values.Value('UTC', environ_prefix='MYSITE')

Value class

class Value(default[, environ=True, environ_name=None, environ_prefix='DJANGO'])

The Value class takes one required and several optional parameters.

Parameters:
  • default – the default value of the setting
  • environ (bool) – toggle for environment use
  • environ_name (capitalized string or None) – name of environment variable to look for
  • environ_prefix (capitalized string) – prefix to use when looking for environment variable

The default parameter is effectively the value the setting has right now in your settings.py.

setup(name)
Parameters:name – the name of the setting
Returns:setting value

The setup method is called during startup of the Django process and implements the ability to check the environment variable. Its purpose is to return a value django-configrations is supposed to use when loading the settings. It’ll be passed one parameter, the name of the Value instance as defined in the settings.py. This is used for building the name of the environment variable.

to_python(value)
Parameters:value – the value of the setting as found in the process environment (os.environ)
Returns:validated and “ready” setting value if found in process environment

The to_python method is only used when the environ parameter of the Value class is set to True (the default) and an environment variable with the appropriate name was found. It will be used to handle the string based environment variable values and returns the “ready” value to be returned by the setup method.

Built-ins

Type values

class BooleanValue

A Value subclass that checks and returns boolean values. Possible values for environment variables are:

  • True values: 'yes', 'y', 'true', '1'
  • False values: 'no', 'n', 'false', '0', '' (empty string)
DEBUG = values.BooleanValue(True)
class IntegerValue

A Value subclass that handles integer values.

MYSITE_CACHE_TIMEOUT = values.BooleanValue(3600)
class FloatValue

A Value subclass that handles float values.

MYSITE_TAX_RATE = values.FloatValue(11.9)
class DecimalValue

A Value subclass that handles Decimal values.

MYSITE_CONVERSION_RATE = values.DecimalValue(decimal.Decimal('4.56214'))
class ListValue(default[, separator=', ', converter=None])

A Value subclass that handles list values.

Parameters:
  • separator – the separator to split environment variables with
  • converter – the optional converter callable to apply for each list item

Simple example:

ALLOWED_HOSTS = ListValue(['mysite.com', 'mysite.biz'])

Use a custom converter to check for the given variables:

from django.core.exceptions import ImproperlyConfigured

def check_monty_python(person):
    if not is_completely_different(person):
        error = '{0} is not a Monty Python member'.format(person)
        raise ImproperlyConfigured(error)
    return person

MONTY_PYTHONS = ListValue(['John Cleese', 'Eric Idle'],
                          converter=check_monty_python)

You can override this list with an environment variable like this:

DJANGO_MONTY_PYTHONS="Terry Jones,Graham Chapman" gunicorn mysite.wsgi:application

Use a custom separator:

EMERGENCY_EMAILS = ListValue(['admin@mysite.net'], separator=';')

And override it:

DJANGO_EMERGENCY_EMAILS="admin@mysite.net;manager@mysite.org;support@mysite.com" gunicorn mysite.wsgi:application
class TupleValue

A Value subclass that handles tuple values.

Parameters:
  • separator – the separator to split environment variables with
  • converter – the optional converter callable to apply for each tuple item

See the ListValue examples above.

class SetValue

A Value subclass that handles set values.

Parameters:
  • separator – the separator to split environment variables with
  • converter – the optional converter callable to apply for each set item

See the ListValue examples above.

class DictValue

Validator values

class EmailValue

A Value subclass that validates the value using the django.core.validators.validate_email validator.

SUPPORT_EMAIL = values.EmailValue('support@mysite.com')
class URLValue

A Value subclass that validates the value using the django.core.validators.URLValidator validator.

SUPPORT_URL = values.URLValue('https://support.mysite.com/')
class IPValue

A Value subclass that validates the value using the django.core.validators.validate_ipv46_address validator.

LOADBALANCER_IP = values.IPValue('127.0.0.1')
class RegexValue(default, regex[, environ=True, environ_name=None, environ_prefix='DJANGO'])

A Value subclass that validates according a regular expression and uses the django.core.validators.RegexValidator.

Parameters:regex – the regular expression
DEFAULT_SKU = values.RegexValue('000-000-00', regex=r'\d{3}-\d{3}-\d{2}')
class PathValue(default[, check_exists=True, environ=True, environ_name=None, environ_prefix='DJANGO'])

A Value subclass that normalizes the given path using os.path.expanduser and validates if it exists on the file system.

Takes an optional check_exists parameter to disable the check with os.path.exists.

Parameters:check_exists – toggle the file system check
BASE_DIR = values.PathValue('/opt/mysite/')

URL-based values

Note

The following URL-based Value subclasses are inspired by the Twelve-Factor methodology and use environment variable names that are already established by that methodology, e.g. 'DATABASE_URL'.

Each of these classes require external libraries to be installed, e.g. the DatabaseURLValue class depends on the package dj-database-url. See the specific class documentation below for which package is needed.

class DatabaseURLValue(default[, alias='default', environ=True, environ_name='DATABASE_URL', environ_prefix=None])

A Value subclass that uses the dj-database-url app to convert a database configuration value stored in the DATABASE_URL environment variable into an appropriate setting value. It’s inspired by the Twelve-Factor methodology.

By default this Value subclass looks for the DATABASE_URL environment variable.

Takes an optional alias parameter to define which database alias to use for the DATABASES setting.

Parameters:alias – which database alias to use

The other parameters have the following default values:

Parameters:
  • environTrue
  • environ_nameDATABASE_URL
  • environ_prefixNone
DATABASES = values.DatabaseURLValue('postgres://myuser@localhost/mydb')
class CacheURLValue(default[, alias='default', environ=True, environ_name='CACHE_URL', environ_prefix=None])

A Value subclass that uses the django-cache-url app to convert a cache configuration value stored in the CACHE_URL environment variable into an appropriate setting value. It’s inspired by the Twelve-Factor methodology.

By default this Value subclass looks for the CACHE_URL environment variable.

Takes an optional alias parameter to define which database alias to use for the CACHES setting.

Parameters:alias – which cache alias to use

The other parameters have the following default values:

Parameters:
  • environTrue
  • environ_nameCACHE_URL
  • environ_prefixNone
CACHES = values.CacheURLValue('memcached://127.0.0.1:11211/')
class EmailURLValue(default[, environ=True, environ_name='EMAIL_URL', environ_prefix=None])

A Value subclass that uses the dj-email-url app to convert an email configuration value stored in the EMAIL_URL environment variable into the appropriate settings. It’s inspired by the Twelve-Factor methodology.

By default this Value subclass looks for the EMAIL_URL environment variable.

Note

This is a special value since email settings are divided into many different settings variables. dj-email-url supports all options though and simply returns a nested dictionary of settings instead of just one setting.

The parameters have the following default values:

Parameters:
  • environTrue
  • environ_nameEMAIL_URL
  • environ_prefixNone
EMAIL = values.EmailURLValue('console://')

Other values

class BackendsValue

A ListValue subclass that validates the given list of dotted import paths by trying to import them. In other words, this checks if the backends exist.

MIDDLEWARE_CLASSES = values.BackendsValue([
    'django.middleware.common.CommonMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
])
class SecretValue

A Value subclass that doesn’t allow setting a default value during instantiation and force-enables the use of an environment variable to reduce the risk of accidentally storing secret values in the settings file.

Raises :ImproperlyConfigured when given a default value
SECRET_KEY = values.SecretValue()

Value mixins

class CastingMixin

A mixin to be used with one of the Value subclasses that requires a caster class attribute of one of the following types:

  • dotted import path, e.g. 'mysite.utils.custom_caster'
  • a callable, e.g. int

Example:

class TemparatureValue(CastingMixin, Value):
    caster = 'mysite.temperature.fahrenheit_to_celcius'

Optionally it can take a message class attribute as the error message to be shown if the casting fails. Additionally an exception parameter can be set to a single or a tuple of exception classes that are required to be handled during the casting.

class ValidationMixin

A mixin to be used with one of the Value subclasses that requires a validator class attribute of one of the following types: The validator should raise Django’s ValidationError to indicate a failed validation attempt.

  • dotted import path, e.g. 'mysite.validators.custom_validator'
  • a callable, e.g. bool

Example:

class TemparatureValue(ValidationMixin, Value):
    validator = 'mysite.temperature.is_valid_temparature'

Optionally it can take a message class attribute as the error message to be shown if the validation fails.

class MultipleMixin

A mixin to be used with one of the Value subclasses that enables the return value of the to_python to be interpreted as a dictionary of settings values to be set at once, instead of using the return value to just set one setting.

A good example for this mixin is the EmailURLValue value which requires setting many EMAIL_* settings.