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=())[source]
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()[source]
Validate the setting value.
- Raises:
ImproperlyConfigured – The setting doesn’t have a valid value.
- decode_environ(value)[source]
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()[source]
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 indjango.conf.settings
.- Raises:
AttributeError – if the variable is missing.
KeyError – if the item is missing from nested setting.
- transform(value)[source]
Return a transformed value.
By default, no transformation is done.
- Parameters:
value (object)
- Returns:
object – the transformed value.
- validate(value)[source]
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=())[source]
Boolean setting.
- class appsettings.IntegerSetting(name='', default=0, required=False, prefix='', call_default=True, transform_default=False, validators=(), minimum=None, maximum=None)[source]
Integer setting.
- class appsettings.PositiveIntegerSetting(name='', default=0, required=False, prefix='', call_default=True, transform_default=False, validators=(), maximum=None)[source]
Positive integer setting.
- class appsettings.FileSetting(name='', default=None, required=False, prefix='', call_default=True, transform_default=False, validators=(), mode=None)[source]
File setting.
Value of this setting is a pathlib.Path instance.
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)[source]
Iterable setting.
- class appsettings.StringSetting(name='', default='', required=False, prefix='', call_default=True, transform_default=False, validators=(), min_length=None, max_length=None, empty=None)[source]
String setting.
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)[source]
Dict setting.
- decode_environ(value)[source]
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
andouter_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)[source]
Object setting.
This setting allows to return an object given its Python path (a.b.c).
- decode_environ(value)[source]
Try to load JSON or return pure string, if JSONDecodeError is raised.
- Parameters:
(string)
- Returns:
string
- transform(path)[source]
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 thegetattr
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)[source]
Callable path setting.
This setting value should be string containing a dotted path to a callable.
appsettings.NestedDictSetting
setting
- class appsettings.NestedDictSetting(settings, *args, **kwargs)[source]
Nested dict setting.
Environment variables are not passed to inner settings.
appsettings.NestedSetting
setting
This setting is deprecated in favor of appsettings.NestedDictSetting
.
appsettings.NestedListSetting
setting
- class appsettings.NestedListSetting(inner_setting, *args, **kwargs)[source]
Nested list setting.
Environment variables are not passed to inner settings.
- get_value()[source]
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.