106 lines
3.9 KiB
ReStructuredText
106 lines
3.9 KiB
ReStructuredText
.. 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`
|