# Django Convigvars
Configure your Django project in easy and readable way.
## Description
Configvars gives possibility to configure Django-based project with local file and environment variables (i.e. for Docker containers).
Environmental variables are the most important. If not set, the variables from the `local` module will be used, or if these are not present either - the default values will be used:
```
ENV > LOCAL > DEFAULT
```
## Installation
`pip install git+https://gitlab.com/marcinjn/django-configvars.git`
### Basic configuration
Add `configvars` to your `settings.INSTALLED_APPS`:
```python
INSTALLED_APPS = [
# ...
"configvars",
# ...
]
```
### Quickstart
In your `settings.py` add these lines at the top of the file:
```python
from convigvars import config, secret
SOME_API_KEY = config("SOME_API_KEY", "default_api_key")
SOME_API_SECRET = secret("SOME_API_SECRET", "")
```
Then use local settings to set these values or pass them by environment
variables. To use local file, add these settings to `local.py` file in
the same folder where `settings.py` file is located, and fill it with:
```
SOME_API_KEY = "NEW_API_KEY"
SOME_API_SECRET = "NEW_API_SECRET"
```
To check if they are apllied propely run `manage.py configvars`.
You can override these settings by using environment vars (i.e. for
deployment in containers). To do so just declare an environment variable
as usual:
```
SOME_API_KEY="ENV_API_KEY" manage.py configvars
```
In case of secrets, you should provide a path to the secret file
containing a value:
```
SOME_API_SECRET="/run/secrets/SOME_API_SECRET" manage.py configvars
```
If file does not exist, the path will be interpreted as typical string value.
## Usage
### Config vars declaration
In your `settings.py` file declare configurable variables by using `config` or `secret` functions. The first one is used for regular variables, the second one - for secure variables (like passwords, secrets, etc).
```python
DATABASES = {
"default": {
"NAME": config("DB_NAME", "example"), # `example` as default database name
"USER": config("DB_USER", "postgres"), # `postgres` as default username
"PASSWORD": secret("DB_PASSWORD"),
"HOST": config("DB_HOST", "localhost"), # `localhost` as default host
"PORT": config("DB_PORT", 5432), # `5432` as default port
}
}
```
### Show configurable variables for your project
```bash
python manage.py configvars
```
Should result in something like that:
```
DB_NAME = 'example'
DB_USER = 'postgres'
DB_PASSWORD = None
DB_HOST = 'localhost'
DB_PORT = 5432
```
### Show only changed config variables
To show changed config variables by `local.py` or environment variables use:
```bash
python manage.py configvars --changed
```
### Adding short description to your config variables
In your `settings.py` declare `config` or `secret` with additional `desc` argument:
```python
MY_CUSTOM_VARIABLE = config("MY_CUSTOM_VARIABLE", "default_value", desc="Set's custom variable")
```
Then you can dump your config variables with descriptions:
```bash
$ python manage.py configvars --comment
MY_CUSTOM_VARIABLE = 'default_value' # Set's custom variable
```
### Local settings
Django Configvars will try to import `<projectname>.local` module by
default. By using this file you can customize your config variables -
they will be used as current values.
To do so, create empty `local.py` in directory where your `settings.py` file
is located, then assign values to your variables.
*As local config variables are specific to a local machine, consider adding `local.py` to `.gitignore`.*
Note that:
* Local settings can be overriden by environment variables
* Local settings can be skipped for your project
To change location or name of your local settings file, you must
initialize Django Configvars explicitely in `settings.py` module:
```
from configvars import initialize
initialize("other.location.of.settings_local")
```
### Environment variables
Django Config vars will check at the first whether environment name of
the variable is defined. It is important for deployments in containers,
where configuration variables are passed mostly by environment variables.
If environment variable does not exist, a local variable will be
used. If local value is not defined, a default value will be used.
Environment variables can be prefixed to solve issues with eventual name
conflicts. To do so you must initialize Django Configvars explicitely in
`settings.py` file:
```
from configvars import initialize
initialize(env_prefix="MYPREFIX_")
```
## Support
To ask question please create an issue.
## To do
* better support for type casts
* config vars view for Django Admin
## Contributing
You can contribute by creating issues, feature requests or merge requests.
## Authors and acknowledgment
- Marcin Nowak
## License
ISC License
Copyright (c) 2023 Marcin Nowak
Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/marcinjn/django-configvars",
"name": "django-configvars",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "web python django config settings",
"author": "Marcin Nowak",
"author_email": "marcin.j.nowak@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/be/89/c0289a8f4a10343c500f5844a8e2da9c1a93ba8d0db3118e0a26496b6e2a/django_configvars-0.5.post1.tar.gz",
"platform": null,
"description": "# Django Convigvars\n\nConfigure your Django project in easy and readable way.\n\n## Description\n\nConfigvars gives possibility to configure Django-based project with local file and environment variables (i.e. for Docker containers).\n\nEnvironmental variables are the most important. If not set, the variables from the `local` module will be used, or if these are not present either - the default values will be used:\n\n```\nENV > LOCAL > DEFAULT\n```\n\n## Installation\n\n`pip install git+https://gitlab.com/marcinjn/django-configvars.git`\n\n\n### Basic configuration\n\nAdd `configvars` to your `settings.INSTALLED_APPS`:\n\n```python\n\nINSTALLED_APPS = [\n # ...\n \"configvars\",\n # ...\n]\n```\n\n### Quickstart\n\nIn your `settings.py` add these lines at the top of the file:\n\n```python\nfrom convigvars import config, secret\n\nSOME_API_KEY = config(\"SOME_API_KEY\", \"default_api_key\")\nSOME_API_SECRET = secret(\"SOME_API_SECRET\", \"\")\n```\n\nThen use local settings to set these values or pass them by environment\nvariables. To use local file, add these settings to `local.py` file in\nthe same folder where `settings.py` file is located, and fill it with:\n\n```\nSOME_API_KEY = \"NEW_API_KEY\"\nSOME_API_SECRET = \"NEW_API_SECRET\"\n```\n\nTo check if they are apllied propely run `manage.py configvars`.\n\nYou can override these settings by using environment vars (i.e. for\ndeployment in containers). To do so just declare an environment variable\nas usual:\n\n```\nSOME_API_KEY=\"ENV_API_KEY\" manage.py configvars\n```\n\nIn case of secrets, you should provide a path to the secret file\ncontaining a value:\n\n```\nSOME_API_SECRET=\"/run/secrets/SOME_API_SECRET\" manage.py configvars\n```\n\nIf file does not exist, the path will be interpreted as typical string value.\n\n## Usage\n\n### Config vars declaration\n\nIn your `settings.py` file declare configurable variables by using `config` or `secret` functions. The first one is used for regular variables, the second one - for secure variables (like passwords, secrets, etc).\n\n\n```python\n\nDATABASES = {\n \"default\": {\n \"NAME\": config(\"DB_NAME\", \"example\"), # `example` as default database name\n \"USER\": config(\"DB_USER\", \"postgres\"), # `postgres` as default username\n \"PASSWORD\": secret(\"DB_PASSWORD\"),\n \"HOST\": config(\"DB_HOST\", \"localhost\"), # `localhost` as default host\n \"PORT\": config(\"DB_PORT\", 5432), # `5432` as default port\n }\n}\n```\n\n### Show configurable variables for your project\n\n```bash\npython manage.py configvars\n```\n\nShould result in something like that:\n\n```\nDB_NAME = 'example'\nDB_USER = 'postgres'\nDB_PASSWORD = None\nDB_HOST = 'localhost'\nDB_PORT = 5432\n```\n\n### Show only changed config variables\n\nTo show changed config variables by `local.py` or environment variables use:\n\n```bash\npython manage.py configvars --changed\n```\n\n### Adding short description to your config variables\n\nIn your `settings.py` declare `config` or `secret` with additional `desc` argument:\n\n```python\nMY_CUSTOM_VARIABLE = config(\"MY_CUSTOM_VARIABLE\", \"default_value\", desc=\"Set's custom variable\")\n```\n\nThen you can dump your config variables with descriptions:\n\n```bash\n$ python manage.py configvars --comment\n\nMY_CUSTOM_VARIABLE = 'default_value' # Set's custom variable\n```\n\n### Local settings\n\nDjango Configvars will try to import `<projectname>.local` module by\ndefault. By using this file you can customize your config variables -\nthey will be used as current values.\n\nTo do so, create empty `local.py` in directory where your `settings.py` file\nis located, then assign values to your variables.\n\n*As local config variables are specific to a local machine, consider adding `local.py` to `.gitignore`.*\n\nNote that:\n* Local settings can be overriden by environment variables\n* Local settings can be skipped for your project\n\nTo change location or name of your local settings file, you must\ninitialize Django Configvars explicitely in `settings.py` module:\n\n```\nfrom configvars import initialize\n\ninitialize(\"other.location.of.settings_local\")\n```\n\n### Environment variables\n\nDjango Config vars will check at the first whether environment name of\nthe variable is defined. It is important for deployments in containers,\nwhere configuration variables are passed mostly by environment variables.\n\nIf environment variable does not exist, a local variable will be\nused. If local value is not defined, a default value will be used.\n\nEnvironment variables can be prefixed to solve issues with eventual name\nconflicts. To do so you must initialize Django Configvars explicitely in\n`settings.py` file:\n\n```\nfrom configvars import initialize\n\ninitialize(env_prefix=\"MYPREFIX_\")\n```\n\n## Support\n\nTo ask question please create an issue.\n\n## To do\n\n* better support for type casts\n* config vars view for Django Admin\n\n\n## Contributing\n\nYou can contribute by creating issues, feature requests or merge requests.\n\n## Authors and acknowledgment\n\n- Marcin Nowak\n\n## License\n\nISC License\n\nCopyright (c) 2023 Marcin Nowak\n\nPermission to use, copy, modify, and/or distribute this software for any\npurpose with or without fee is hereby granted, provided that the above\ncopyright notice and this permission notice appear in all copies.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH\nREGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY\nAND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,\nINDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM\nLOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR\nOTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR\nPERFORMANCE OF THIS SOFTWARE.\n",
"bugtrack_url": null,
"license": null,
"summary": "Custom settings management for Django",
"version": "0.5.post1",
"project_urls": {
"Homepage": "https://gitlab.com/marcinjn/django-configvars"
},
"split_keywords": [
"web",
"python",
"django",
"config",
"settings"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6ff84948522158cc06abe9a9d156825b981c67e6ebed96c515591e1821d19ce4",
"md5": "7f2de4615eee4c21436119d4103dce4a",
"sha256": "8e78541d12fdc1543800c2c25b3ca711a30ce19e972487a2e152cad34f6dc6b4"
},
"downloads": -1,
"filename": "django_configvars-0.5.post1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7f2de4615eee4c21436119d4103dce4a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 6663,
"upload_time": "2024-09-19T18:23:38",
"upload_time_iso_8601": "2024-09-19T18:23:38.869249Z",
"url": "https://files.pythonhosted.org/packages/6f/f8/4948522158cc06abe9a9d156825b981c67e6ebed96c515591e1821d19ce4/django_configvars-0.5.post1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "be89c0289a8f4a10343c500f5844a8e2da9c1a93ba8d0db3118e0a26496b6e2a",
"md5": "24a51fa0fc2f218d2aa16036de364d0e",
"sha256": "7ea4a4a930c99d10ac18c12f5d75e1a39fc3d7da0c225942141f91ecace73fdf"
},
"downloads": -1,
"filename": "django_configvars-0.5.post1.tar.gz",
"has_sig": false,
"md5_digest": "24a51fa0fc2f218d2aa16036de364d0e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 6231,
"upload_time": "2024-09-19T18:23:39",
"upload_time_iso_8601": "2024-09-19T18:23:39.987443Z",
"url": "https://files.pythonhosted.org/packages/be/89/c0289a8f4a10343c500f5844a8e2da9c1a93ba8d0db3118e0a26496b6e2a/django_configvars-0.5.post1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-19 18:23:39",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "marcinjn",
"gitlab_project": "django-configvars",
"lcname": "django-configvars"
}
JSON