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.
Note
These classes are required to be used as attributes of Configuration
classes. See the main documentation for more information.
Overview#
Here is an example (from a settings.py file with a Configuration
subclass):
from configurations import Configuration, values
class Dev(Configuration):
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 Configuration, values
class Dev(Configuration):
DEBUG = values.BooleanValue(True)
DEBUG_PROPAGATE_EXCEPTIONS = values.BooleanValue(DEBUG)
See the list of built-in value classes for more information.
Environment variables#
To separate the site configuration from your application code you should use environment variables for configuration. 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 common use cases.
Default behavior#
For example, imagine you want to override the ROOT_URLCONF
setting on your
staging server to be able to debug a problem with your in-development code.
You’re using a web server that passes the environment variables from
the shell it was started from into your Django WSGI process.
Use the boolean environ
option of the Value
class (True
by
default) to tell django-configurations to look for an environment variable with
the same name as the specific Value
variable, only uppercased and
prefixed with DJANGO_
. E.g.:
from configurations import Configuration, values
class Stage(Configuration):
# ..
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 the web server simply specify that environment variable
(e.g. in your init script):
$ DJANGO_ROOT_URLCONF=mysite.debugging_urls gunicorn mysite.wsgi:application
If the environment variable can’t be found it’ll use the default
'mysite.urls'
.
Disabling environment variables#
To disable environment variables, specify the environ
parameter of the
Value
class. For example this would disable it for the TIME_ZONE
setting value:
from configurations import Configuration, values
class Dev(Configuration):
TIME_ZONE = values.Value('UTC', environ=False)
Custom environment variable names#
To support legacy systems, integrate with other parts of your software 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 base name of the environment variable it
looks for. For example this would enforce the name DJANGO_MYSITE_TZ
instead of using the name of the Value
instance.:
from configurations import Configuration, values
class Dev(Configuration):
TIME_ZONE = values.Value('UTC', environ_name='MYSITE_TZ')
Allow final value to be used outside the configuration context#
You may use the environ_name
parameter to allow a Value
to be
directly converted to its final value for use outside of the configuration
context:
>>> type(values.Value([]))
<class 'configurations.values.Value'>
>>> type(values.Value([], environ_name="FOOBAR"))
<class 'list'>
This can also be achieved when using environ=False
and providing a
default value.
Custom environment variable prefixes#
In case you 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
):
from configurations import Configuration, values
class Dev(Configuration):
TIME_ZONE = values.Value('UTC', environ_prefix='MYSITE')
The environ_prefix
parameter can also be None
to completely disable
the prefix.
Value
class#
- class Value(default[, environ=True, environ_name=None, environ_prefix='DJANGO', environ_required=False])[source]#
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 (str or None) – capitalized name of environment variable to look for
environ_prefix (str) – capitalized prefix to use when looking for environment variable
environ_required (bool) – whether or not the value is required to be set as an environment variable
The
default
parameter is effectively the value the setting has right now in yoursettings.py
.- setup(name)[source]#
- 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-configurations is supposed to use when loading the settings. It’ll be passed one parameter, the name of theValue
instance as defined in thesettings.py
. This is used for building the name of the environment variable.
- to_python(value)[source]#
- 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 used when theenviron
parameter of theValue
class is set toTrue
(the default) and an environment variable with the appropriate name was found.It will be used to handle the string based environment variables and returns the “ready” value of the setting.
Some
Value
subclasses also use it during initialization when the default value has a string-like format like an environment variable which needs to be converted into a Python data type.
Built-ins#
Type values#
- class BooleanValue[source]#
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[source]#
A
Value
subclass that handles integer values.MYSITE_CACHE_TIMEOUT = values.IntegerValue(3600)
- class PositiveIntegerValue[source]#
A
Value
subclass that handles positive integer values.New in version 2.1.
MYSITE_WORKER_POOL = values.PositiveIntegerValue(8)
- class FloatValue[source]#
A
Value
subclass that handles float values.MYSITE_TAX_RATE = values.FloatValue(11.9)
- class DecimalValue[source]#
A
Value
subclass that handles Decimal values.MYSITE_CONVERSION_RATE = values.DecimalValue(decimal.Decimal('4.56214'))
- class ListValue(default[, separator=', ', converter=None])[source]#
A
SequenceValue
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:
def check_monty_python(person): if not is_completely_different(person): error = '{0} is not a Monty Python member'.format(person) raise ValueError(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[source]#
A
SequenceValue
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 SingleNestedTupleValue(default[, seq_separator=';', separator=', ', converter=None])[source]#
A
SingleNestedSequenceValue
subclass that handles single nested tuple values, e.g.((a, b), (c, d))
.- Parameters:
seq_separator – the separator to split each tuple with
separator – the separator to split the inner tuple contents with
converter – the optional converter callable to apply for each inner tuple item
Useful for ADMINS, MANAGERS, and the like. For example:
ADMINS = SingleNestedTupleValue(( ('John', 'jcleese@site.com'), ('Eric', 'eidle@site.com'), ))
Override using environment variables like this:
DJANGO_ADMINS=Terry,tjones@site.com;Graham,gchapman@site.com
- class SingleNestedListValue(default[, seq_separator=';', separator=', ', converter=None])[source]#
A
SingleNestedSequenceValue
subclass that handles single nested list values, e.g.[[a, b], [c, d]]
.- Parameters:
seq_separator – the separator to split each list with
separator – the separator to split the inner list contents with
converter – the optional converter callable to apply for each inner list item
See the
SingleNestedTupleValue
examples above.
Validator values#
- class EmailValue[source]#
A
Value
subclass that validates the value using thedjango.core.validators.validate_email
validator.SUPPORT_EMAIL = values.EmailValue('support@mysite.com')
- class URLValue[source]#
A
Value
subclass that validates the value using thedjango.core.validators.URLValidator
validator.SUPPORT_URL = values.URLValue('https://support.mysite.com/')
- class IPValue[source]#
A
Value
subclass that validates the value using thedjango.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'])[source]#
A
Value
subclass that validates according a regular expression and uses thedjango.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'])[source]#
A
Value
subclass that normalizes the given path usingos.path.expanduser
and checks if it exists on the file system.Takes an optional
check_exists
parameter to disable the check withos.path.exists
.- Parameters:
check_exists – toggle the file system check
BASE_DIR = values.PathValue('/opt/mysite/') STATIC_ROOT = values.PathValue('/var/www/static', checks_exists=False)
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])[source]#
A
Value
subclass that uses the dj-database-url app to convert a database configuration value stored in theDATABASE_URL
environment variable into an appropriate setting value. It’s inspired by the Twelve-Factor methodology.By default this
Value
subclass looks for theDATABASE_URL
environment variable.Takes an optional
alias
parameter to define which database alias to use for theDATABASES
setting.- Parameters:
alias – which database alias to use
The other parameters have the following default values:
- Parameters:
environ –
True
environ_name –
DATABASE_URL
environ_prefix –
None
DATABASES = values.DatabaseURLValue('postgres://myuser@localhost/mydb')
- class CacheURLValue(default[, alias='default', environ=True, environ_name='CACHE_URL', environ_prefix=None])[source]#
A
Value
subclass that uses the django-cache-url app to convert a cache configuration value stored in theCACHE_URL
environment variable into an appropriate setting value. It’s inspired by the Twelve-Factor methodology.By default this
Value
subclass looks for theCACHE_URL
environment variable.Takes an optional
alias
parameter to define which database alias to use for theCACHES
setting.- Parameters:
alias – which cache alias to use
The other parameters have the following default values:
- Parameters:
environ –
True
environ_name –
CACHE_URL
environ_prefix –
None
CACHES = values.CacheURLValue('memcached://127.0.0.1:11211/')
- class EmailURLValue(default[, environ=True, environ_name='EMAIL_URL', environ_prefix=None])[source]#
A
Value
subclass that uses the dj-email-url app to convert an email configuration value stored in theEMAIL_URL
environment variable into the appropriate settings. It’s inspired by the Twelve-Factor methodology.By default this
Value
subclass looks for theEMAIL_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:
environ –
True
environ_name –
EMAIL_URL
environ_prefix –
None
EMAIL = values.EmailURLValue('console://')
- class SearchURLValue(default[, environ=True, environ_name='SEARCH_URL', environ_prefix=None])[source]#
New in version 0.8.
A
Value
subclass that uses the dj-search-url app to convert a search configuration value stored in theSEARCH_URL
environment variable into the appropriate settings for use with Haystack. It’s inspired by the Twelve-Factor methodology.By default this
Value
subclass looks for theSEARCH_URL
environment variable.Takes an optional
alias
parameter to define which search backend alias to use for theHAYSTACK_CONNECTIONS
setting.- Parameters:
alias – which cache alias to use
The other parameters have the following default values:
- Parameters:
environ –
True
environ_name –
SEARCH_URL
environ_prefix –
None
HAYSTACK_CONNECTIONS = values.SearchURLValue('elasticsearch://127.0.0.1:9200/my-index')
Other values#
- class BackendsValue[source]#
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 = 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[source]#
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. This usually resolves toDJANGO_SECRET_KEY
unless you have customized the environment variable names.- Raises:
ValueError
when given a default value
Changed in version 1.0: This value class has the
environ_required
parameter turned toTrue
.SECRET_KEY = values.SecretValue()
Value mixins#
- class CastingMixin[source]#
A mixin to be used with one of the
Value
subclasses that requires acaster
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 anexception
parameter can be set to a single or a tuple of exception classes that are required to be handled during the casting.
- class ValidationMixin[source]#
A mixin to be used with one of the
Value
subclasses that requires avalidator
class attribute of one of the following types: The validator should raise Django’sValidationError
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[source]#
A mixin to be used with one of the
Value
subclasses that enables the return value of theto_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 manyEMAIL_*
settings.