Donfig

Warnings

• breaking The `update_defaults` method in `Config` objects changed behavior in v0.8.0. Previously, it might not have consistently overridden existing default values. As of v0.8.0, `update_defaults` will reliably override old default values, which might change behavior if your code relied on the previous 'buggy' non-overriding behavior.
  Fix: Review calls to `config.update_defaults()` and ensure the intended merging/overriding logic matches the new behavior. If preserving old defaults is crucial, manually check for existence before updating.
• gotcha When loading configuration from environment variables, Donfig uses `ast.literal_eval` to parse values. This means that environment variable values are interpreted as Python literals (e.g., 'True' becomes `True` boolean, '123' becomes `123` integer, '[1, 2]' becomes a list). This can lead to unexpected type conversions if not accounted for.
  Fix: Be aware of the `ast.literal_eval` parsing when setting environment variables. Ensure values are formatted correctly as Python literals if specific types (like booleans, numbers, lists, dictionaries) are expected. For string values that should not be evaluated, ensure they are quoted or otherwise treated as plain strings by your application after retrieval if `ast.literal_eval` causes issues.
• gotcha When setting configuration values using `config.set()`, underscores (`_`) and hyphens (`-`) in key names are treated as identical. For example, `config.set({'my-key': True})` is equivalent to `config.set({'my_key': True})`.
  Fix: Maintain consistency in your key naming convention (either all hyphens or all underscores) to avoid confusion. If you use both, remember they will resolve to the same internal key.
• deprecated Version 0.8.0 introduced support for key deprecation. While not a direct breaking change for existing configurations, this means that future releases of packages using donfig might mark certain configuration keys as deprecated. It's advisable to check documentation for specific applications using donfig to see if any keys you rely on have been deprecated.
  Fix: Monitor application-specific documentation for deprecation warnings related to configuration keys. Update your configurations as recommended to use newer, non-deprecated keys.

Install

• pip install donfig Install stable version

Imports

• Config

  from donfig import Config

Quickstart

Initialize a `Config` object with a unique name, which it uses to locate environment variables and YAML files. Access settings using `config.get()` and update them with `config.set()`. The `set()` method can also be used as a context manager for temporary changes. Environment variables take precedence over YAML files, which in turn take precedence over programmatic defaults.

import os
from donfig import Config

# Simulate environment variable for demonstration
os.environ['MYAPP_SETTING_ONE'] = 'env_value'

# Create a configuration object for your application/package
# The name ('myapp' here) is used for environment variable prefixing (e.g., MYAPP_)
# and YAML file searching (e.g., ~/.config/myapp/)
config = Config('myapp', defaults={'setting_one': 'default_value', 'setting_two': 123})

# Access configuration values
value_one = config.get('setting_one')
value_two = config.get('setting_two')

print(f"Setting One (from env): {value_one}")
print(f"Setting Two (from default): {value_two}")

# Update configuration programmatically
config.set(setting_two=456)
print(f"Setting Two (updated): {config.get('setting_two')}")

# Use as a context manager to temporarily change configuration
with config.set(setting_one='context_value'):
    print(f"Setting One (in context): {config.get('setting_one')}")

print(f"Setting One (after context): {config.get('setting_one')}")

# Clean up environment variable (optional, for isolated testing)
del os.environ['MYAPP_SETTING_ONE']