<commit_before>``django-settings-export``
##########################


|version| |travis| |coverage|


Often it is needed to make some of your Django project's settings
accessible from within templates. This app provides a simple mechanism
for doing just that.


**Principles:**

* *Explicit is better than implicit:* Only explicitly listed
  settings keys are exported to templates.
* *Errors should never pass silently:* Accessing an undefined
  or unexported setting key from a template results in an exception.


Tested on Python 2.7+, Django 1.5+.


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

.. code-block:: bash

    $ pip install django-settings-export


Add ``'django_settings_export.settings_export'`` to
template context processor list in your ``settings.py``:

**Django 1.8 and newer:**

.. code-block:: python

    TEMPLATES = [
        {
            # …
            'OPTIONS': {
                'context_processors': [
                    # …
                    'django_settings_export.settings_export',
                ],
            },
        },
    ]

**Django older than 1.8:**

.. code-block:: python

    TEMPLATE_CONTEXT_PROCESSORS = [
        # [...]
        'django_settings_export.settings_export',
    ]



Usage
=====

All settings that should be made accessible from templates need to be
explicitly listed in ``settings.SETTINGS_EXPORT``:


.. code-block:: python

    # settings.py

    DEBUG = True
    GA_ID = 'UA-00000-0'

    SETTINGS_EXPORT = [
        'DEBUG',
        'GA_ID',
    ]



Now you can access those exported settings from your templates
via ``settings.<KEY>``:


.. code-block:: html

    <!-- template.html -->

    {% if not settings.DEBUG %}
        <script>ga('create', '{{ settings.GA_ID }}', 'auto');</script>
    {% endif %}


Changing the variable name
--------------------------

If you wish to change the name of the context variable to something besides
``settings``, add ``SETTINGS_EXPORT_VARIABLE_NAME = 'custom_name'``
to your ``settings.py``. This is useful when some other plugin is already adding
``settings`` to your template contexts.


.. code-block:: python

    # settings.py
    FOO = 'bar'
    SETTINGS_EXPORT = ['FOO']
    SETTINGS_EXPORT_VARIABLE_NAME = 'my_config'



.. code-block:: html

    <!-- template.html -->

    {{ my_config.FOO }}


Exceptions
----------

* Listing an undefined setting key in ``SETTINGS_EXPORT`` results in an
  ``UndefinedSettingError``.
* Accessing a unexported setting key on the ``settings`` object in a template
  results in an ``UnexportedSettingError``.



Demo
----

See the source code of the bundled
`demo app <https://github.com/jkbrzt/django-settings-export/tree/master/demo>`_.
<commit_msg>Mention the base exception class<commit_after>``django-settings-export``
##########################


|version| |travis| |coverage|


Often it is needed to make some of your Django project's settings
accessible from within templates. This app provides a simple mechanism
for doing just that.


**Principles:**

* *Explicit is better than implicit:* Only explicitly listed
  settings keys are exported to templates.
* *Errors should never pass silently:* Accessing an undefined
  or unexported setting key from a template results in an exception.


Tested on Python 2.7+, Django 1.5+.


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

.. code-block:: bash

    $ pip install django-settings-export


Add ``'django_settings_export.settings_export'`` to
template context processor list in your ``settings.py``:

**Django 1.8 and newer:**

.. code-block:: python

    TEMPLATES = [
        {
            # …
            'OPTIONS': {
                'context_processors': [
                    # …
                    'django_settings_export.settings_export',
                ],
            },
        },
    ]

**Django older than 1.8:**

.. code-block:: python

    TEMPLATE_CONTEXT_PROCESSORS = [
        # [...]
        'django_settings_export.settings_export',
    ]



Usage
=====

All settings that should be made accessible from templates need to be
explicitly listed in ``settings.SETTINGS_EXPORT``:


.. code-block:: python

    # settings.py

    DEBUG = True
    GA_ID = 'UA-00000-0'

    SETTINGS_EXPORT = [
        'DEBUG',
        'GA_ID',
    ]



Now you can access those exported settings from your templates
via ``settings.<KEY>``:


.. code-block:: html

    <!-- template.html -->

    {% if not settings.DEBUG %}
        <script>ga('create', '{{ settings.GA_ID }}', 'auto');</script>
    {% endif %}


Changing the variable name
--------------------------

If you wish to change the name of the context variable to something besides
``settings``, add ``SETTINGS_EXPORT_VARIABLE_NAME = 'custom_name'``
to your ``settings.py``. This is useful when some other plugin is already adding
``settings`` to your template contexts.


.. code-block:: python

    # settings.py
    FOO = 'bar'
    SETTINGS_EXPORT = ['FOO']
    SETTINGS_EXPORT_VARIABLE_NAME = 'my_config'



.. code-block:: html

    <!-- template.html -->

    {{ my_config.FOO }}


Exceptions
----------

These custom exceptions can be thrown:

* Listing an undefined setting key in ``SETTINGS_EXPORT`` results in an
  ``UndefinedSettingError``.
* Accessing a unexported setting key on the ``settings`` object in a template
  results in an ``UnexportedSettingError``.

All subclass from ``django_settings_export.SettingsExportError``.




Demo
----

See the source code of the bundled
`demo app <https://github.com/jkbrzt/django-settings-export/tree/master/demo>`_.

{'fraction_non_alphanumeric': 0.13845037198330612, 'fraction_numerical': 0.005080747595717656, 'mean_word_length': 2.7547683923705724, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 15, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, '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': '5156839', 'n_tokens_mistral': 1684, 'n_tokens_neox': 1543, 'n_words': 508}