<commit_before>|

================================
Storing settings in the database
================================

Not all settings belong in ``settings.py``, as it has some particular
limitations:

    * Settings are project-wide. This not only requires apps to clutter up
      ``settings.py``, but also increases the chances of naming conflicts.

    * Settings are constant throughout an instance of Django. They cannot be
      changed without restarting the application.

    * Settings require a programmer in order to be changed. This is true even
      if the setting has no functional impact on anything else.

Many applications find need to overcome these limitations, and ``dbsettings``
provides a convenient way to do so.

The main goal in using this application is to define a set of placeholders that
will be used to represent the settings that are stored in the database. Then,
the settings may edited at run-time using the provided editor, and all Python
code in your application that uses the setting will receive the updated value.

Requirements
============

+------------------+------------+--------------+
| Dbsettings       | Python     | Django       |
+==================+============+==============+
| >=0.7            | 3.2        | 1.5 - 1.7    |
|                  +------------+--------------+
|                  | 2.7        | 1.3 - 1.7    |
|                  +------------+--------------+
|                  | 2.6        | 1.3 - 1.6    |
+------------------+------------+--------------+
| ==0.6            | 3.2        |       1.5    |
|                  +------------+--------------+
|                  | 2.6 - 2.7  | 1.3 - 1.5    |
+------------------+------------+--------------+
| <=0.5            | 2.6 - 2.7  | 1.2\* - 1.4  |
+------------------+------------+--------------+

\* Possibly version below 1.2 will work too, but not tested.

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

To install the ``dbsettings`` package, simply place it anywhere on your
``PYTHONPATH``.

Project settings
----------------

In order to setup database storage, and to let Django know about your use of
``dbsettings``, simply add it to your ``INSTALLED_APPS`` setting, like so::

    INSTALLED_APPS = (
        ...
        'dbsettings',
        ...
    )

URL Configuration
-----------------

In order to edit your settings at run-time, you'll need to configure a URL to
access the provided editors. You'll just need to add a single line, defining
the base URL for the editors, as ``dbsettings`` has its own URLconf to handle
the rest. You may choose any location you like::

    urlpatterns = patterns('',
        ...
        (r'^settings/', include('dbsettings.urls')),
        ...
    )

A note about caching
--------------------

This framework utilizes Django's built-in `cache framework`_, which is used to
minimize how often the database needs to be accessed. During development,
Django's built-in server runs in a single process, so all cache backends will
work just fine.

Most productions environments, including mod_python and FastCGI, run multiple
processes, which some backends don't fully support. When using the ``simple``
or ``locmem`` backends, updates to your settings won't be reflected immediately,
causing your application to ignore the new changes.

No other backends exhibit this behavior, but since ``simple`` is the default,
make sure to specify a proper backend when moving to a production environment.

.. _`cache framework`: http://www.djangoproject.com/documentation/cache/

Usage
=====

These database-backed settings can be applied to any model in any app, or even
in the app itself. All the tools necessary to do so are available within the
``dbsettings`` module. A single import provides everything you'll need::

    import dbsettings

Defining a group of settings
----------------------------

Settings are be defined in groups that allow them to be referenced together<commit_msg>Update cache docs link (close #12).<commit_after>|

================================
Storing settings in the database
================================

Not all settings belong in ``settings.py``, as it has some particular
limitations:

    * Settings are project-wide. This not only requires apps to clutter up
      ``settings.py``, but also increases the chances of naming conflicts.

    * Settings are constant throughout an instance of Django. They cannot be
      changed without restarting the application.

    * Settings require a programmer in order to be changed. This is true even
      if the setting has no functional impact on anything else.

Many applications find need to overcome these limitations, and ``dbsettings``
provides a convenient way to do so.

The main goal in using this application is to define a set of placeholders that
will be used to represent the settings that are stored in the database. Then,
the settings may edited at run-time using the provided editor, and all Python
code in your application that uses the setting will receive the updated value.

Requirements
============

+------------------+------------+--------------+
| Dbsettings       | Python     | Django       |
+==================+============+==============+
| >=0.7            | 3.2        | 1.5 - 1.7    |
|                  +------------+--------------+
|                  | 2.7        | 1.3 - 1.7    |
|                  +------------+--------------+
|                  | 2.6        | 1.3 - 1.6    |
+------------------+------------+--------------+
| ==0.6            | 3.2        |       1.5    |
|                  +------------+--------------+
|                  | 2.6 - 2.7  | 1.3 - 1.5    |
+------------------+------------+--------------+
| <=0.5            | 2.6 - 2.7  | 1.2\* - 1.4  |
+------------------+------------+--------------+

\* Possibly version below 1.2 will work too, but not tested.

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

To install the ``dbsettings`` package, simply place it anywhere on your
``PYTHONPATH``.

Project settings
----------------

In order to setup database storage, and to let Django know about your use of
``dbsettings``, simply add it to your ``INSTALLED_APPS`` setting, like so::

    INSTALLED_APPS = (
        ...
        'dbsettings',
        ...
    )

URL Configuration
-----------------

In order to edit your settings at run-time, you'll need to configure a URL to
access the provided editors. You'll just need to add a single line, defining
the base URL for the editors, as ``dbsettings`` has its own URLconf to handle
the rest. You may choose any location you like::

    urlpatterns = patterns('',
        ...
        (r'^settings/', include('dbsettings.urls')),
        ...
    )

A note about caching
--------------------

This framework utilizes Django's built-in `cache framework`_, which is used to
minimize how often the database needs to be accessed. During development,
Django's built-in server runs in a single process, so all cache backends will
work just fine.

Most productions environments, including mod_python and FastCGI, run multiple
processes, which some backends don't fully support. When using the ``simple``
or ``locmem`` backends, updates to your settings won't be reflected immediately,
causing your application to ignore the new changes.

No other backends exhibit this behavior, but since ``simple`` is the default,
make sure to specify a proper backend when moving to a production environment.

.. _`cache framework`: http://docs.djangoproject.com/en/dev/topics/cache/

Usage
=====

These database-backed settings can be applied to any model in any app, or even
in the app itself. All the tools necessary to do so are available within the
``dbsettings`` module. A single import provides everything you'll need::

    import dbsettings

Defining a group of settings
----------------------------

Settings are be defined in groups that allow them to be referenced together
{'fraction_non_alphanumeric': 0.1902097902097902, 'fraction_numerical': 0.011951684678957407, 'mean_word_length': 2.093197011403854, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 1, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7673031', 'n_tokens_mistral': 2005, 'n_tokens_neox': 1845, 'n_words': 910}