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