django-easysettings 2.0.1
Easy app-specific settings for Django
License: BSD

===================
django-easysettings
===================

.. image:: https://circleci.com/gh/SmileyChris/django-easysettings.svg?style=svg
    :alt: Build status
    :target: https://circleci.com/gh/SmileyChris/django-easysettings

.. image:: https://codecov.io/gh/SmileyChris/django-easysettings/branch/master/graph/badge.svg
    :alt: Coverage status
    :target: https://codecov.io/gh/SmileyChris/django-easysettings


Easy app-specific settings for Django apps.

Provides a method for using a declarative class for an app's default settings.
The instance of this class can be used to access all project settings in place
of ``django.conf.settings``.

.. contents::
    :local:
    :backlinks: none


Installation
============

To install, run: ``pip install django-easysettings``


Usage
=====

Create a ``conf.py`` file within your app's directory, adding attributes for
the default values of your app-specific settings. They will be overridden by
any project setting that is provided.

For example:

.. code:: python

    from easysettings.app import AppSettings


    class Settings(AppSettings):
        MYAPP_FRUIT = 'Apple'


    settings = Settings()


Then in your app, rather than `from django.conf import settings`, use
`from myapp.conf import settings`. For example:

.. code:: python

    from myapp.conf import settings


    def dashboard(request):
        context = {}
        context['fruit'] = settings.MYAPP_FRUIT
        if settings.DEBUG:
            context['debug_mode'] = True
        # ...

Dictionaries
------------

A common pattern is to use a dictionary as a namespace for all an app's
settings, such as ``settings.MYAPP['settings']``.

Easy-settings handles this fine, overriding any keys provided in the project
while still having access to the default app settings keys.

You can also use a subclass of an ``AppSettings`` class to set up a dictionary.

.. code:: python

    from easysettings.apps import AppSettings


    class MyAppSettings(AppSettings):
        """
        MyApp settings
        """
        #: Preferred fruit
        FRUIT = 'Apple'
        #: Preferred drink
        DRINK = 'Water'


    class Settings(AppSettings):
        MYAPP = MyAppSettings


    settings = Settings()

Legacy Usage
------------

If previously your app used a common prefix (like `MYAPP_`) you
can still support projects that still use these stand-alone legacy settings
while moving to a ``MYAPP`` dictionary for your settings.

.. code:: python

    from easysettings.legacy import LegacyAppSettings


    class Settings(LegacyAppSettings):
        MYAPP = {'FRUIT': 'Apple'}


    settings = Settings()

If a project uses settings like ``MYAPP_FRUIT = 'Banana'`` they will continue
to work. As soon as a project switches to ``MYAPP``, any ``MYAPP_*`` settings
will be ignored.

While the legacy app settings class is used, the dictionary settings can still
be accessed via the prefixed setting (for example, ``settings.MYAPP_FRUIT``).

==========
Change Log
==========

2.0.1 (10 August 2019)
======================

- Add Python 3.7 and Django 2.2 to the test matrix.


2.0 (24 April 2018)
===================

- Full rework of project! Import is now
  ``from easysettings.app import AppSettings`` (but left importable from
  ``easysettings`` for better backwards compatibility).

- Removed isolated settings functionality, unnecessary with a separate settings
  module for tests and/or use of the ``TestCase.settings()`` context manager.

- Added ``easysettings.legacy.LegacyAppSettings`` for providing backwards
  compatibility for prefixed project settings when moving settings to a
  dictionary rather than individual settings with the same prefix.

1.1 (4 April 2017)
==================

- Django 1.11 compatibility.

1.0.1 (24 May 2012)
===================

- Included extra source files.

1.0 (16 April 2012)
===================

- Initial release.