.. contents::
.. sectnum::
What is it?
-----------
If you are a Python developer who likes to keep application configuration in simple Python modules and that your app have some default settings and production/dev/test setting files, **converge** can help you merge settings and start the application with desired settings based on environment variables.
Getting started
----------------
Easy to use
~~~~~~~~~~~~
.. code:: bash
./settings/default_settings.py
-------------------
SERVER_PORT = 8000
DOMAIN = 'example.com'
ADMIN_EMAIL = 'admin@example.com'
./settings/dev_settings.py
---------------
SERVER_PORT = 9000
.. code:: python
import settings
print(settings.SERVER_PORT) # 9000
print(settings.DOMAIN) # example.com
print(settings.get('VAR_THAT_DOESNT_EXIST')) # None
Install
~~~~~~~
.. code:: bash
pip install converge
Supported environment variables
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
_All directives are optional._
**APP_MODE**
Valid values are
- dev (default)
- test
- staging
- beta
- prod
Based on ``mode`` appropriate settings module would be used (if available)
**SETTINGS_DIR**
Defaults to "settings".
If your settings files are in different directory, use SETTINGS_DIR to point converge to correct path.
.. note:: Remember to drop __init__.py in settings directory.
**GIT_SETTINGS_REPO**
Fetching application settings from a git repository is supported too. If such configuration is specified, git repository is cloned into `SETTINGS_DIR`.
**GIT_SETTINGS_SUBDIR**
In case you
- use same git repository to host configurations of more than one applications and
- say settings files are in different subdirectories
Example
::
my-git-repo/
|
|- myapp1
| |
| |- default_settings.py
| |- prod_settings.py
|
|
|- myapp2
::
export SETTINGS_DIR='appsettings'
export GIT_SETTINGS_REPO='git@github.com:shon/converge-test-settings.git'
export GIT_SETTINGS_SUBDIR='myapp1'
In this case all \*_settings.py files in myapp1/ would be copied to appsettings.
**Example**
::
export APP_MODE='test'
export SETTINGS_DIR='settings'
export GIT_SETTINGS_REPO='git@github.com:shon/converge-test-settings.git'
export GIT_SETTINGS_SUBDIR='myapp1'
Supported settings files
-------------------------
- Defaults: default_settings.py
- Mode
- production: prod_settings.py
- development: dev_settings.py
- test: test_settings.py
- staging: staging_settings.py
- beta: beta_settings.py
- Deployment specific: site_settings.py
Guidelines
-----------
Settings files are usual Python files that can contain valid python code however here are some guidelines for user
- Use module variables for global application wide configuration
- Use UPPERCASE while naming settings variables
- For values prefer basic python datatypes such as string, integer,
tuples
- eg. ``SERVER_PORT = 1234``
- Avoid complex python operations
- Use simple classes for config sections
.. code:: python
class DB:
HOST = 'db.example.com'
PORT = 1234
- Use simple string operations to avoid repetition
.. code:: python
BASE_DOMAIN = 'example.com'
API_URL = 'api.' + BASE_DOMAIN``
Overriding settings
-------------------
Defining module veriables in site_settings.py
Example
~~~~~~~
**default_settings.py**
``SERVER_PORT = 9999``
**site_settings.py**
``SERVER_PORT = 8888``
Overriding partial settings
---------------------------
Example:
**default_settings.py**
.. code:: python
class DB:
HOST = 'db.example.com'
PORT = 1234
**site_settings.py**
.. code:: python
DB.PORT = 1111
(Slightly) Advanced usage
---------------------------
In case if you want to keep all settings.py files in a directory. Use `SETTINGS_DIR` environment variable.
Using SETTINGS_DIR
~~~~~~~~~~~~~~~~~~
.. code:: bash
export APP_MODE='prod'
export SETTINGS_DIR='settings/fat_server'
This is useful when you have to deploy multiple instances of an app with different configs
::
`-- settings/
|
|-- server1/
| |
| |--default_settings.py
| |--prod_settings.py
|
|-- server2/
| |--default_settings.py
| |--prod_settings.py
|
|
Raw data
{
"_id": null,
"home_page": "http://pypi.python.org/pypi/converge/",
"name": "converge",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": "",
"keywords": "",
"author": "Shekhar Tiwatne",
"author_email": "pythonic@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/52/39/b194ede7ac95869a80e50704c2309413a3eb0ec3c85a574af2b6190963e3/converge-1.1.1.tar.gz",
"platform": null,
"description": ".. contents::\n.. sectnum::\n\n\nWhat is it?\n-----------\n\nIf you are a Python developer who likes to keep application configuration in simple Python modules and that your app have some default settings and production/dev/test setting files, **converge** can help you merge settings and start the application with desired settings based on environment variables.\n\n\nGetting started\n----------------\n\nEasy to use\n~~~~~~~~~~~~\n\n.. code:: bash\n\n ./settings/default_settings.py\n -------------------\n SERVER_PORT = 8000\n DOMAIN = 'example.com'\n ADMIN_EMAIL = 'admin@example.com'\n\n ./settings/dev_settings.py\n ---------------\n SERVER_PORT = 9000\n\n\n.. code:: python\n\n import settings\n print(settings.SERVER_PORT) # 9000\n print(settings.DOMAIN) # example.com\n print(settings.get('VAR_THAT_DOESNT_EXIST')) # None\n\n\nInstall\n~~~~~~~\n\n.. code:: bash\n\n pip install converge\n\nSupported environment variables\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n_All directives are optional._\n\n**APP_MODE**\n\nValid values are\n\n- dev (default)\n- test\n- staging\n- beta\n- prod\n\nBased on ``mode`` appropriate settings module would be used (if available)\n\n**SETTINGS_DIR**\n\nDefaults to \"settings\".\n\nIf your settings files are in different directory, use SETTINGS_DIR to point converge to correct path.\n\n.. note:: Remember to drop __init__.py in settings directory.\n\n\n**GIT_SETTINGS_REPO**\n\nFetching application settings from a git repository is supported too. If such configuration is specified, git repository is cloned into `SETTINGS_DIR`.\n\n**GIT_SETTINGS_SUBDIR**\n\nIn case you \n- use same git repository to host configurations of more than one applications and\n- say settings files are in different subdirectories\n\nExample\n\n::\n\n my-git-repo/\n |\n |- myapp1\n | |\n | |- default_settings.py\n | |- prod_settings.py\n |\n |\n |- myapp2\n\n::\n\n export SETTINGS_DIR='appsettings'\n export GIT_SETTINGS_REPO='git@github.com:shon/converge-test-settings.git'\n export GIT_SETTINGS_SUBDIR='myapp1'\n\nIn this case all \\*_settings.py files in myapp1/ would be copied to appsettings.\n\n\n**Example**\n\n::\n\n export APP_MODE='test'\n export SETTINGS_DIR='settings'\n export GIT_SETTINGS_REPO='git@github.com:shon/converge-test-settings.git'\n export GIT_SETTINGS_SUBDIR='myapp1'\n\n\nSupported settings files\n-------------------------\n\n- Defaults: default_settings.py\n\n- Mode\n - production: prod_settings.py\n - development: dev_settings.py\n - test: test_settings.py\n - staging: staging_settings.py\n - beta: beta_settings.py\n\n- Deployment specific: site_settings.py\n\n\nGuidelines\n-----------\n\nSettings files are usual Python files that can contain valid python code however here are some guidelines for user\n\n- Use module variables for global application wide configuration\n- Use UPPERCASE while naming settings variables\n- For values prefer basic python datatypes such as string, integer,\n tuples\n- eg. ``SERVER_PORT = 1234``\n- Avoid complex python operations\n- Use simple classes for config sections\n .. code:: python\n\n class DB:\n HOST = 'db.example.com'\n PORT = 1234\n\n- Use simple string operations to avoid repetition\n .. code:: python\n\n BASE_DOMAIN = 'example.com'\n API_URL = 'api.' + BASE_DOMAIN``\n\nOverriding settings\n-------------------\n\nDefining module veriables in site_settings.py\n\nExample\n~~~~~~~\n\n**default_settings.py**\n\n``SERVER_PORT = 9999``\n\n**site_settings.py**\n\n``SERVER_PORT = 8888``\n\nOverriding partial settings\n---------------------------\n\nExample:\n\n**default_settings.py**\n\n.. code:: python\n\n class DB:\n HOST = 'db.example.com'\n PORT = 1234\n\n**site_settings.py**\n\n.. code:: python\n\n DB.PORT = 1111\n\n(Slightly) Advanced usage\n---------------------------\nIn case if you want to keep all settings.py files in a directory. Use `SETTINGS_DIR` environment variable.\n\nUsing SETTINGS_DIR\n~~~~~~~~~~~~~~~~~~\n\n\n.. code:: bash\n\n export APP_MODE='prod'\n export SETTINGS_DIR='settings/fat_server'\n\nThis is useful when you have to deploy multiple instances of an app with different configs\n\n::\n\n `-- settings/\n |\n |-- server1/\n | |\n | |--default_settings.py\n | |--prod_settings.py\n |\n |-- server2/\n | |--default_settings.py\n | |--prod_settings.py\n |\n |\n\n\n",
"bugtrack_url": null,
"license": "http://www.opensource.org/licenses/mit-license.php",
"summary": "Ultra simple settings management for (only) Python apps",
"version": "1.1.1",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "53b33cc049d71792b1b35387821e8d58",
"sha256": "b4f06e3a1fc7106ff3ebc3031e2eb3b33a72cf9237e1211470c700a04a058b4e"
},
"downloads": -1,
"filename": "converge-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "53b33cc049d71792b1b35387821e8d58",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 4952,
"upload_time": "2022-12-15T11:54:43",
"upload_time_iso_8601": "2022-12-15T11:54:43.119674Z",
"url": "https://files.pythonhosted.org/packages/52/39/b194ede7ac95869a80e50704c2309413a3eb0ec3c85a574af2b6190963e3/converge-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-15 11:54:43",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "converge"
}
JSON