#############
django-confit
#############
`django-confit` eases Django configuration management.
**As a Django user**, in order to configure a project:
* `django-confit` helps you load the settings wherever they are, whatever the
format: Python modules, environment variables, JSON, YAML...
* `django-confit` validates the settings, i.e. it tells you if some directive
is missing, has wrong format...
**As a Django library developer**, in order to help your application's users:
* you write configuration schemas for your application, using `django-confit`'s
toolkit and conventions.
* `django-confit` helps you document your application's specific
configuration.
**As a non Django user**, in order to deploy and run a Django-powered project:
* you write the configuration as you like, depending on your workflow and your
provisioning toolkit. You know the project can load them using
`django-confit`.
* you expect applications to validate the configuration before they actually
use it, and report errors with a readable output.
*******
Example
*******
In a project's ``settings.py`` file, let's load configuration from various
locations:
.. code-block:: python
import os
import django_confit
# Load settings.
raw_settings = {}
raw_settings.update(django_confit.load_module('myproject.default_settings'))
raw_settings.update(django_confit.load_file(open('/etc/myproject.json')))
raw_settings.update(django_confit.load_mapping(os.environ, prefix='MYPROJECT_')
# Update globals, because that's the way Django uses DJANGO_SETTINGS_MODULE.
globals().update(raw_settings)
Optionally, you can use builtin schemas to validate settings:
.. code-block:: python
# Validate and clean settings.
cleaned_settings = django_confit.validate_settings(raw_settings)
# Update globals, because that's the way Django uses DJANGO_SETTINGS_MODULE.
globals().update(cleaned_settings)
.. warning:: At the moment, there is no builtin schema for latest Django>=1.7.
**************
Project status
**************
Today, `django-confit` is a proof of concept:
* loading settings is nice and easy.
* validating configuration is easy... provided you have the schemas.
* creating configuration schemas is verbose. It uses `colander`_ which has nice
features, but may not be the definitive option.
* generating documentation from schemas is not implemented.
**The main limitation is that, when you use validation, schemas are
mandatory.** If some configuration directive is not registered in a schema, it
will not be present in validation output. It means that, if you install a new
third-party Django application, you need the configuration schema for this
application, else its settings will not pass validation. **So the most-wanted
contribution is submitting configuration schemas for third-party
applications.**
Notice that this behaviour is a wanted feature. As `django-confit` author, I
think **libraries should always provide a schema for the settings they use**.
I do not pretend `django-confit` should be THE answer. I just bet that, if
schemas were widely adopted by the Django community, configuration would be
easier to manage.
`django-confit` does not pretend to be the ultimate configuration management
app for Django. Its goal is to show how some issues could be resolved, and to
highlight the benefits. `django-confit` is a proposal. If you like its
concepts, then you can:
* use `django-confit` of course!
* discuss, spread the word, send feedback.
* improve code. Help around configuration schemas of third-party apps would be
appreciated.
**********
Ressources
**********
* Documentation: https://django-confit.readthedocs.org
* PyPI page: https://pypi.python.org/pypi/django-confit/
* Code repository: https://github.com/benoitbryon/django-confit
* Bugtracker: https://github.com/benoitbryon/django-confit/issues
* Continuous integration: https://travis-ci.org/benoitbryon/django-confit
* Roadmap: https://github.com/benoitbryon/django-confit/milestones
.. _`colander`: https://pypi.python.org/pypi/colander/