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
|
.. topple documentation master file, created by
sphinx-quickstart on Sun Dec 15 23:37:44 2013.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
topple
======
Bigger projects cat get somewhat more complicated settings files. One
strategy from keeping required settings and installation-specific
settings apart may be to separate the two in different files. Whether
this is the case or not, topple might be able to help you.
topple tries to help you maintain this kind of file by allowing you to
specify a template of such a file, with some extra data such as a
predicate to check the value with, and generating and updating such
files from this template.
Configuration
-------------
Configuration is stored in a module named ``toppler``, unless a
``--module`` or ``-m`` argument was specified on the command line. An
example configuration might look like::
def boolp(val):
return isinstance(val, bool)
def integerp(val):
return isinstance(val, integer)
def stringp(val):
return isinstance(val, string)
def listp(val):
return isinstance(val, list)
OUTPUT_FILE = 'settings_local.py'
SETTINGS = [
('DEBUG', (boolp, True)),
('DEBUG_PROPOGATE_EXCEPTIONS', (boolp, True)),
('SITE_ID', (integerp, 1)),
('ALLOWED_HOSTS', (listp, ['.example.com']))
]
This file specifies a few predicates to check the types of the
settings. Any function returning a ``True`` or ``False`` value and
taking a single arguments (the value specified for the setting) can be
used. For example ``os.path.exists`` may be used to specify that the
value in a setting must be an existing path. It specifies that the
settings should be output to the file ``settings_local.py`` and that
it should have the ``DEBUG``, ``DEBUG_PROPOGATE_EXCEPTIONS``,
``SITE_ID`` and ``ALLOWED_HOSTS`` settings. It also specifies the
predicates to use to check the validity of each setting and their
initial values.
Command-line Usage
------------------
topple works through three main commands, ``generate``, ``update`` and
``check``. These commands are implemented by the following classes:
.. class:: Generate
Implements the ``generate`` command. This command turns the
template as found in the configuration file into a usable settings
file. The predicates aren't used at this point, it is not required
to specify valid options in the template, though it is important
for you to change these settings as soon as possible, otherwise you
won't be able to (fully) use the settings.
The ``generate`` command writes the settings to the ``OUTPUT_FILE``
as specified in the configuration file, unless the ``--preview`` (or
``-p``) option is given, in which case the settings are printed to
the standard output stream.
.. class:: Update
Implements the ``update`` command. This command reads the existing
``OUTPUT_FILE`` and the configuration and merges them. It leaves
existing settings as they are, but adds settings that are not yet
present in the ``OUTPUT_FILE``.
The ``update`` command writes the settings to the ``OUTPUT_FILE``
as specified in the cunfiguration file, unless the ``--preview``
(or ``-p``) option is given, in which case the settings are printed
to the standard output stream.
.. class:: Check
Implements the ``check`` command. This command reads the existing
``OUTPUT_FILE`` and the configuration and checks the validity of
the settings in ``OUTPUT_FILE``. For each setting that doesn't
match the given predicate an error message is printed, specifying
the setting, value and name of the predicate. For each setting that
has been specified in the configuration file that wasn't found in
the ``OUTPUT_FILE`` a message is printed stating that it is missing
from the ``OUTPUT_FILE``.
.. toctree::
:maxdepth: 2
Indices and tables
==================
* :ref:`genindex`
* :ref:`search`
|
