django-confit¶

Prerequisites¶

• Python [1] 2.7, 3.3, 3.4, 3.5

As a library¶

In most cases, you will use django-confit as a dependency of another project (typically a Django project or a Django application). In such a case, you should add django-confit in your main project’s requirements. Typically in setup.py:

from setuptools import setup

setup(
    install_requires=[
        'django-confit',
        #...
    ]
    # ...
)

Then when you install your main project with your favorite package manager (like pip [2]), django-confit will automatically be installed.

Standalone¶

You can install django-confit with your favorite Python package manager. As an example with pip [2]:

pip install django-confit

Check¶

Check django-confit has been installed:

python -c "import django_confit;print(django_confit.__version__)"

You should get django_confit‘s version.

Notes & references

CONFIT_SCHEMAS¶

A dictionary of <APP>: <SCHEMA> where <APP> is in INSTALLED_APPS and <SCHEMA> is the Python dotted path to a Schema class (or factory).

This configuration directive is mandatory only when you need configuration schemas that are not builtin django-confit. See also the list of builtin schemas.

validate_settings() automatically loads schemas from INSTALLED_APPS setting. For each <APP> in INSTALLED_APPS, it looks for:

1. CONFIT_SCHEMAS[<APP>],
2. django_confit.schemas.<APP>.ConfigurationSchema.

Simple example from default settings in django-confit demo project [1]:

CONFIT_SCHEMAS = {
    'django_confit_demo': 'django_confit_demo.settings_schemas'
                          '.DjangoConfitDemoConfigurationSchema'
}

Notes & references

load_mapping¶

django_confit.loaders.load_mapping(input, prefix='')¶

Convert mapping of {key: string} to {key: complex type}.

This function makes it possible (and easy) to load complex types from single-level key-value stores, such as environment variables or INI files.

Of course, both flat and nested mappings are supported:

>>> from django_confit import load_mapping
>>> flat_mapping = {'DEBUG': 'True', 'SECRET_KEY': 'not a secret'}
>>> output = load_mapping(flat_mapping)
>>> output == flat_mapping
True

>>> nested_mapping = {'DATABASES': {'USER': 'me', 'HOST': 'localhost'}}
>>> output = load_mapping(nested_mapping)
>>> output == nested_mapping
True

Values can be complex types (sequences, mappings) using JSON or YAML. Keys using ”.json” or ”.yaml” suffix are automatically decoded:

>>> nested_mapping = {
...     'DATABASES.yaml': 'ENGINE: sqlite3',
... }
>>> output = load_mapping(nested_mapping)
>>> output['DATABASES'] == {'ENGINE': 'sqlite3'}
True

You can use optional prefix argument to load only a subset of mapping:

>>> mapping = {'YES_ONE': '1', 'NO_TWO': '2'}
>>> load_mapping(mapping, prefix='YES_')
{'ONE': '1'}

load_module¶

django_confit.loaders.load_module(module_path)¶

Return module’s globals as a dict.

>>> from django_confit import load_module
>>> settings = load_module('django.conf.global_settings')
>>> settings['DATABASES']
{}

It does not load “protected” and “private” attributes (those with underscores).

>>> '__name__' in settings
False

load_file¶

django_confit.loaders.load_file(file_obj)¶

Return mapping from file object, using name attr to guess format.

Supported file formats are JSON and YAML. The lowercase extension is used to guess the file type.

>>> from django_confit import load_file
>>> from six.moves import StringIO
>>> file_obj = StringIO('SOME_LIST: [a, b, c]')
>>> file_obj.name = 'something.yaml'
>>> load_file(file_obj) == {
...     'SOME_LIST': ['a', 'b', 'c'],
... }
True

validate_settings¶

django_confit.schemas.validate_settings(raw_settings)¶

Return cleaned settings using schemas collected from INSTALLED_APPS.

Low-level API¶

Use deserialize() method of Colander schemas: http://docs.pylonsproject.org/projects/colander/en/latest/basics.html#deserialization

Create settings_schemas.ConfigurationSchema¶

See:

• colander’s documentation [1]
• django-confit’s builtin schemas [2]

Simple example from custom schemas in django-confit demo project [3]:

"""Custom configuration schema(s)."""
import colander


class DjangoConfitDemoConfigurationSchema(colander.MappingSchema):
    CONFITDEMO_HELLO = colander.SchemaNode(
        colander.String(),
        missing=colander.required,
        default='',
    )

Register your schema¶

In a project or a third-party application, register schemas in settings.CONFIT_SCHEMAS. See Configure.

In django-confit itself, make sure the schema can be loaded with django_confit.schemas.<APP>.ConfigurationSchema.

Notes & references

Create tickets¶

Please use django-confit bugtracker [1] before starting some work:

• check if the bug or feature request has already been filed. It may have been answered too!
• else create a new ticket.
• if you plan to contribute, tell us, so that we are given an opportunity to give feedback as soon as possible.
• Then, in your commit messages, reference the ticket with some refs #TICKET-ID syntax.

Use topic branches¶

• Work in branches.
• Prefix your branch with the ticket ID corresponding to the issue. As an example, if you are working on ticket #23 which is about contribute documentation, name your branch like 23-contribute-doc.
• If you work in a development branch and want to refresh it with changes from master, please rebase [2] or merge-based rebase [3], i.e. do not merge master.

Fork, clone¶

Clone django-confit repository (adapt to use your own fork):

git clone git@github.com:benoitbryon/django-confit.git
cd django-confit/

Usual actions¶

The Makefile is the reference card for usual actions in development environment:

• Install development toolkit with pip [4]: make develop.
• Run tests with tox [5]: make test.
• Build documentation: make documentation. It builds Sphinx [6] documentation in var/docs/html/index.html.
• Release django-confit project with zest.releaser [7]: make release.
• Cleanup local repository: make clean, make distclean and make maintainer-clean.

See also make help.

Notes & references