====================
Django Settings Toml
====================

This project is used to configure  `Django <https://www.djangoproject.com>`_ projects using a `Toml <https://github.com/toml-lang/toml>`_ configuration file. This project chooses Toml over other configuration language becuase of it's simplicity and small specification. It is easier to understand and looks very much like INI-style config. We couldn't use INI-style because it is difficult to repsent data structures like dictionaries and lists, and there is no support for nesting.

Changelog
=========
0.0.4
-----
- Add support for Substitution in maps and lists.
- Fix loading settings where values are non-string which caused TypeError in v0.0.3.

0.0.3
-----
- Fix packaging for the new release.

0.0.2
------
- Add support for variable substitution using ``${VAR}`` syntax in values.


Usage
=====

To use this in your Django project, Add the following to your ``settings.py`` file::

  # settings.py
  from django_settings_toml import load_settings

  load_settings(__name__, ['/etc/project.toml', '~/.project.toml'])


Then, you can run your django project like this::

  $ DJANGO_SETTINGS_MODULE=project.settings django-admin runserver


Variable Substitution
---------------------

Values can refer to other keys defined in the same file using ``${VAR}``
syntax. For example::


  # /etc/project.toml

  HOSTNAME = 'domain.local'

  EMAIL1 = 'aperson@${HOSTNAME}'

  EMAIL2 = 'bperson@${HOSTNAME}'


In the above example, the value of ``EMAIL1 = 'aperson@domain.local`` and
similar for ``EMAIL2``.

If they variables that are being referred to aren't defined, the template is
left as-is and doesn't raise any errors. For example, in the above example, if
``HOSTNAME`` wasn't defined, the value will be ``EMAIL1 =
'aperson@${HOSTNAME}``.


Example Settings
================
::

   # /etc/project.toml
   # SECURITY WARNING: keep the secret key used in production secret!
   SECRET_KEY = 'change-this-on-your-production-server'

   # SECURITY WARNING: don't run with debug turned on in production!
   DEBUG = false

   ADMINS = [
   ['Mailman Suite Admin', 'root@localhost'],
   ]

   # Application definition
   INSTALLED_APPS = [
   'django.contrib.admin',
   'django.contrib.auth',
   'django.contrib.contenttypes',
   'django.contrib.sessions',
   'django.contrib.sites',
   'django.contrib.messages',
   'django.contrib.staticfiles',
   'rest_framework',
   'django_q',
   'allauth',
   ]

   MIDDLEWARE = [
   'django.contrib.sessions.middleware.SessionMiddleware',
   'django.middleware.common.CommonMiddleware',
   'django.middleware.csrf.CsrfViewMiddleware',
   'django.middleware.locale.LocaleMiddleware',
   'django.contrib.auth.middleware.AuthenticationMiddleware',
   'django.contrib.messages.middleware.MessageMiddleware',
   'django.middleware.clickjacking.XFrameOptionsMiddleware',
   'django.middleware.security.SecurityMiddleware',
   ]

   ROOT_URLCONF = 'project.urls'

   WSGI_APPLICATION = 'project.wsgi.application'

   HOSTNAME = 'project.local'

   EMAIL_NAME = 'project1@${HOSTNAME}'

   [DATABASES.default]
   ENGINE = 'django.db.backends.sqlite3'
   NAME = 'mailmansuite.db'

   [LOGGING]
   version = 1
   disable_existing_loggers = false

   [LOGGING.filters.require_debug_false]
   '()' = 'django.utils.log.RequireDebugFalse'

   [LOGGING.handlers.mail_admins]
   level = 'ERROR'
   filters = ['require_debug_false']
   class =  'django.utils.log.AdminEmailHandler'

   [LOGGING.handlers.file]
   level = 'INFO'
   class = 'logging.handlers.WatchedFileHandler'
   filename =  'logs/mailmansuite.log'
   formatter = 'verbose'

   [LOGGING.loggers."django.request"]
   handlers = ['mail_admins', 'file']
   level = 'ERROR'
   propagate = true

   [LOGGING.formatters.verbose]
   format = '%(levelname)s %(asctime)s %(process)d %(name)s %(message)s'


Gotchas
=======

- Please make sure that you have writtena valid Toml, you can use
  `TOML Validator <https://github.com/BurntSushi/toml/tree/master/cmd/tomlv>`_ or
  `tomlcheck <https://github.com/vmchale/tomlcheck>`_ tools to
  validate the toml file.

- Please make sure that all smiple ``KEY = value`` pairs are in the
  root namespace (above any ``[section]``) so that they don't get
  swallowed under one of the maps or arrays. Previously, we have
  seen ``ImproperlyConfiguredError`` for missing keys that were
  actually defined in the toml file.

LICENSE
=======

The contents of this project is licensed under Apache License 2.0. Please see
the LICENSE file for a complete copy of license text.
