Hierarchical Configuration

Common errors

• KeyError: 'my_config_key' or configuration not loaded as expected.

  cause The `conf_files_paths` provided to `HierarchicalConf` does not contain the directory where your configuration files are located, or the files are not named according to the `[ENVIRONMENT]_conf.yml` pattern.
  fix Verify that the `conf_files_paths` list includes the absolute path to the directory containing your YAML files (e.g., `['/path/to/my/configs']`). Confirm that your configuration files are named `dev_conf.yml`, `production_conf.yml`, etc., matching the `ENVIRONMENT` variable.

• Configuration value is incorrect despite file existing and environment being set.

  cause This often occurs due to key overwriting. If the same key is present in multiple configuration files loaded by `HierarchicalConf`, the value from the last loaded file (highest precedence) will take effect, potentially masking an earlier value you expected.
  fix Inspect all relevant `[ENVIRONMENT]_conf.yml` files for duplicate keys. Trace the loading order based on `conf_files_paths` and the `ENVIRONMENT` variable to understand which value has precedence. Adjust your configuration files or `conf_files_paths` order as needed.

Warnings

• gotcha The library relies on the `ENVIRONMENT` environment variable to determine which configuration files (e.g., `dev_conf.yml`, `production_conf.yml`) to load. Missetting or omitting this variable will result in unexpected configurations being loaded or no configuration at all.
  Fix: Always ensure the `ENVIRONMENT` environment variable is correctly set before initializing `HierarchicalConf`. Configuration files should follow the `[ENVIRONMENT]_conf.yml` naming convention.
• gotcha When multiple configuration files are loaded, keys defined in later loaded files will overwrite values from earlier loaded files if duplicates exist. Understand the loading precedence to avoid unexpected configuration values.
  Fix: Design your configuration hierarchy carefully. If a key needs to be consistent, define it once in the highest-precedence file. If it needs environment-specific overrides, ensure the environment-specific file is loaded later in the precedence.

Install

• pip install hierarchical-conf Install latest version

Imports

• HierarchicalConf

  from hierarchical_conf.hierarchical_conf import HierarchicalConf

Quickstart

This quickstart demonstrates how to set up `hierarchical-conf` to load configurations based on the `ENVIRONMENT` variable. It creates two sample YAML files for 'dev' and 'production' environments, then loads and prints configuration values, showing how the `ENVIRONMENT` variable influences which settings are applied.

import os
from pathlib import Path
from hierarchical_conf.hierarchical_conf import HierarchicalConf

# Create dummy config files
project_root = Path(os.getcwd()) / 'my_configs'
project_root.mkdir(exist_ok=True)

(project_root / 'dev_conf.yml').write_text('database: { host: dev_db, port: 5432 }\nlog_level: DEBUG')
(project_root / 'production_conf.yml').write_text('database: { host: prod_db, port: 5432 }\nlog_level: INFO')

# Set environment variable (simulate 'dev' environment)
os.environ['ENVIRONMENT'] = 'dev'

# Initialize HierarchicalConf
hconf = HierarchicalConf(conf_files_paths=[str(project_root)])

# Get configuration for 'database'
db_config = hconf.get_config('database')
print(f"Database config (dev): {db_config}")

# Get configuration for 'log_level'
log_level = hconf.get_config('log_level')
print(f"Log level (dev): {log_level}")

# Switch environment to production
os.environ['ENVIRONMENT'] = 'production'

# Re-initialize to pick up new environment (or load another instance)
hconf_prod = HierarchicalConf(conf_files_paths=[str(project_root)])
prod_db_config = hconf_prod.get_config('database')
print(f"Database config (production): {prod_db_config}")

prod_log_level = hconf_prod.get_config('log_level')
print(f"Log level (production): {prod_log_level}")

# Clean up dummy files
# os.remove(project_root / 'dev_conf.yml')
# os.remove(project_root / 'production_conf.yml')
# os.rmdir(project_root)