# Django Preferences Utils
[](https://travis-ci.com/github/otto-torino/django-preferences-utils)
[](https://pepy.tech/project/django-preferences-utils)
All you need to manage your django project preferences.
## Motivation
So you need to manage your django project preferences.
You tried many different solutions bu no one seemed to work well.
And then you came across this one.
Let's talk about it.
There is nothing special about managing preferences in Django. A simple model is everything you need.
The problem is that you just need one record, isn't it?
And you don't want to have an ugly changelist view with just one row.
Nothing special, you can solve it, but it's boring.
So here comes Django Preferences Utils.
**You define your preferences in a model, use everything you want: file fields, image fields, json fields, translations, everything.
Just make sure to subclass what you have to as explained below, register your model and you're done. All the other stuff is taken care of by Django Preferences Utils.**
**Oh, and you can also define multiple models for your preferences.**
## How to
Install Django Preferences Utils
``` bash
$ pip install django-preferences-utils
```
Add it to your `INSTALLED_APPS`:
``` python
INSTALLED_APPS = (
...
'django_preferences_utils',
...
)
```
Create your preferences model:
``` python
from django.db import models
from preferences_utils.models import PreferencesUtilsModel
# "pref" is the name used internally to ref this particular model
# and is also the key used by the context processor and accessible in all your templates
@PreferencesUtilsModel.register("pref")
class Preferences(PreferencesUtilsModel):
site_title = models.CharField(_('site title'), max_length=100, default="The best site in the world", blank=True)
class Meta:
verbose_name = _("site settings")
```
> Important: Django Preferences Utils will save your model by itself when requiring a preferences instance. So be sure to have only nullable fields or fields with a default value.
Now probably you want to register you model in the admin:
``` python
from django.contrib import admin
from preferences_utils.admin import PreferencesUtilsAdmin
from .models import Preferences
@admin.register(Preferences)
class PreferencesNewAdmin(PreferencesUtilsAdmin):
list_display = ('id', 'site_title', ) # whatever, is never shown
fieldsets = (
(_('Main'), {
'fields': ("site_title",),
"classes": ("baton-tabs-init",), # django-baton, you should use it ;)
}),
)
```
And propbably you need to use your preferences...
Inside a view:
``` python
from django.views.generic import View
from .models import Preferences
class MyView(View):
pref = Preferences.instance()
# or PreferencesUtilsModel.instance("pref")
# ...
```
Or inside a template, in this case add to your context processors in your settings:
``` python
TEMPLATES = [
# ...
"OPTIONS": {
# ...
"context_processors": [
# ...
# notice the "pref" part at the end, this is the name used when registering your model
"preferences_utils.context_processors.preferences.pref",
],
}
]
```
And now you can use your preferences in your templates.
``` html
<h1>{{ pref.site_title }}</h1>
```
## How it works
Django Preferences Utils provides a few things:
- A model to subclass which assures you have only one instance in your database
- The same model class provides a class method to retrieve the instance
- Registering your model to Django Preferences Utils allows you to have multiple preferences models and customize the name used in the context
- An admin model to subclass which provides a custom changelist view
- A context processor to retrieve your preferences
## Running Tests
Does the code actually work?
``` bash
$ source <YOURVIRTUALENV>/bin/activate
(myenv) $ pip install -r requirements_test.txt
(myenv) $ python runtests.py
```
## Development commands
``` bash
pip install -r requirements_dev.txt
invoke -l
```
## Credits
Django Preferences Utils is developed by Otto SRL.
# History
## 0.1.0 (2024-06-14)
- First release on PyPI.
Raw data
{
"_id": null,
"home_page": "https://github.com/otto-torino/django-preferences-utils",
"name": "django-preferences-utils",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "django-preferences-utils",
"author": "abidibo",
"author_email": "abidibo@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/96/71/c0fa00a46131235b0659f23138f1423fb5c9d661b9877c10cbdbbe99bdc6/django_preferences_utils-0.1.0.tar.gz",
"platform": null,
"description": "# Django Preferences Utils\n\n\n[](https://travis-ci.com/github/otto-torino/django-preferences-utils)\n\n[](https://pepy.tech/project/django-preferences-utils)\n\n\n\nAll you need to manage your django project preferences.\n\n## Motivation\n\nSo you need to manage your django project preferences. \nYou tried many different solutions bu no one seemed to work well. \nAnd then you came across this one. \nLet's talk about it. \n\nThere is nothing special about managing preferences in Django. A simple model is everything you need. \nThe problem is that you just need one record, isn't it? \nAnd you don't want to have an ugly changelist view with just one row. \nNothing special, you can solve it, but it's boring.\n\nSo here comes Django Preferences Utils.\n\n**You define your preferences in a model, use everything you want: file fields, image fields, json fields, translations, everything.\nJust make sure to subclass what you have to as explained below, register your model and you're done. All the other stuff is taken care of by Django Preferences Utils.**\n\n**Oh, and you can also define multiple models for your preferences.**\n\n## How to\n\nInstall Django Preferences Utils\n\n``` bash \n$ pip install django-preferences-utils\n```\n\nAdd it to your `INSTALLED_APPS`:\n\n``` python \n INSTALLED_APPS = (\n ...\n 'django_preferences_utils',\n ...\n )\n```\n\nCreate your preferences model:\n\n``` python\nfrom django.db import models\nfrom preferences_utils.models import PreferencesUtilsModel\n\n# \"pref\" is the name used internally to ref this particular model\n# and is also the key used by the context processor and accessible in all your templates\n@PreferencesUtilsModel.register(\"pref\")\nclass Preferences(PreferencesUtilsModel):\n site_title = models.CharField(_('site title'), max_length=100, default=\"The best site in the world\", blank=True)\n\n class Meta:\n verbose_name = _(\"site settings\")\n```\n\n> Important: Django Preferences Utils will save your model by itself when requiring a preferences instance. So be sure to have only nullable fields or fields with a default value.\n\nNow probably you want to register you model in the admin:\n\n``` python\nfrom django.contrib import admin\nfrom preferences_utils.admin import PreferencesUtilsAdmin\nfrom .models import Preferences\n\n@admin.register(Preferences)\nclass PreferencesNewAdmin(PreferencesUtilsAdmin):\n list_display = ('id', 'site_title', ) # whatever, is never shown\n\n fieldsets = (\n (_('Main'), {\n 'fields': (\"site_title\",),\n \"classes\": (\"baton-tabs-init\",), # django-baton, you should use it ;)\n }),\n )\n```\n\nAnd propbably you need to use your preferences...\n\nInside a view:\n\n``` python \nfrom django.views.generic import View\nfrom .models import Preferences\n\nclass MyView(View):\n pref = Preferences.instance()\n # or PreferencesUtilsModel.instance(\"pref\")\n # ...\n```\n\nOr inside a template, in this case add to your context processors in your settings:\n\n``` python\nTEMPLATES = [\n # ...\n \"OPTIONS\": {\n # ...\n \"context_processors\": [\n # ...\n # notice the \"pref\" part at the end, this is the name used when registering your model\n \"preferences_utils.context_processors.preferences.pref\",\n ],\n }\n]\n```\n\nAnd now you can use your preferences in your templates.\n\n``` html \n <h1>{{ pref.site_title }}</h1>\n```\n\n## How it works\n\nDjango Preferences Utils provides a few things:\n\n- A model to subclass which assures you have only one instance in your database\n- The same model class provides a class method to retrieve the instance\n- Registering your model to Django Preferences Utils allows you to have multiple preferences models and customize the name used in the context\n- An admin model to subclass which provides a custom changelist view\n- A context processor to retrieve your preferences\n\n## Running Tests\n\nDoes the code actually work?\n\n``` bash\n$ source <YOURVIRTUALENV>/bin/activate\n(myenv) $ pip install -r requirements_test.txt\n(myenv) $ python runtests.py\n```\n\n\n## Development commands\n\n``` bash\npip install -r requirements_dev.txt\ninvoke -l\n```\n\n## Credits\n\nDjango Preferences Utils is developed by Otto SRL.\n\n\n# History\n\n## 0.1.0 (2024-06-14)\n\n- First release on PyPI.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "All you need for your django project settings",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/otto-torino/django-preferences-utils",
"Source": "https://github.com/otto-torino/django-preferences-utils",
"Tracker": "https://github.com/otto-torino/django-preferences-utils/issues"
},
"split_keywords": [
"django-preferences-utils"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a6659d989dba9e5bb24ef1dad06933ed17c41002130473de96be09597d03813f",
"md5": "b183f8a279870d9da9b34dd1b41d9c1a",
"sha256": "5e52b9813ba0e3b039977730188b17ea5fd6425845c7c006da27fcc533dd81a4"
},
"downloads": -1,
"filename": "django_preferences_utils-0.1.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "b183f8a279870d9da9b34dd1b41d9c1a",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 7987,
"upload_time": "2024-06-14T16:11:07",
"upload_time_iso_8601": "2024-06-14T16:11:07.400744Z",
"url": "https://files.pythonhosted.org/packages/a6/65/9d989dba9e5bb24ef1dad06933ed17c41002130473de96be09597d03813f/django_preferences_utils-0.1.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9671c0fa00a46131235b0659f23138f1423fb5c9d661b9877c10cbdbbe99bdc6",
"md5": "6cd1d36fe37869654ba198a257d4e809",
"sha256": "4060b626e417377c3d39d9b0220583854edd1bfc4a7c6160500b6d8a6bccb24e"
},
"downloads": -1,
"filename": "django_preferences_utils-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "6cd1d36fe37869654ba198a257d4e809",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 9453,
"upload_time": "2024-06-14T16:11:09",
"upload_time_iso_8601": "2024-06-14T16:11:09.315243Z",
"url": "https://files.pythonhosted.org/packages/96/71/c0fa00a46131235b0659f23138f1423fb5c9d661b9877c10cbdbbe99bdc6/django_preferences_utils-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-14 16:11:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "otto-torino",
"github_project": "django-preferences-utils",
"travis_ci": true,
"coveralls": true,
"github_actions": false,
"tox": true,
"lcname": "django-preferences-utils"
}
JSON
