README.rst
1django-appconf
2==============
3
4.. image:: http://codecov.io/github/django-compressor/django-appconf/coverage.svg?branch=develop
5 :alt: Code Coverage
6 :target: http://codecov.io/github/django-compressor/django-appconf?branch=develop
7
8.. image:: https://secure.travis-ci.org/django-compressor/django-appconf.png?branch=develop
9 :alt: Build Status
10 :target: http://travis-ci.org/django-compressor/django-appconf
11
12A helper class for handling configuration defaults of packaged Django
13apps gracefully.
14
15.. note::
16
17 This app precedes Django's own AppConfig_ classes that act as
18 "objects [to] store metadata for an application" inside Django's
19 app loading mechanism. In other words, they solve a related but
20 different use case than django-appconf and can't easily be used
21 as a replacement. The similarity in name is purely coincidental.
22
23.. _AppConfig: https://docs.djangoproject.com/en/stable/ref/applications/#django.apps.AppConfig
24
25Overview
26--------
27
28Say you have an app called ``myapp`` with a few defaults, which you want
29to refer to in the app's code without repeating yourself all the time.
30``appconf`` provides a simple class to implement those defaults. Simply add
31something like the following code somewhere in your app files::
32
33 from appconf import AppConf
34
35 class MyAppConf(AppConf):
36 SETTING_1 = "one"
37 SETTING_2 = (
38 "two",
39 )
40
41.. note::
42
43 ``AppConf`` classes depend on being imported during startup of the Django
44 process. Even though there are multiple modules loaded automatically,
45 only the ``models`` modules (usually the ``models.py`` file of your
46 app) are guaranteed to be loaded at startup. Therefore it's recommended
47 to put your ``AppConf`` subclass(es) there, too.
48
49The settings are initialized with the capitalized app label of where the
50setting is located at. E.g. if your ``models.py`` with the ``AppConf`` class
51is in the ``myapp`` package, the prefix of the settings will be ``MYAPP``.
52
53You can override the default prefix by specifying a ``prefix`` attribute of
54an inner ``Meta`` class::
55
56 from appconf import AppConf
57
58 class AcmeAppConf(AppConf):
59 SETTING_1 = "one"
60 SETTING_2 = (
61 "two",
62 )
63
64 class Meta:
65 prefix = 'acme'
66
67The ``MyAppConf`` class will automatically look at Django's global settings
68to determine if you've overridden it. For example, adding this to your site's
69``settings.py`` would override ``SETTING_1`` of the above ``MyAppConf``::
70
71 ACME_SETTING_1 = "uno"
72
73In case you want to use a different settings object instead of the default
74``'django.conf.settings'``, set the ``holder`` attribute of the inner
75``Meta`` class to a dotted import path::
76
77 from appconf import AppConf
78
79 class MyAppConf(AppConf):
80 SETTING_1 = "one"
81 SETTING_2 = (
82 "two",
83 )
84
85 class Meta:
86 prefix = 'acme'
87 holder = 'acme.conf.settings'
88
89If you ship an ``AppConf`` class with your reusable Django app, it's
90recommended to put it in a ``conf.py`` file of your app package and
91import ``django.conf.settings`` in it, too::
92
93 from django.conf import settings
94 from appconf import AppConf
95
96 class MyAppConf(AppConf):
97 SETTING_1 = "one"
98 SETTING_2 = (
99 "two",
100 )
101
102In the other files of your app you can easily make sure the settings
103are correctly loaded if you import Django's settings object from that
104module, e.g. in your app's ``views.py``::
105
106 from django.http import HttpResponse
107 from myapp.conf import settings
108
109 def index(request):
110 text = 'Setting 1 is: %s' % settings.MYAPP_SETTING_1
111 return HttpResponse(text)
112
113