API reference

appsettings.AppSettings class

appsettings.Setting and subclasses

class appsettings.Setting(name='', default=None, required=False, prefix='', call_default=True, transform_default=False, validators=())

Base setting class.

The setting’s name and prefix are used to specify the variable name to look for in the project settings. The default value is returned only if the variable is missing and the setting is not required. If the setting is missing and required, trying to access it will raise an AttributeError.

When accessing a setting’s value, the value is first fetched from environment or the project settings, then passed to a transform function that will return it modified (or not). By default, no transformation is applied.

The call_default parameter tells if we should try to call the given default value before returning it. This allows to give lambdas or callables as default values. The transform_default parameter tells if we should transform the default value as well through the transform method.

If the setting value is taken from environment, decode_environ method is called. By default it just decodes string as JSON and throws JSONDecodeError if the value is not a valid JSON. Some subclasses override and extend this method to be able to handle even other common values.

Class attributes:

default_validators (list of callables): Default set of validators for the setting.

check()

Validate the setting value.

Raises

ImproperlyConfigured – The setting doesn’t have a valid value.

decode_environ(value)

Return a decoded value.

By default, loads a JSON.

Parameters

value (string)

Returns

Any – the decoded value

property default_value

Property to return the default value.

If the default value is callable and call_default is True, return the result of default(). Else return default.

Returns

object – the default value.

property full_name

Property to return the full name of the setting.

Returns

str – upper prefix + upper name.

get_value()

Return the transformed raw or default value.

If the variable is missing from the project settings, and the setting is required, re-raise an AttributeError. If it is not required, return the (optionally transformed) default value.

Returns

object – the transformed raw value.

Raises

ImproperlyConfigured – The setting doesn’t have a valid value.

property raw_value

Property to return the variable defined in os.environ or in``django.conf.settings``.

Returns

object – the variable defined in os.environ or in django.conf.settings.

Raises

• AttributeError – if the variable is missing.

• KeyError – if the item is missing from nested setting.

run_validators(value)

Run the validators on the setting value.

transform(value)

Return a transformed value.

By default, no transformation is done.

Parameters

value (object)

Returns

object – the transformed value.

validate(value)

Run custom validation on the setting value.

By default, no additional validation is performed.

Raises

ValidationError – if the validation fails.

property value

Property to return the transformed raw or default value.

This property is a simple shortcut for get_value().

Returns

object – the transformed raw value.

Raises

ImproperlyConfigured – The setting doesn’t have a valid value.

class appsettings.BooleanSetting(name='', default=True, required=False, prefix='', call_default=True, transform_default=False, validators=())

Boolean setting.

decode_environ(value)

Return a decoded value.

Try to load a valid JSON. If JSONDecodeError is raised, chcecks for other common values (True, False, yes, no, 0, 1).

Parameters

value (string)

Returns

bool

class appsettings.IntegerSetting(name='', default=0, required=False, prefix='', call_default=True, transform_default=False, validators=(), minimum=None, maximum=None)

Integer setting.

class appsettings.PositiveIntegerSetting(name='', default=0, required=False, prefix='', call_default=True, transform_default=False, validators=(), maximum=None)

Positive integer setting.

class appsettings.FileSetting(name='', default=None, required=False, prefix='', call_default=True, transform_default=False, validators=(), mode=None)

File setting.

Value of this setting is a pathlib.Path instance.

transform(value)

Transform value to Path instance.

class appsettings.FloatSetting(name='', default=0.0, required=False, prefix='', call_default=True, transform_default=False, validators=(), minimum=None, maximum=None)

Float setting.

class appsettings.PositiveFloatSetting(name='', default=0.0, required=False, prefix='', call_default=True, transform_default=False, validators=(), maximum=None)

Positive float setting.

appsettings.IterableSetting and subclasses

class appsettings.IterableSetting(name='', default=None, required=False, prefix='', call_default=True, transform_default=False, validators=(), item_type=None, delimiter=':', min_length=None, max_length=None, empty=None)

Iterable setting.

decode_environ(value)

Decode JSON value or split value by a delimiter to a list, if JSONDecodeError is raised.

Default delimiter is a colon, can be changed via attribute delimiter.

Parameters

value (str)

Returns

Iterable

class appsettings.StringSetting(name='', default='', required=False, prefix='', call_default=True, transform_default=False, validators=(), min_length=None, max_length=None, empty=None)

String setting.

decode_environ(value)

Return a decoded value.

Try to load JSON or return pure string, if JSONDecodeError is raised.

Parameters

(string)

Returns

string

class appsettings.ListSetting(name='', default=<class 'list'>, **kwargs)

List setting.

decode_environ(value)

Decode JSON value or split value by a delimiter to a list, if JSONDecodeError is raised.

Default delimiter is a colon, can be changed via attribute delimiter.

Parameters

value (str)

Returns

list

class appsettings.SetSetting(name='', default=<class 'set'>, **kwargs)

Set setting.

decode_environ(value)

Decode JSON value or split value by a delimiter to a set, if JSONDecodeError is raised.

Default delimiter is a colon, can be changed via attribute delimiter.

Parameters

value (str)

Returns

set

class appsettings.TupleSetting(name='', default=<class 'tuple'>, **kwargs)

Tuple setting.

decode_environ(value)

Decode JSON value or split value by a delimiter to a tuple, if JSONDecodeError is raised.

Default delimiter is a colon, can be changed via attribute delimiter.

Parameters

value (str)

Returns

tuple

appsettings.DictSetting setting

class appsettings.DictSetting(name='', default=<class 'dict'>, required=False, prefix='', call_default=True, transform_default=False, validators=(), key_type=None, value_type=None, outer_delimiter=None, inner_delimiter='=', min_length=None, max_length=None, empty=None)

Dict setting.

decode_environ(value)

Decode JSON value or split value by delimiters to a dict, if JSONDecodeError is raised.

Default delimiter to distinguish single items is a whitespace sequence, items are then split by equal sign by default. Both delimiters can be changed via instance attributes inner_delimiter and outer_delimiter.

Parameters

value (str)

Raises

ValueError – not enough values to unpack

Returns

dict

appsettings.ObjectSetting setting

class appsettings.ObjectSetting(name='', default=None, required=False, prefix='', call_default=True, transform_default=False, validators=(), min_length=None, max_length=None, empty=None)

Object setting.

This setting allows to return an object given its Python path (a.b.c).

decode_environ(value)

Try to load JSON or return pure string, if JSONDecodeError is raised.

Parameters

(string)

Returns

string

transform(path)

Transform a path into an actual Python object.

The path can be arbitrary long. You can pass the path to a package, a module, a class, a function or a global variable, as deep as you want, as long as the deepest module is importable through importlib.import_module and each object is obtainable through the getattr method. Local objects will not work.

Parameters

path (str) – the dot-separated path of the object.

Returns

object – the imported module or obtained object.

appsettings.CallablePathSetting setting

class appsettings.CallablePathSetting(name='', default=None, required=False, prefix='', call_default=True, transform_default=False, validators=(), min_length=None, max_length=None, empty=None)

Callable path setting.

This setting value should be string containing a dotted path to a callable.

validate(value)

Check whether the value is path to a callable.

We disregard the raw value and use transformed value instead.

appsettings.NestedDictSetting setting

class appsettings.NestedDictSetting(settings, *args, **kwargs)

Nested dict setting.

Environment variables are not passed to inner settings.

check()

Validate the setting value.

Raises

• AttributeError – if the setting is missing and required.

• ValueError – (or other Exception) if the raw value is invalid.

get_value()

Return dictionary with values of subsettings.

Returns

dict – values of subsettings.

appsettings.NestedSetting setting

This setting is deprecated in favor of appsettings.NestedDictSetting.

class appsettings.NestedSetting(*args, **kwargs)

Deprecated alias for NestedDictSetting.

appsettings.NestedListSetting setting

class appsettings.NestedListSetting(inner_setting, *args, **kwargs)

Nested list setting.

Environment variables are not passed to inner settings.

check()

Check the nested list setting itself and all its items.

get_value()

Return the transformed raw or default value.

If the variable is missing from the project settings, and the setting is required, re-raise an AttributeError. If it is not required, return the (optionally transformed) default value.

Returns

object – the transformed raw value.

Raises

ImproperlyConfigured – The setting doesn’t have a valid value.

transform(value)

Transform each item in the list.