DOCSEARCHbyAlgolia
Submit Docs

django-appconf Documentation

repository·develop·Indexed 18 days ago

https://github.com/django-compressor/django-appconf

A helper library for managing default configuration settings for Django applications. It allows developers to define app-specific defaults using the AppConf class, which can be overridden via Django's global settings. Features include automatic prefixing, custom configuration logic via configure_* methods, and a Meta inner class to customize prefixes, required settings, and settings holders.

Tokens
2.6K
Snippets
12
Records
13
Agent score
61%

What's inside django-appconf

  1. Enable AppConf to proxy global Django settings

    develop

    By default, AppConf instances do not act as proxies for the global Django settings. To enable this behavior—allowing the AppConf instance to look up values in the global settings object (using the app's prefix)—set proxy = True within the inner Meta class of your AppConf subclass.

    from appconf import AppConf

class MyAppConf(AppConf):
    SETTING_1 = "one"
    SETTING_2 = (
        "two",
    )

    class Meta:
        proxy = True

myapp_settings = MyAppConf()

# If proxy=True, this checks django.conf.settings.MYAPP_INSTALLED_APPS
if "myapp" in myapp_settings.INSTALLED_APPS:
    print "yay, myapp is installed!"

  2. Access app settings in your code

    develop

    While it is strongly recommended to use from django.conf import settings to access configured settings, you can optionally use your app's specific AppConf instance directly.

    When accessing settings directly via an AppConf instance, the settings do not have the application's prefix (e.g., if your app is myapp, you access SETTING_1 instead of MYAPP_SETTING_1).

    from myapp.models import MyAppConf

myapp_settings = MyAppConf()
print myapp_settings.SETTING_1

  4. Best practices for shipping AppConf in reusable apps

    develop

    When developing a reusable Django app, follow these patterns to ensure settings are correctly loaded and accessible:

    1. File Structure: Place your AppConf subclass in a conf.py file within your app package.
    2. Imports: Import django.conf.settings inside your conf.py.
    3. Accessing Settings: In your app's logic (e.g., views.py), import the settings object directly from your app's configuration module rather than django.conf.settings to ensure the AppConf defaults are applied.

    Example Structure:

    myapp/conf.py:

    from django.conf import settings
from appconf import AppConf

class MyAppConf(AppConf):
    SETTING_1 = "one"

    myapp/views.py:

    from django.http import HttpResponse
from myapp.conf import settings

def index(request):
    # Accessing the setting via the app's config module
    text = 'Setting 1 is: %s' % settings.MYAPP_SETTING_1
    return HttpResponse(text)
    from django.conf import settings
from appconf import AppConf

class MyAppConf(AppConf):
    SETTING_1 = "one"
    SETTING_2 = (
        "two",
    )

  5. Define application configuration defaults with AppConf

    develop

    Use AppConf to manage default settings for a packaged Django app. By subclassing AppConf, you can define default values that are automatically overridden if corresponding settings exist in Django's global settings.py.

    Key Behaviors:

    • Automatic Prefixing: By default, the settings are prefixed with the capitalized name of the app package where the class is defined. For example, if the class is in myapp/models.py, the setting is accessed via MYAPP_SETTING_NAME.
    • Startup Requirement: AppConf classes must be imported during the Django startup process. It is highly recommended to define your AppConf subclass within your app's models.py or a dedicated conf.py file to ensure they are loaded.
    • Global Settings Integration: AppConf integrates with Django's global settings. If you define ACME_SETTING_1 = "uno" in your project's settings.py, it will override the default value provided in your AppConf class.
    from appconf import AppConf

class MyAppConf(AppConf):
    SETTING_1 = "one"
    SETTING_2 = (
        "two",
    )

  6. Override settings programmatically during instantiation

    develop

    You can override specific settings at the moment you instantiate your AppConf class by passing the setting names as keyword arguments.

    from myapp.models import MyAppConf

myapp_settings = MyAppConf(SETTING_1='something completely different')

if 'different' in myapp_settings.SETTING_1:
    print "yay, I'm different!"

  7. Define application settings with AppConf

    develop

    Use the AppConf class to create a template for application settings. You define settings as class attributes. This allows you to centralize configuration and provide a structured way to access settings via a specific prefix or holder (like django.conf.settings).

    from appconf import AppConf

class MyAppConf(AppConf):
    SETTING_1 = "one"
    SETTING_2 = (
        "two",
    )

  8. Customize AppConf prefix and settings holder

    develop

    You can control how AppConf identifies its settings and where it looks for overrides using an inner Meta class.

    • prefix: Overrides the default capitalized app label prefix. If prefix = 'acme', the setting becomes ACME_SETTING_1.
    • holder: Overrides the default settings object (which is django.conf.settings). Provide a dotted import path to a different settings object.
    from appconf import AppConf

class AcmeAppConf(AppConf):
    SETTING_1 = "one"
    SETTING_2 = (
        "two",
    )

    class Meta:
        prefix = 'acme'
        holder = 'acme.conf.settings'

  9. Configure AppConf behavior using the Meta inner class

    develop

    The AppConf.Meta inner class allows you to customize how settings are looked up, validated, and accessed. Use it to define prefixes, required settings, and the settings holder.

    class MyAppConf(AppConf):
    SETTING_1 = "one"
    SETTING_2 = "two"

    class Meta:
        proxy = False
        prefix = 'myapp'
        required = ['SETTING_3', 'SETTING_4']
        holder = 'django.conf.settings'

  10. Implement custom configuration logic with configure_* methods

    develop

    You can intercept the value of a specific setting by implementing a configure_<SETTING_NAME> method on your AppConf subclass. This method receives the initial value (either the class attribute value or the value found in the Meta.holder) and must return the final value to be used for that setting. This is useful for dynamic configuration based on the environment.

    class MyAppConf(AppConf):
    DEPLOYMENT_MODE = "dev"

    def configure_deployment_mode(self, value):
        if on_production():
            value = "prod"
        return value

  11. Use the main configure method for cross-setting logic

    develop

    After all individual configure_<setting_name> methods have run, AppConf calls a main configure() method. This method is intended for complex configuration where multiple settings depend on each other.

    • You can access the current state of all settings via the self.configured_data dictionary.
    • Important: If you modify settings within this method, you must return the self.configured_data dictionary.
    from django.conf import settings
from appconf import AppConf

class MyCustomAppConf(AppConf):
    ENABLED = True
    MODE = 'development'

    def configure_enabled(self, value):
        return value and not settings.DEBUG

    def configure(self):
        mode = self.configured_data['MODE']
        enabled = self.configured_data['ENABLED']
        if not enabled and mode != 'development':
            print "WARNING: app not enabled in %s mode!" % mode
        return self.configured_data

  12. Configure settings with callbacks

    develop

    You can define custom logic for individual settings by implementing a method named configure_<lower_setting_name>.

    • The method receives one parameter: the default value defined in the class attribute or the override value from global settings.
    • The method must return the value to be used for that setting.
    • This is useful for settings that depend on other global settings (like django.conf.settings.DEBUG).
    from django.conf import settings
from appconf import AppConf

class MyCustomAppConf(AppConf):
    ENABLED = True

    def configure_enabled(self, value):
        # Returns True only if ENABLED is True and DEBUG is False
        return value and not settings.DEBUG