django-valerie 0.2.0
A Django app that provides a singleton model so you can store your settings in the database.
License: BSD 3-Clause License
Requires Python: >=3.6
Keywords: Django,Settings,Singleton

==============
Django Valerie
==============

A Django app that provides a singleton model so you can store your settings
in the database.

Supports Python 3.6-3.8 or later and Django 2.2-3.1.


Quickstart
==========

Install the app using pip::

    pip install django-valerie

Add it to your installed apps::

    INSTALLED_APPS = [
      ...
      'valerie',
    ]

Create a model for your settings, for example::

    # models.py
    from django.db import models

    from valerie.models import Settings


    class MySettings(Settings):

        site = models.CharField(max_length=50)
        logo = models.FileField(upload_to="files")
        comments = models.BooleanField()

        def get_initial(cls):
            initial = super().get_initial()
            initial["site"] = "My Awesome Site"
            initial["comments"] = True
            return initial

Now register the settings with the Django Admin::

    from django.contrib import admin

    from valerie.admin import SettingsAdmin

    from .models import MySettings


    @admin.register(MySettings)
    class MySettingsAdmin(SettingsAdmin):
        pass

The record is added, using the defaults, to the database on demand so
you can immediately use the settings in your code without needing to
do any migrations::

    settings = MySettings.fetch()

Or in a template by giving the `<app>.<model>` path::

    {% load valerie_tags %}

    {% valerie_settings "myapp.MySettings" as settings %}

You can now turn over control to your site admin staff to update the values.

Caching
=======
If you have caching enabled there are three settings which control whether
and where the settings object is cached and for how long:::

    SETTINGS_CACHE_NAME = 'default'

    SETTINGS_CACHE_TIMEOUT = 60 * 60  # 1 hour

    SETTINGS_CACHE_PREFIX = "settings"

The default stores the settings in the `default` cache for 1 hour (which seems
reasonable given they should change relatively slowly).

The cache is refreshed whenever a settings object is accessed and the cache
entry had expired. The cache is also updated every time a settings object is
saved.

The settings are defined on the Settings class but you can override some or all
of these in the Django settings.

Sensible defaults
=================
The default values for each required field in your settings model can be
selectively overridden in the Django setting `SETTINGS_DEFAULTS`. This is a
dictionary so it can contain entries for each `Settings` class::

    SETTINGS_DEFAULTS = {
        "MySettings": {
            "site": "My New Awesome Site",
            "comments": False,
        }
    }

That make it easy to use `django-valerie` in an app you distribute as your
sensible defaults can be overridden as needed.

Demo site
=========
If you check out the code from the repository, the project contains a demo
site with an example app that contains concrete subclass of the `Settings`
class so you can see how django-valerie works.

Make it so
==========
The project has a ``Makefile`` that contains a number of targets to support the
development process. The most useful are probably `tests` for running the tests
and `runserver` for running the demo site to show the Django Admin site. There
is also a set of targets to manage the release process.

You can read a brief description by running ``make`` on the command line::

    Please use `make <target>' where <target> is one of:

    @echo ""
    @echo "  help                 to show this list"
    @echo "  clean-build          to clean the files and directories generated by previous builds"
    @echo "  clean-docs           to clean the generated HTML documentation"
    @echo "  clean-tests          to clean the directories created during testing"
    @echo "  clean-coverage       to clean the test coverage data and reports"
    @echo "  clean-venv           to clean the virtualenv"
    @echo "  clean                to clean everything EXCEPT the virtualenv"
    @echo
    @echo "  build                to build the package"
    @echo "  checks               to run quality code checks"
    @echo "  coverage             to measure the test coverage"
    @echo "  docs                 to build the HTML documentation"
    @echo "  major                to update the version number for a major release, e.g. 2.1 to 3.0"
    @echo "  messages             to run the makemessages and compilemessages management commands"
    @echo "  migrate              to run migrate management command"
    @echo "  migrations           to run makemigrations management command"
    @echo "  minor                to update the version number for a minor release, e.g. 2.1 to 2.2"
    @echo "  patch                to update the version number for a patch release, e.g. 2.1.1 to 2.1.2"
    @echo "  runserver            to run the Django demo site"
    @echo "  test                 to run the tests during development"
    @echo "  test-all             to run the tests for all the supported environments"
    @echo "  upload               to upload a release to PyPI repository"
    @echo "  venv                 to create the virtualenv and install dependencies"


Similar to
==========

* `django-solo`_

.. _django-solo: https://github.com/lazybird/django-solo