topple/docs/index.rst

.. 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`