converge

Ultra simple settings management for (only) Python apps

Project description

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 load desired application settings.

2 Getting started

2.1 Easy to use

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

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

3 .convergerc

.convergerc file helps converge choose application mode and in turn load correct settings file.

3.1 Supported directives

_All directives are optional._

APP_MODE

Valid values are

prod
dev
test
staging

Based on mode appropriate settings module would be used (if available)

SETTINGS_DIR

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

cat .convergerc

SETTINGS_DIR = 'appsettings'
GIT_SETTINGS_REPO = 'git@github.com:shon/converge-test-settings.git'
GIT_SETTINGS_SUBDIR = 'myapp1'

In this case all *_settings.py files in myapp1/ would be copied to appsettings.

Example

.convergerc
-----------

APP_MODE = 'test'
SETTINGS_DIR = 'settings'
GIT_SETTINGS_REPO = 'git@github.com:shon/converge-test-settings.git'
GIT_SETTINGS_SUBDIR = 'myapp1'

4 Supported settings files

Defaults: default_settings.py
Mode
- production: prod_settings.py
- development: dev_settings.py
- test: test_settings.py
- staging: staging_settings.py
Deployment specific: site_settings.py

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

6 Overriding settings

Defining module veriables in site_settings.py

6.1 Example

default_settings.py

SERVER_PORT = 9999

site_settings.py

SERVER_PORT = 8888

7 Overriding partial settings

Example:

default_settings.py

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

site_settings.py

DB.PORT = 1111

8 (Slightly) Advanced usage

In case if you want to keep all settings.py files in a directory. Use SETTINGS_DIR directive in .convergerc file.

8.1 Example

>> cat .convergerc

APP_MODE = 'prod'
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
     |
     |

Project details

Release history Release notifications | RSS feed

1.1.1

Dec 15, 2022

1.1.0

Nov 24, 2022

1.0.2

Feb 9, 2021

1.0.1

Feb 5, 2021

1.0.0

Nov 19, 2019

0.9.8

Aug 6, 2018

0.9.7

Mar 6, 2018

0.9.6

Dec 27, 2017

This version

0.9.5

Dec 26, 2017

0.9

Oct 21, 2017

0.7

Jan 12, 2017

0.5

Jan 7, 2017

0.2

Nov 12, 2016

0.1

Nov 12, 2016

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

converge-0.9.5.tar.gz (4.6 kB view details)

Uploaded Dec 26, 2017 Source

File details

Details for the file converge-0.9.5.tar.gz.

File metadata

Download URL: converge-0.9.5.tar.gz
Upload date: Dec 26, 2017
Size: 4.6 kB
Tags: Source
Uploaded using Trusted Publishing? No

File hashes

Hashes for converge-0.9.5.tar.gz
Algorithm	Hash digest
SHA256	`f9b5ea7e28008ade200880574778d83a581d0005e53398447d79d054f479e4ae`
MD5	`e0487baf94ee831be2cd082be5478677`
BLAKE2b-256	`5048d4263a7dbd82b2eb54ff7b9221aba3a8936d324411edf530ce8f9f4032ab`