Registry / serialization / hierarchical-conf

hierarchical-conf

JSON →
library1.0.4pypypi✓ verified 84d ago

Hierarchical-conf is a Python library designed for loading settings from YAML files in a hierarchical manner. It processes a list of paths, loading configuration files and overwriting duplicated keys based on file precedence. The library supports Python 3.7+ and is currently at version 1.0.4, with releases appearing to be made as needed.

pip install hierarchical-conf
INSTALL
IMPORT
SIG · HIERARCHICAL-CONF
H
hierarchical-conf
serializationpythonv1.0.4
Install
1.8s avg
Import
141ms
Disk
19MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.0.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.143s · 20.5MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 1.8s · import 0.138s · 21MB
19MB installed
● package 19MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

HierarchicalConf
from hierarchical_conf.hierarchical_conf import HierarchicalConf

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)
Debug
Known issues
gotchaThe 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.
affects: All
gotchaWhen 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.
affects: All
Errors
Common errors & fixes
KeyError: 'my_config_key' or configuration not loaded as expected.
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.
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.
Upgrade
Version history
1.0.4latest on PyPI · released Aug 20, 2025
Audit
Dependencies
PyYAMLoptionalRequired for parsing YAML configuration files, which is the core functionality of the library.
Agent activity
14 hits · last 30 days
node
12
Resources
hierarchical-conf — pip install hierarchical-conf · libregistry