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.