1 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.

2 Getting started

2.1 Easy to use

./settings/default_settings.py
-------------------
SERVER_PORT = 8000
DOMAIN = 'example.com'
ADMIN_EMAIL = 'admin@example.com'

./settings/dev_settings.py
---------------
SERVER_PORT = 9000

import settings
print(settings.SERVER_PORT)  # 9000
print(settings.DOMAIN)  # example.com
print(settings.get('VAR_THAT_DOESNT_EXIST'))  # None

2.2 Install

pip install converge

2.3 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.

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'

3 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

4 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

class DB:
    HOST = 'db.example.com'
    PORT = 1234

Use simple string operations to avoid repetition

BASE_DOMAIN = 'example.com'
API_URL = 'api.' + BASE_DOMAIN``

5 Overriding settings

Defining module veriables in site_settings.py

5.1 Example

default_settings.py

SERVER_PORT = 9999

site_settings.py

SERVER_PORT = 8888

6 Overriding partial settings

Example:

default_settings.py

class DB:
    HOST = 'db.example.com'
    PORT = 1234

site_settings.py

DB.PORT = 1111

7 (Slightly) Advanced usage

In case if you want to keep all settings.py files in a directory. Use SETTINGS_DIR environment variable.

7.1 Using SETTINGS_DIR

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
     |
     |

Metadata

Release files for converge 1.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for converge 1.1.1
File	Size	Uploaded
converge-1.1.1.tar.gz	5.0 kB	Dec 15, 2022	Details

Release files / converge-1.1.1.tar.gz

Download URL	converge-1.1.1.tar.gz
Size	5.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`b4f06e3a1fc7106ff3ebc3031e2eb3b33a72cf9237e1211470c700a04a058b4e`
BLAKE2b-256 checksum How to use checksums	`5239b194ede7ac95869a80e50704c2309413a3eb0ec3c85a574af2b6190963e3`
Upload date	Dec 15, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/4.0.1 CPython/3.10.6`