# Django-app-parameter
App-Parameter is a very simple Django app to save some application's parameters in the database. Those parameters can be updated by users at run time (no need to new deployment or any restart). It can be used to store the website's title or default e-mail expeditor...
## Install
pip install django-app-parameter
## Settings
1. Add "django_app_parameter" to your INSTALLED_APPS setting like this:
```python
INSTALLED_APPS = [
...
"django_app_parameter",
]
```
If you want global parameters to be available in templates, set provided context processor:
```python
TEMPLATES = [
...
"OPTIONS": {
"context_processors": [
...
"django_app_parameter.context_processors.add_global_parameter_context",
],
},
]
```
2. Run `python manage.py migrate` to create the django_app_parameter's table.
3. Start development server and visit http://127.0.0.1:8000/admin/ to create parameters (you'll need the Admin app enabled).
## Usage
### Add new parameters
Use admin interface to add parameters. You can access a parameter in your code use the "slug" field. Slug is built at first save with: `slugify(self.name).upper().replace("-", "_")`.
Examples:
self.name ==> self.slug
blog title ==> BLOG_TITLE
sender e-mail ==> SENDER_E_MAIL
##weird@Na_me ==> WERIDNA_ME
See [Django's slugify function](https://docs.djangoproject.com/fr/4.0/ref/utils/#django.utils.text.slugify) for more informations.
### Access parameter in python code
You can read parameter anywhere in your code:
```python
from django.views.generic import TemplateView
from django_app_parameter import app_parameter
class RandomView(TemplateView):
def get_context_data(self, **kwargs):
kwargs.update({"blog_title": app_parameter.BLOG_TITLE})
return super().get_context_data(**kwargs)
```
In case you try to read a non existent parameter, an ImproperlyConfigured exception is raised.
### Access parameter in templates
You can also access "global" parameters from every templates:
```html
<head>
<title>{{ BLOG_TITLE }}</title>
</head>
```
A to make a parameter global, you only need to check is_global in admin.
### Bulk load parameter with management command
A management command is provided to let you easily load new parameters: `load_param`.
It will create or update, the key for matching is the SLUG.
It accepts 3 parameters: file, json and no-update.
#### Option --file
Add all parameters listed in the provided file.
`load_param --file /path/to/json.file`
Example of file content:
```json
[
{"name": "hello ze world", "value": "yes", "description": "123", "is_global": true},
{"slug": "A8B8C", "name": "back on test", "value": "yes", "value_type": "INT" }
]
```
Here all available property you can add to the json:
* name
* slug
* value_type
* value
* description
* is_global
If slug is not provided it will be built. Default value_type is STR (string) and default is_global is False. Name is always required, others properties are optionnals.
#### Option --json
Add parameters in one shot.
`load_param --json "[{'name': 'param1'}, {'name': 'param2'},]"`
The provided json needs to match same rules as for --file option above.
You can't use --json and --file together.
#### Option --no-update
This option is provided to disable 'update' if parameter with same SLUG already exists. It can be used with --json and --file. It's useful to ensure all parameters are created in all environments and can be executed altogether with migrate. It avoid replacing already existing parameters' values which could lead to breaking environments.
`load_param --no-update --file required_parameters.json`
I use it in my starting container script:
```bash
#!/bin/bash
# Execute migrations
python manage.py migrate
# load new parameters if any
python manage.py load_param --no-update --file required_parameters.json
# launch webserver
gunicorn config.wsgi
```
Enjoy.
## Ideas which could come later (or not)
* [x] A migration process to keep a list of your parameters in a file and automatically add them in each environment
* [x] Shortcut to use Parameter.str(slug) (skip 'objects' key word)
* [x] Management command to add a new parameter
* [] Check correctness of value type on save
* [] modifications history
* [x] Boolean type
* [] Datetime types
If you have new idea you would like to see, feel free to open a new issue in this repo.
## Help developping
If you want to participate to the development, there are (only) 2 constraints:
* Format all your code with black
* All unit test must pass and new code must be covered
Because tests require a whole django environment, to run them I use https://github.com/Swannbm/runtest_on_dj_packages ; if you know a better way to do it I am all ears :D
## Why Django-App-Parameter
Because I wanted to try packaging a Django app and I used this one in most of my projects so it seemed a good idea.
Raw data
{
"_id": null,
"home_page": "https://github.com/Swannbm/django-app-parameter",
"name": "django-app-parameter",
"maintainer": "Swann",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "swann.bouviermuller@gmail.com",
"keywords": "Django,Parameter,Configuration",
"author": "Swann",
"author_email": "swann.bouviermuller@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f2/81/cb98e294dc2d3dfc8e69263ec7c0d919fa33a756ca03f1449abea4faa97c/django_app_parameter-1.1.3.tar.gz",
"platform": null,
"description": "# Django-app-parameter\n\n\n\n\n\n\n\nApp-Parameter is a very simple Django app to save some application's parameters in the database. Those parameters can be updated by users at run time (no need to new deployment or any restart). It can be used to store the website's title or default e-mail expeditor...\n\n## Install\n\n pip install django-app-parameter\n\n## Settings\n\n1. Add \"django_app_parameter\" to your INSTALLED_APPS setting like this:\n\n```python\nINSTALLED_APPS = [\n ...\n \"django_app_parameter\",\n]\n```\n\nIf you want global parameters to be available in templates, set provided context processor:\n\n```python\nTEMPLATES = [\n ...\n \"OPTIONS\": {\n \"context_processors\": [\n ...\n \"django_app_parameter.context_processors.add_global_parameter_context\",\n ],\n },\n]\n```\n\n2. Run `python manage.py migrate` to create the django_app_parameter's table.\n\n3. Start development server and visit http://127.0.0.1:8000/admin/ to create parameters (you'll need the Admin app enabled).\n\n## Usage\n\n### Add new parameters\n\nUse admin interface to add parameters. You can access a parameter in your code use the \"slug\" field. Slug is built at first save with: `slugify(self.name).upper().replace(\"-\", \"_\")`.\n\nExamples:\n\n self.name ==> self.slug\n blog title ==> BLOG_TITLE\n sender e-mail ==> SENDER_E_MAIL\n ##weird@Na_me ==> WERIDNA_ME\n\nSee [Django's slugify function](https://docs.djangoproject.com/fr/4.0/ref/utils/#django.utils.text.slugify) for more informations.\n\n### Access parameter in python code\n\nYou can read parameter anywhere in your code:\n\n```python\nfrom django.views.generic import TemplateView\nfrom django_app_parameter import app_parameter\n\nclass RandomView(TemplateView):\n def get_context_data(self, **kwargs):\n kwargs.update({\"blog_title\": app_parameter.BLOG_TITLE})\n return super().get_context_data(**kwargs)\n```\n\nIn case you try to read a non existent parameter, an ImproperlyConfigured exception is raised.\n\n### Access parameter in templates\n\nYou can also access \"global\" parameters from every templates:\n\n```html\n<head>\n <title>{{ BLOG_TITLE }}</title>\n</head>\n```\n\nA to make a parameter global, you only need to check is_global in admin.\n\n### Bulk load parameter with management command\n\nA management command is provided to let you easily load new parameters: `load_param`.\n\nIt will create or update, the key for matching is the SLUG.\n\nIt accepts 3 parameters: file, json and no-update.\n\n#### Option --file\n\nAdd all parameters listed in the provided file.\n\n`load_param --file /path/to/json.file`\n\nExample of file content:\n\n```json\n[\n {\"name\": \"hello ze world\", \"value\": \"yes\", \"description\": \"123\", \"is_global\": true},\n {\"slug\": \"A8B8C\", \"name\": \"back on test\", \"value\": \"yes\", \"value_type\": \"INT\" }\n]\n```\n\nHere all available property you can add to the json:\n* name\n* slug\n* value_type\n* value\n* description\n* is_global\n\nIf slug is not provided it will be built. Default value_type is STR (string) and default is_global is False. Name is always required, others properties are optionnals.\n\n#### Option --json\n\nAdd parameters in one shot.\n\n`load_param --json \"[{'name': 'param1'}, {'name': 'param2'},]\"`\n\nThe provided json needs to match same rules as for --file option above.\n\nYou can't use --json and --file together.\n\n#### Option --no-update\n\nThis option is provided to disable 'update' if parameter with same SLUG already exists. It can be used with --json and --file. It's useful to ensure all parameters are created in all environments and can be executed altogether with migrate. It avoid replacing already existing parameters' values which could lead to breaking environments.\n\n`load_param --no-update --file required_parameters.json`\n\nI use it in my starting container script:\n```bash\n#!/bin/bash\n\n# Execute migrations\npython manage.py migrate\n\n# load new parameters if any\npython manage.py load_param --no-update --file required_parameters.json\n\n# launch webserver\ngunicorn config.wsgi\n```\n\nEnjoy.\n\n## Ideas which could come later (or not)\n\n* [x] A migration process to keep a list of your parameters in a file and automatically add them in each environment\n* [x] Shortcut to use Parameter.str(slug) (skip 'objects' key word)\n* [x] Management command to add a new parameter\n* [] Check correctness of value type on save\n* [] modifications history\n* [x] Boolean type\n* [] Datetime types\n\nIf you have new idea you would like to see, feel free to open a new issue in this repo.\n\n## Help developping\n\nIf you want to participate to the development, there are (only) 2 constraints:\n* Format all your code with black\n* All unit test must pass and new code must be covered\n\nBecause tests require a whole django environment, to run them I use https://github.com/Swannbm/runtest_on_dj_packages ; if you know a better way to do it I am all ears :D\n\n## Why Django-App-Parameter\n\nBecause I wanted to try packaging a Django app and I used this one in most of my projects so it seemed a good idea.",
"bugtrack_url": null,
"license": "CC0 1.0 Universal",
"summary": "App-Parameter is a very simple Django app to save application's parameter in the database.",
"version": "1.1.3",
"project_urls": {
"Homepage": "https://github.com/Swannbm/django-app-parameter",
"Repository": "https://github.com/Swannbm/django-app-parameter",
"issues": "https://github.com/hackersandslackers/python-poetry-tutorial/issues"
},
"split_keywords": [
"django",
"parameter",
"configuration"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3c4af5bca86030a58b0d08572436aae00359e1c2487500a45adf1a44e7bbc22a",
"md5": "3f430b4a2b9377b85321098b23fadd1f",
"sha256": "17367c92e8f664dd9c61de2ad1f3f25efd5082e8b5ea36a3983b32d36c671bf4"
},
"downloads": -1,
"filename": "django_app_parameter-1.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3f430b4a2b9377b85321098b23fadd1f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 15426,
"upload_time": "2023-10-18T08:20:12",
"upload_time_iso_8601": "2023-10-18T08:20:12.980650Z",
"url": "https://files.pythonhosted.org/packages/3c/4a/f5bca86030a58b0d08572436aae00359e1c2487500a45adf1a44e7bbc22a/django_app_parameter-1.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f281cb98e294dc2d3dfc8e69263ec7c0d919fa33a756ca03f1449abea4faa97c",
"md5": "76e3f75f8d731ee87ec47892191d2956",
"sha256": "d30e34f1db49b9b9f5a7ac09c7b39d7f8c77cc87a912831843b1465a142fac13"
},
"downloads": -1,
"filename": "django_app_parameter-1.1.3.tar.gz",
"has_sig": false,
"md5_digest": "76e3f75f8d731ee87ec47892191d2956",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 14102,
"upload_time": "2023-10-18T08:20:15",
"upload_time_iso_8601": "2023-10-18T08:20:15.654652Z",
"url": "https://files.pythonhosted.org/packages/f2/81/cb98e294dc2d3dfc8e69263ec7c0d919fa33a756ca03f1449abea4faa97c/django_app_parameter-1.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-18 08:20:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Swannbm",
"github_project": "django-app-parameter",
"travis_ci": false,
"coveralls": true,
"github_actions": false,
"lcname": "django-app-parameter"
}
JSON
