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 method will be connected to the Django setting_changed signal in this method, with the dispatch UID being 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.

appsettings.Setting and subclasses

class appsettings.Setting(name='', default=None, required=False, prefix='', call_default=True, transform_default=False, checker=None, 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 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.

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, checker=None, 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.
• checker (callable) – an instance of type checker or any callable object accepting two arguments (name, value). This argument is deprecated.
• validators (list of callables) – list of additional validators to use.

__weakref__

list of weak references to the object (if defined)

check()

Run the setting checker against the setting raw value.

Raises:

• AttributeError – if the setting is missing and required.
• ValueError – if the raw value is invalid.

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.

raw_value

Property to return the variable defined in django.conf.settings.

Returns:

object – the variable defined 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.

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.

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.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, 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, 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.
• 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.

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

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

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.

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

Bases: appsettings.settings.IterableSetting

List setting.

__init__(name='', default=<class 'list'>, *args, **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.

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

Bases: appsettings.settings.IterableSetting

Set setting.

__init__(name='', default=<class 'set'>, *args, **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.

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

Bases: appsettings.settings.IterableSetting

Tuple setting.

__init__(name='', default=<class 'tuple'>, *args, **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.

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, 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, 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.
• min_length (int) – Noop. Deprecated.
• max_length (int) – Noop. Deprecated.
• empty (bool) – whether empty iterable is allowed. Deprecated in favor of MinLengthValidator.

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

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

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.

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.NestedSetting setting

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

Bases: appsettings.settings.DictSetting

Nested setting.

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

Run the setting checker against the setting raw 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.TypeChecker and subclasses

class appsettings.TypeChecker(base_type=None)

Bases: object

Type checker base class.

A type checker is a simple class that can be called when instantiated in order to validate an object against some conditions. A simple type checker will only check the type of the object. More complex type checkers can be created by inheriting from this base class.

__call__(name, value)

Call method.

Parameters:

• name (str) – the value’s name.
• value (object) – the value to check.

Raises:

ValueError – if value is not type base_type.

__init__(base_type=None)

Initialization method.

Parameters:base_type (type) – the type to check against value’s type.

__weakref__

list of weak references to the object (if defined)

class appsettings.BooleanTypeChecker

Bases: appsettings.settings.TypeChecker

Boolean type checker.

__init__()

Initialization method.

class appsettings.IntegerTypeChecker(minimum=None, maximum=None)

Bases: appsettings.settings.TypeChecker

Integer type checker.

__call__(name, value)

Call method.

Parameters:

• name (str) – the value’s name.
• value (int) – the value to check.

Raises:

• ValueError – if value is not type int.
• ValueError – if value is less than minimum.
• ValueError – if value is more than maximum.

__init__(minimum=None, maximum=None)

Initialization method.

Parameters:

• minimum (int) – a minimum value (included).
• maximum (int) – a maximum value (included).

class appsettings.FloatTypeChecker(minimum=None, maximum=None)

Bases: appsettings.settings.TypeChecker

Float type checker.

__call__(name, value)

Call method.

Parameters:

• name (str) – the value’s name.
• value (float) – the value to check.

Raises:

• ValueError – if value is not type float.
• ValueError – if value is less than minimum.
• ValueError – if value is more than maximum.

__init__(minimum=None, maximum=None)

Initialization method.

Parameters:

• minimum (float) – a minimum value (included).
• maximum (float) – a maximum value (included).

appsettings.IterableTypeChecker and subclasses

class appsettings.IterableTypeChecker(iter_type, item_type=None, min_length=None, max_length=None, empty=True)

Bases: appsettings.settings.TypeChecker

Iterable type checker.

Inherit from this class to create type checkers that support iterable object checking, with item type, minimum and maximum length, and allowed emptiness.

__call__(name, value)

Call method.

Parameters:

• name (str) – the value’s name.
• value (iterable) – the value to check.

Raises:

• ValueError – if value is not type iter_type.
• ValueError – if any item in value is not type item_type.
• ValueError – if value’s length is less than min_length.
• ValueError – if value’s length is more than max_length.
• ValueError – if value’s length is 0 and emptiness is not allowed.

__init__(iter_type, item_type=None, min_length=None, max_length=None, empty=True)

Initialization method.

Parameters:

• iter_type (type) – the type of the iterable object.
• item_type (type) – the type of the items inside the object.
• min_length (int) – a minimum length (included).
• max_length (int) – a maximum length (included).
• empty (bool) – whether emptiness is allowed.

class appsettings.StringTypeChecker(min_length=None, max_length=None, empty=True)

Bases: appsettings.settings.IterableTypeChecker

String type checker.

__init__(min_length=None, max_length=None, empty=True)

Initialization method.

Parameters:

• min_length (int) – minimum length of the string (included).
• max_length (int) – maximum length of the string (included).
• empty (bool) – whether empty string is allowed.

class appsettings.ListTypeChecker(item_type=None, min_length=None, max_length=None, empty=True)

Bases: appsettings.settings.IterableTypeChecker

List type checker.

__init__(item_type=None, min_length=None, max_length=None, empty=True)

Initialization method.

Parameters:

• item_type (type) – the type of the items inside the list.
• min_length (int) – minimum length of the list (included).
• max_length (int) – maximum length of the list (included).
• empty (bool) – whether empty list is allowed.

class appsettings.SetTypeChecker(item_type=None, min_length=None, max_length=None, empty=True)

Bases: appsettings.settings.IterableTypeChecker

Set type checker.

__init__(item_type=None, min_length=None, max_length=None, empty=True)

Initialization method.

Parameters:

• item_type (type) – the type of the items inside the set.
• min_length (int) – minimum length of the set (included).
• max_length (int) – maximum length of the set (included).
• empty (bool) – whether empty set is allowed.

class appsettings.TupleTypeChecker(item_type=None, min_length=None, max_length=None, empty=True)

Bases: appsettings.settings.IterableTypeChecker

Tuple type checker.

__init__(item_type=None, min_length=None, max_length=None, empty=True)

Initialization method.

Parameters:

• item_type (type) – the type of the items inside the tuple.
• min_length (int) – minimum length of the tuple (included).
• max_length (int) – maximum length of the tuple (included).
• empty (bool) – whether empty tuple is allowed.

appsettings.DictTypeChecker checker

class appsettings.DictTypeChecker(key_type=None, value_type=None, min_length=None, max_length=None, empty=True)

Bases: appsettings.settings.TypeChecker

Dict type checker.

__call__(name, value)

Call method.

Parameters:

• name (str) – the value’s name.
• value (dict) – the value to check.

Raises:

• ValueError – if value is not type dict.
• ValueError – if any key in value is not type key_type.
• ValueError – if any value in value is not type value_type.
• ValueError – if value’s length is less than min_length.
• ValueError – if value’s length is more than max_length.
• ValueError – if value’s length is 0 and emptiness is not allowed.

__init__(key_type=None, value_type=None, min_length=None, max_length=None, empty=True)

Initialization method.

Parameters:

• key_type (type) – the type of the dict keys.
• value_type (type) – the type of the dict values.
• min_length (int) – minimum length of the dict (included).
• max_length (int) – maximum length of the dict (included).
• empty (bool) – whether empty dict is allowed.

appsettings.ObjectTypeChecker checker

class appsettings.ObjectTypeChecker(empty=True)

Bases: appsettings.settings.StringTypeChecker

Object type checker.

Actually only check if the given value is a string.

TODO: maybe check that value is a valid Python path (https://stackoverflow.com/questions/47537921). TODO: maybe check that the object actually exists (https://stackoverflow.com/questions/14050281).

__call__(name, value)

Call method.

Parameters:

• name (str) – the value’s name.
• value (str) – the value to check.

Raises:

ValueError – if value is not type str.

__init__(empty=True)

Initialization method.

Parameters:empty (bool)