Skip to main content

Load configuration variables from a file or environment

Project description

https://github.com/lincolnloop/goodconf/actions/workflows/test.yml/badge.svg?branch=main&event=push pre-commit.ci status 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

A thin wrapper over Pydantic’s settings management. Allows you to define configuration variables and load them from environment or JSON/YAML/TOML file. Also generates initial configuration files and documentation for your defined configuration.

Installation

pip install goodconf or pip install goodconf[yaml] / pip install goodconf[toml] if parsing/generating YAML/TOML files is required. When running on Python 3.11+ the [toml] extra is only required for generating TOML files as parsing is supported natively.

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, Field
from pydantic import PostgresDsn

class AppConfig(GoodConf):
    "Configuration for My App"
    DEBUG: bool
    DATABASE_URL: PostgresDsn = "postgres://localhost:5432/mydb"
    SECRET_KEY: str = Field(
        initial=lambda: base64.b64encode(os.urandom(60)).decode(),
        description="Used for cryptographic signing. "
        "https://docs.djangoproject.com/en/2.0/ref/settings/#secret-key")

    model_config = {"default_files": ["/etc/myproject/myproject.yaml", "myproject.yaml"]}

config = AppConfig()

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

import dj_database_url
from .conf import config

config.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.conf.config.generate_yaml(DEBUG=True))" > myproject.yaml

Better yet, make it a function and entry point so you can install your project and run something like generate-config > myproject.yaml.

Usage

GoodConf

Your subclassed GoodConf object can include a model_config dictionary with the following attributes:

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.

It also has one method:

load

Trigger the load method during instantiation. Defaults to False.

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

Environment variables always take precedence over variables in the configuration files.

See Pydantic’s docs for examples of loading:

Fields

Declare configuration values by subclassing GoodConf and defining class attributes which are standard Python type definitions or Pydantic FieldInfo instances generated by the Field function.

Goodconf can use one extra argument provided to the Field to define an function which can generate an initial value for the field:

initial

Callable to use for initial value when generating a config

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/conf.py`
from myproject.conf 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.

Contribute

Create virtual environment and install package and dependencies.

pip install -e ".[tests]"

Run tests

pytest

Releases are done with GitHub Actions whenever a new tag is created. For more information, see ./.github/workflows/build.yml

Project details


Download files

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

Source Distribution

goodconf-6.0.0.tar.gz (13.9 kB view details)

Uploaded Source

Built Distribution

goodconf-6.0.0-py3-none-any.whl (10.8 kB view details)

Uploaded Python 3

File details

Details for the file goodconf-6.0.0.tar.gz.

File metadata

  • Download URL: goodconf-6.0.0.tar.gz
  • Upload date:
  • Size: 13.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for goodconf-6.0.0.tar.gz
Algorithm Hash digest
SHA256 8fdb5a45979ba605e268a56beb24cabd429e440c017a0dbc944e214d670331cd
MD5 bc6cfffa066a7c37f3fa6864a1720b9b
BLAKE2b-256 b01c18a0a82b0787dc579a659033ab742a23384bd707cabe760555967fd74a4e

See more details on using hashes here.

File details

Details for the file goodconf-6.0.0-py3-none-any.whl.

File metadata

  • Download URL: goodconf-6.0.0-py3-none-any.whl
  • Upload date:
  • Size: 10.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for goodconf-6.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 efdbf719145a5ca2a2fa4ee20f9c825acad26cdf57a6e43c95811771f9ce9739
MD5 6b0c987f6b8361af48a3425f2f71ed0c
BLAKE2b-256 1a8eb4fc24649fd88c1a18eca61b2062a141cab50435031c4e95e4813c755bc5

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page