django-classbasedsettings 1.1.0

Basic

The only real change you need to make to the settings.py file that Django creates for you is to nest all the variables in a class:

from cbsettings import DjangoDefaults

class MySettings(DjangoDefaults):

    ADMINS = (
        # ('Your Name', 'your_email@example.com'),
    )

    MANAGERS = ADMINS

    DATABASES = {
        'default': {
            'ENGINE': 'django.db.backends.',
            'NAME': '',
            'USER': '',
            'PASSWORD': '',
            'HOST': '',
            'PORT': '',
        }
    }

    # etc, etc

Notice that the class extends DjangoDefaults. By inheriting from this class, you get all the default settings values that Django normally composites your settings with. (These are pulled in from django.conf.global_settings so they’ll track with your version of Django, not classbasedsettings.) You can also do stuff like this:

class MySettings(DjangoDefaults):

    STATICFILES_FINDERS = DjangoDefaults.STATICFILES_FINDERS + (
        'my.custom.StaticFileFinder',
    )

    # etc

These are just normal Python classes, so you can do anything you normally can:

class MySettings(DjangoDefaults):

    @property
    def TEMPLATE_DEBUG(self):
        # Now a subclass can override DEBUG and TEMPLATE_DEBUG will be changed accordingly
        return self.DEBUG

    # etc

Callable properties are automatically called:

class MySettings(DjangoDefaults):

    TEMPLATE_DEBUG = lambda s: s.DEBUG

...unless you don’t want them to be:

from cbsettings import callable_setting

class MySettings(DjangoDefaults):

    @callable_setting
    def SOME_SETTING(self, *args, **kwargs):
        # This setting is actually a callable. The decorator tells cbsettings
        # not to invoke it to get a settings value.
        .
        .
        .

You can also prevent your callable settings from receiveing a “self” argument:

from cbsettings import callable_setting

class MySettings(DjangoDefaults):

    @callable_setting(takes_self=False)
    def SOME_SETTING(*args, **kwargs):
        .
        .
        .

Using a Settings Factory

You might be thinking that hardcoding your settings class into files is just as bad as Django’s hardcoding of the settings module. That’s true. Which is why configure() can be passed the path to any callable that returns a settings object instance. So your manage.py might instead look like this:

#!/usr/bin/env python
import sys
import cbsettings

if __name__ == "__main__":
    cbsettings.configure('path.to.my.settings.factory')

    from django.core.management import execute_from_command_line

    execute_from_command_line(sys.argv)

Then, in path/to/my/settings.py:

def factory():
    if 'DEV' in os.environ:
        return MyDebugSettings()
    else:
        return MyProductionSettings()

Now you can easily change which settings class you’re using based on whatever conditions you want without having to make modifications to multiple files.

Using Switcher

Using a factory method to determine which settings class to use is a powerful feature! But usually you’ll want to switch settings classes based on the same kinds of conditions, so django-classbasedsettings comes with a factory that’ll handle these common cases, and allow you to easily define simple conditions of your own. It also uses a more declarative syntax, which makes it more organized than a factory method. Here’s how you use it in your settings file:

from cbsettings import DjangoDefaults, switcher

class MyProductionSettings(DjangoDefaults):
    DEBUG = False
    # etc

class MyDevSettings(DjangoDefaults):
    DEBUG = True
    # etc

class MyTestingSettings(MyProductionSettings):
    SOME_VAR = 'whatever'

# You can use one of the preregistered conditions by passing kwargs. The
# first class whose conditions are all met will be used.
switcher.register(MyTestSettings, testing=True)
switcher.register(MyDevSettings, hostnames=['mycompuer.home', 'billscomputer.home'])
switcher.register(MyProductionSettings, hostnames=['theserver.com'])

# ...or you can define your own simple checks as positional arguments. If
# all of the values are truthy (and any kwarg checks pass), the class will
# be used.
switcher.register(MyDevSettings, 'dev.mysite.com' in __file__)
switcher.register(MyDevSettings, os.environ.get('DEV'))

# Callable positional arguments will be called, then checked for truthiness.
switcher.register(MyDevSettings, lambda: randint(1, 2) == 2)

You can also use switcher.register as a class decorator:

@switcher.register(hostnames=['theserver.com'])
class MyProductionSettings(DjangoDefaults):
    DEBUG = False
    # etc

Then, wherever you’re calling configure, pass it your module’s switcher variable:

cbsettings.configure('path.to.my.settings.switcher')