Skip to main content
Join the official Python Developers Survey 2018 and win valuable prizes: Start the survey!

Load configuration variables from a file or environment

Project description

https://img.shields.io/travis/lincolnloop/goodconf.svg https://img.shields.io/codecov/c/github/lincolnloop/goodconf.svg https://img.shields.io/pypi/v/goodconf.svg https://img.shields.io/pypi/pyversions/goodconf.svg

Define configuration variables and load them from environment or JSON/YAML file. Also generates initial configuration files and documentation for your defined configuration.

Installation

pip install goodconf or pip install goodconf[yaml] if parsing/generating YAML files is required.

Quick Start

Let’s use configurable Django settings as an example.

First, create a conf.py file in your project’s directory, next to settings.py:

import base64
import os

from goodconf import GoodConf, Value

class Config(GoodConf):
    "Configuration for My App"
    DEBUG = Value(default=False, help="Toggle debugging.")
    DATABASE_URL = Value(
        default='postgres://localhost:5432/mydb',
        help="Database connection.")
    SECRET_KEY = Value(
        initial=lambda: base64.b64encode(os.urandom(60)).decode(),
        help="Used for cryptographic signing. "
        "https://docs.djangoproject.com/en/2.0/ref/settings/#secret-key")

Next, use the config in your settings.py file:

import os
import dj_database_url
from .conf import Config

BASE_DIR = os.path.dirname(os.path.dirname(__file__))

config = Config(
    default_files=[
        "/etc/myproject/myproject.yaml",
        os.path.join(BASE_DIR, "myproject.yaml"),
    ]
).load()

DEBUG = config.DEBUG
SECRET_KEY = config.SECRET_KEY
DATABASES = {"default": dj_database_url.parse(config.DATABASE_URL)}

In your initial developer installation instructions, give some advice such as:

python -c "import myproject; print(myproject.config.generate_yaml(DEBUG=True))" > myproject.yaml

Usage

GoodConf

Your subclassed GoodConf object can be initialized with the following keyword args:

file_env_var
The name of an environment variable which can be used for the name of the configuration file to load.
default_files
If no file is passed to the load method, try to load a configuration from these files in order.
load
Trigger the load method during instantiation. Defaults to False.

Use plain-text docstring for use as a header when generating a configuration file.

Value

Declare configuration values by subclassing GoodConf and defining class attributes which are Value instances. They can be initialized with the following keyword args:

default
Default value if none is provided. If left unset, loading a config that fails to provide this value will raise accept RequiredValueMissing exception.
initial
Initial value to use when generating a config
cast_as
Python type to cast variable as. Defaults to type of default (if provided) or str.
help
Plain-text description of the value.

Django Usage

A helper is provided which monkey-patches Django’s management commands to accept a --config argument. Replace your manage.py with the following:

# Define your GoodConf in `myproject/__init__.py`
from myproject import config

if __name__ == '__main__':
    config.django_manage()

Why?

I took inspiration from logan (used by Sentry) and derpconf (used by Thumbor). Both, however used Python files for configuration. I wanted a safer format and one that was easier to serialize data into from a configuration management system.

Environment Variables

I don’t like working with environment variables. First, there are potential security issues:

  1. Accidental leaks via logging or error reporting services.
  2. Child process inheritance (see ImageTragick for an idea why this could be bad).

Second, in practice on deployment environments, environment variables end up getting written to a number of files (cron, bash profile, service definitions, web server config, etc.). Not only is it cumbersome, but also increases the possibility of leaks via incorrect file permissions.

I prefer a single structured file which is explicitly read by the application. I also want it to be easy to run my applications on services like Heroku where environment variables are the preferred configuration method.

This module let’s me do things the way I prefer in environments I control, but still run them with environment variables on environments I don’t control with minimal fuss.

Project details


Download files

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

Filename, size & hash SHA256 hash help File type Python version Upload date
goodconf-1.0.0-py2.py3-none-any.whl (11.8 kB) Copy SHA256 hash SHA256 Wheel py2.py3 Jul 18, 2018
goodconf-1.0.0.tar.gz (8.9 kB) Copy SHA256 hash SHA256 Source None Jul 18, 2018

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page