README.rst

Django AppSettings

Application settings helper for Django apps.

Why another app settings app? Because none of the other suited my needs!

This one is simple to use, and works with unit tests overriding settings.

Installation

pip install django-app-settings

Documentation

On ReadTheDocs

Development

To run all the tests: tox. See CONTRIBUTING.

Quick usage

# Define your settings class
import appsettings


class MySettings(appsettings.AppSettings):
    boolean_setting = appsettings.BooleanSetting(default=False)
    required_setting = appsettings.StringSetting(required=True)
    named_setting = appsettings.IntegerSetting(name='integer_setting')
    prefixed_setting = appsettings.ListSetting(prefix='my_app_')

    class Meta:
        setting_prefix = 'app_'


# Related settings in settings.py
APP_INTEGER_SETTING = -24
MY_APP_PREFIXED_SETTING = []


# Instantiate your class wherever you need to
appconf = MySettings()
assert appconf.boolean_setting is False  # True (default value)
assert appconf.required_setting == 'hello'  # raises AttributeError
assert appconf.named_setting < 0  # True
assert appconf.prefixed_setting  # False (empty list)


# Values are cached to avoid perf issues
with override_settings(APP_REQUIRED_SETTING='hello',
                       APP_INTEGER_SETTING=0):
    # ...but cache is cleaned on Django's setting_changed signal
    assert appconf.required_setting == 'hello'  # True
    assert appconf.named_setting < 0  # False


# You can still access settings through the class itself (values not cached)
print(MySettings.boolean_setting.get_value())  # explicit call
print(MySettings.boolean_setting.value)  # with property


# Run type checking and required presence on all settings at once
MySettings.check()  # raises Django's ImproperlyConfigured (missing required_setting)
# MySettings.check() is best called in django.apps.AppConfig's ready method

You can easily create your own Setting classes for more complex settings.

import re

import appsettings
from django.core.exceptions import ValidationError


class RegexSetting(appsettings.Setting):
    def validate(self, value):
        re_type = type(re.compile(r'^$'))
        if not isinstance(value, (re_type, str)):
            # Raise ValidationError
            raise ValidationError('Value must be a string or a compiled regex (use re.compile)')

    def transform(self, value):
        # ensure it always returns a compiled regex
        if isinstance(value, str):
            value = re.compile(value)
        return value

Please check the documentation to see even more advanced usage.

License

Software licensed under ISC license.