API reference

appsettings.AppSettings class

class appsettings.AppSettings

Bases: object

Base class for application settings.

Only use this class as a parent class for inheritance. If you try to access settings directly in AppSettings, it will raise a RecursionError. Some protections have been added to prevent you from instantiating this very class, or to return immediately when running AppSettings.check(), but trying to access attributes on the class is not yet prevented.

__getattr__(item)

Return a setting value.

The caching is done here. If the setting exists, and if it’s variable name is in the cache dictionary, return the cached value. If there is no cached value, get the setting value with setting.get_value(), cache it, and return it.

Parameters:item (str) – the name of the setting variable (not the setting’s name). Returns:object – a setting value. Raises:AttributeError if the setting does not exist.

__init__()

Initialization method.

The invalidate_cache and manage_environ_invalidation methods will be connected to the Django setting_changed signal in this method, with the dispatch UIDs being method initials and the id of this very object (id(self)).

__weakref__

list of weak references to the object (if defined)

classmethod check()

Class method to check every settings.

Will raise an ImproperlyConfigured exception with explanation.

invalidate_cache(**kwargs)

Invalidate cache. Run when receive setting_changed signal.

manage_environ_invalidation(*, setting, enter, **kwargs)

Manage keys and values in os.environ on setting change.

Environ values take precedence over django.conf values by default. But when we override a setting, we want to take the django.conf value and therefore we need to remove corresponding key from the os.environ. To be able to restore the original value later, we add a prefix (OS_ENVIRON_OVERRIDE_PREFIX) to the key and then just remove the prefix.

appsettings.Setting and subclasses

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

Bases: object

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.

__init__(name='', default=None, required=False, prefix='', call_default=True, transform_default=False, validators=())

Initialization method.

Parameters:

• name (str) – the name of the setting.
• default (object) – default value given to the setting.
• required (bool) – whether the setting is required or not.
• prefix (str) – the setting’s prefix (overrides AppSettings.Meta prefix).
• call_default (bool) – whether to call the default (if callable).
• transform_default (bool) – whether to transform the default value.
• validators (list of callables) – list of additional validators to use.

__weakref__

list of weak references to the object (if defined)

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

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.

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.

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.

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=())

Bases: appsettings.settings.Setting

Boolean setting.

__init__(name='', default=True, required=False, prefix='', call_default=True, transform_default=False, validators=())

Initialization method.

Parameters:

• name (str) – the name of the setting.
• default (bool) – default value given to the setting.
• required (bool) – whether the setting is required or not.
• prefix (str) – the setting’s prefix (overrides AppSettings.Meta prefix).
• call_default (bool) – whether to call the default (if callable).
• transform_default (bool) – whether to transform the default value.
• validators (list of callables) – list of additional validators to use.

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)

Bases: appsettings.settings.Setting

Integer setting.

__init__(name='', default=0, required=False, prefix='', call_default=True, transform_default=False, validators=(), minimum=None, maximum=None)

Initialization method.

Parameters:

• name (str) – the name of the setting.
• default (int) – default value given to the setting.
• required (bool) – whether the setting is required or not.
• prefix (str) – the setting’s prefix (overrides AppSettings.Meta prefix).
• call_default (bool) – whether to call the default (if callable).
• transform_default (bool) – whether to transform the default value.
• validators (list of callables) – list of additional validators to use.
• minimum (int) – a minimum value (included).
• maximum (int) – a maximum value (included).

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

Bases: appsettings.settings.IntegerSetting

Positive integer setting.

__init__(name='', default=0, required=False, prefix='', call_default=True, transform_default=False, validators=(), maximum=None)

Initialization method.

Parameters:

• name (str) – the name of the setting.
• default (int) – default value given to the setting.
• required (bool) – whether the setting is required or not.
• prefix (str) – the setting’s prefix (overrides AppSettings.Meta prefix).
• call_default (bool) – whether to call the default (if callable).
• transform_default (bool) – whether to transform the default value.
• validators (list of callables) – list of additional validators to use.
• maximum (int) – a maximum value (included).

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

Bases: appsettings.settings.Setting

File setting.

Value of this setting is a pathlib.Path instance.

__init__(name='', default=None, required=False, prefix='', call_default=True, transform_default=False, validators=(), mode=None)

Initialization method.

Note that attribute mode is used in FileValidator. For more information check its documentation.

Parameters:

• name (str) – the name of the setting.
• default (object) – default value given to the setting.
• required (bool) – whether the setting is required or not.
• prefix (str) – the setting’s prefix (overrides AppSettings.Meta prefix).
• call_default (bool) – whether to call the default (if callable).
• transform_default (bool) – whether to transform the default value.
• validators (list of callables) – list of additional validators to use.
• mode (optional int) – Required permission for the file. None means no validation (f.e. file does not exist yet), other values might consist of inclusive OR between F_OK, R_OK, W_OK and X_OK constants. When checking read, write or execute permission, file existence (F_OK) is implicitly required. For more information check os.access documentation (https://docs.python.org/3/library/os.html#os.access).

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)

Bases: appsettings.settings.IntegerSetting

Float setting.

__init__(name='', default=0.0, required=False, prefix='', call_default=True, transform_default=False, validators=(), minimum=None, maximum=None)

Initialization method.

Parameters:

• name (str) – the name of the setting.
• default (float) – default value given to the setting.
• required (bool) – whether the setting is required or not.
• prefix (str) – the setting’s prefix (overrides AppSettings.Meta prefix).
• call_default (bool) – whether to call the default (if callable).
• transform_default (bool) – whether to transform the default value.
• validators (list of callables) – list of additional validators to use.
• minimum (int) – a minimum value (included).
• maximum (int) – a maximum value (included).

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

Bases: appsettings.settings.FloatSetting

Positive float setting.

__init__(name='', default=0.0, required=False, prefix='', call_default=True, transform_default=False, validators=(), maximum=None)

Initialization method.

Parameters:

• name (str) – the name of the setting.
• default (float) – default value given to the setting.
• required (bool) – whether the setting is required or not.
• prefix (str) – the setting’s prefix (overrides AppSettings.Meta prefix).
• call_default (bool) – whether to call the default (if callable).
• transform_default (bool) – whether to transform the default value.
• validators (list of callables) – list of additional validators to use.
• maximum (int) – a maximum value (included).

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)

Bases: appsettings.settings.Setting

Iterable setting.

__init__(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)

Initialization method.

Parameters:

• name (str) – the name of the setting.
• default (iterable) – default value given to the setting.
• required (bool) – whether the setting is required or not.
• prefix (str) – the setting’s prefix (overrides AppSettings.Meta prefix).
• call_default (bool) – whether to call the default (if callable).
• transform_default (bool) – whether to transform the default value.
• validators (list of callables) – list of additional validators to use.
• item_type (type) – the type of the items inside the iterable.
• delimiter (str) – value used to split a string into separated parts
• min_length (int) – minimum length of the iterable (included).
• max_length (int) – maximum length of the iterable (included).
• empty (bool) – whether empty iterable is allowed. Deprecated in favor of min_length.

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)

Bases: appsettings.settings.Setting

String setting.

__init__(name='', default='', required=False, prefix='', call_default=True, transform_default=False, validators=(), min_length=None, max_length=None, empty=None)

Initialization method.

Parameters:

• name (str) – the name of the setting.
• default (str) – default value given to the setting.
• required (bool) – whether the setting is required or not.
• prefix (str) – the setting’s prefix (overrides AppSettings.Meta prefix).
• call_default (bool) – whether to call the default (if callable).
• transform_default (bool) – whether to transform the default value.
• validators (list of callables) – list of additional validators to use.
• min_length (int) – minimum length of the iterable (included).
• max_length (int) – maximum length of the iterable (included).
• empty (bool) – whether empty iterable is allowed. Deprecated in favor of min_length.

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)

Bases: appsettings.settings.IterableSetting

List setting.

__init__(name='', default=<class 'list'>, **kwargs)

Initialization method.

Parameters:

• name (str) – the name of the setting.
• default (list) – default value given to the setting.
• required (bool) – whether the setting is required or not.
• prefix (str) – the setting’s prefix (overrides AppSettings.Meta prefix).
• call_default (bool) – whether to call the default (if callable).
• transform_default (bool) – whether to transform the default value.
• validators (list of callables) – list of additional validators to use.
• item_type (type) – the type of the items inside the iterable.
• min_length (int) – minimum length of the iterable (included).
• max_length (int) – maximum length of the iterable (included).
• empty (bool) – whether empty iterable is allowed. Deprecated in favor of min_length.

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)

Bases: appsettings.settings.IterableSetting

Set setting.

__init__(name='', default=<class 'set'>, **kwargs)

Initialization method.

Parameters:

• name (str) – the name of the setting.
• default (set) – default value given to the setting.
• required (bool) – whether the setting is required or not.
• prefix (str) – the setting’s prefix (overrides AppSettings.Meta prefix).
• call_default (bool) – whether to call the default (if callable).
• transform_default (bool) – whether to transform the default value.
• validators (list of callables) – list of additional validators to use.
• item_type (type) – the type of the items inside the iterable.
• min_length (int) – minimum length of the iterable (included).
• max_length (int) – maximum length of the iterable (included).
• empty (bool) – whether empty iterable is allowed. Deprecated in favor of min_length.

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)

Bases: appsettings.settings.IterableSetting

Tuple setting.

__init__(name='', default=<class 'tuple'>, **kwargs)

Initialization method.

Parameters:

• name (str) – the name of the setting.
• default (tuple) – default value given to the setting.
• required (bool) – whether the setting is required or not.
• prefix (str) – the setting’s prefix (overrides AppSettings.Meta prefix).
• call_default (bool) – whether to call the default (if callable).
• transform_default (bool) – whether to transform the default value.
• validators (list of callables) – list of additional validators to use.
• item_type (type) – the type of the items inside the iterable.
• min_length (int) – minimum length of the iterable (included).
• max_length (int) – maximum length of the iterable (included).
• empty (bool) – whether empty iterable is allowed. Deprecated in favor of min_length.

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)

Bases: appsettings.settings.Setting

Dict setting.

__init__(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)

Initialization method.

Parameters:

• name (str) – the name of the setting.
• default (dict) – default value given to the setting.
• required (bool) – whether the setting is required or not.
• prefix (str) – the setting’s prefix (overrides AppSettings.Meta prefix).
• call_default (bool) – whether to call the default (if callable).
• transform_default (bool) – whether to transform the default value.
• validators (list of callables) – list of additional validators to use.
• key_type – the type of the dict keys.
• value_type (type) – the type of dict values.
• outer_delimiter (str) – value used to split environ string into separated parts
• inner_delimiter (str) – value used to split environ string parts
• min_length (int) – Noop. Deprecated.
• max_length (int) – Noop. Deprecated.
• empty (bool) – whether empty iterable is allowed. Deprecated in favor of MinLengthValidator.

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)

Bases: appsettings.settings.Setting

Object setting.

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

__init__(name='', default=None, required=False, prefix='', call_default=True, transform_default=False, validators=(), min_length=None, max_length=None, empty=None)

Initialization method.

Parameters:

• name (str) – the name of the setting.
• default (object) – default value given to the setting.
• required (bool) – whether the setting is required or not.
• prefix (str) – the setting’s prefix (overrides AppSettings.Meta prefix).
• call_default (bool) – whether to call the default (if callable).
• transform_default (bool) – whether to transform the default value.
• validators (list of callables) – list of additional validators to use.
• min_length (int) – Noop. Deprecated.
• max_length (int) – Noop. Deprecated.
• empty (bool) – Noop. Deprecated.

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)

Bases: appsettings.settings.ObjectSetting

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)

Bases: appsettings.settings.DictSetting

Nested dict setting.

Environment variables are not passed to inner settings.

__init__(settings, *args, **kwargs)

Initialization method.

Parameters:

• settings (dict) – subsettings.
• name (str) – the name of the setting.
• default (dict) – default value given to the setting.
• required (bool) – whether the setting is required or not.
• prefix (str) – the setting’s prefix (overrides AppSettings.Meta prefix).
• call_default (bool) – whether to call the default (if callable).
• transform_default (bool) – whether to transform the default value.
• validators (list of callables) – list of additional validators to use.
• key_type – the type of the dict keys.
• value_type (type) – the type of dict values.
• min_length (int) – minimum length of the iterable (included).
• max_length (int) – maximum length of the iterable (included).
• empty (bool) – whether empty iterable is allowed. Deprecated in favor of min_length.

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)

Bases: appsettings.settings.NestedDictSetting

Deprecated alias for NestedDictSetting.

__init__(*args, **kwargs)

Initialization method.

Parameters:

• settings (dict) – subsettings.
• name (str) – the name of the setting.
• default (dict) – default value given to the setting.
• required (bool) – whether the setting is required or not.
• prefix (str) – the setting’s prefix (overrides AppSettings.Meta prefix).
• call_default (bool) – whether to call the default (if callable).
• transform_default (bool) – whether to transform the default value.
• validators (list of callables) – list of additional validators to use.
• key_type – the type of the dict keys.
• value_type (type) – the type of dict values.
• min_length (int) – minimum length of the iterable (included).
• max_length (int) – maximum length of the iterable (included).
• empty (bool) – whether empty iterable is allowed. Deprecated in favor of min_length.

appsettings.NestedListSetting setting

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

Bases: appsettings.settings.IterableSetting

Nested list setting.

Environment variables are not passed to inner settings.

__init__(inner_setting, *args, **kwargs)

Initialization method.

Parameters:

• inner_setting (Setting) – setting that should be applied to list items. NestedDictSetting is not supported at the moment.
• name (str) – the name of the setting.
• default (dict) – default value given to the setting.
• required (bool) – whether the setting is required or not.
• prefix (str) – the setting’s prefix (overrides AppSettings.Meta prefix).
• call_default (bool) – whether to call the default (if callable).
• transform_default (bool) – whether to transform the default value.
• validators (list of callables) – list of additional validators to use.
• key_type – the type of the dict keys.
• value_type (type) – the type of dict values.
• min_length (int) – minimum length of the iterable (included).
• max_length (int) – maximum length of the iterable (included).
• empty (bool) – whether empty iterable is allowed. Deprecated in favor of min_length.

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.