django-valerie 0.2.0

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

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