Skip to main content

Configparser with environment variable and direct override

Project description

ConfigParser Override

Version Build Status

This library provides a utility class ConfigParserOverride that extends the functionality of configparser.ConfigParser to allow overriding configuration values with environment variables and directly assigned key-value arguments.

NOTE: This library only depends on the Python standard library!

Features

  • Read configuration from one or more files.
  • Override configuration values with environment variables.
  • Override configuration values with directly assigned arguments.
  • Support for optional environment variable prefix.

Install

pip install configparser-override

Usage

Example of how to use ConfigParserOverride:

Example config.ini File

[DEFAULT]
default_key1 = default_value1
default_key2 = default_value2

[section1]
key1 = value1
key2 = value2

[section2]
key3 = value3
key4 = value4

Python Code

import os
from configparser_override import ConfigParserOverride

# Optionally set environment variables for overriding
os.environ["MYAPP_DEFAULT_KEY1"] = "overridden_default_value1"
os.environ["MYAPP_SECTION1__KEY1"] = "overridden_value1"
os.environ["MYAPP_SECTION2__KEY3"] = "overridden_value3"

# Initialize the parser with an optional environment variable prefix and
# overrides from direct assignments.
parser = ConfigParserOverride(
    env_prefix="MYAPP_",
    SECTION2__KEY4="direct_override_value4",
    section2__key5="direct_override_value5",  # By default sections and keys are case insensitive
)

# Read configuration from a file
config = parser.read(filenames="config.ini")

# Access the configuration
print(config.defaults()["default_key1"])  # Output: overridden_default_value1
print(config.defaults()["default_key2"])  # Output: default_value2
print(config["section1"]["key1"])  # Output: overridden_value1
print(config["section1"]["key2"])  # Output: value2
print(config["section2"]["key3"])  # Output: overridden_value3
print(config["section2"]["key4"])  # Output: direct_override_value4
print(config["section2"]["key5"])  # Output: direct_override_value5

Note

Configuration values can be overridden in three ways. This is the order of precedence:

  1. Directly assigned arguments during initialization of the class.
  2. Environment variables.
  3. Configuration files.

The format for environment variable names is as follows:

  • When no prefix is set: The format is [OPTION].
  • When a prefix is set: The format is [PREFIX][OPTION].
  • Sections and options are separated by double underscores (__).
    • The format is [PREFIX][SECTION]__[OPTION] or [SECTION]__[OPTION] if no prefix is set.

For example, to override the option key1 in section1 with a prefix MYAPP_, the environment variable would be MYAPP_SECTION1__KEY1.

Platform Dependency

Different operating systems handle environment variables differently. Linux is case sensitive while Windows is not. See os.environ docs. Hence, it is safest to always use capitalized environment variables to avoid any unexpected behavior.

Recommendation

In order to avoid any unanticipated issues and make your code safe to run on any platform, follow these rules:

  • Environment variables should be UPPERCASE.
    • Environment variable prefix should be UPPERCASE.
  • Sections in config.ini files should be lowercase.
    • One exception is the DEFAULT section which by convention is UPPERCASE.
  • Options in config.ini files should be lowercase.
  • Directly assigned arguments should be lowercase.

Default Case Sensitivity Handling

By default, ConfigParserOverride stores everything as lowercase, with an exception of Section headers that are read from configuration files, where the existing casing is honored. However, if you want to override something with an environment variable or direct assignment, it will recognize the existing casing of the section and continue to use that even though you use uppercase or something else in the override.

It is highly discouraged, but you can make ConfigParserOverride case-sensitive by initializing it with the argument case_sensitive_overrides=True.

from configparser_override import ConfigParserOverride

parser = ConfigParserOverride(env_prefix="MYAPP_", case_sensitive_overrides=True)

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

configparser_override-0.3.0.tar.gz (14.4 kB view hashes)

Uploaded Source

Built Distribution

configparser_override-0.3.0-py3-none-any.whl (8.9 kB view hashes)

Uploaded Python 3

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