{"id":1465,"library":"donfig","title":"Donfig","description":"Donfig is a Python library designed to simplify package and script configuration, drawing inspiration from the configuration logic originally found in the Dask library. It allows configuration through programmatic settings, environment variables, and YAML files located in standard paths. The library is actively maintained, with the current version being 0.8.1.post1, and releases occurring periodically to add features and fix bugs.","status":"active","version":"0.8.1.post1","language":"python","source_language":"en","source_url":"https://github.com/pytroll/donfig","tags":["configuration","settings","yaml","environment-variables"],"install":[{"cmd":"pip install donfig","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for parsing configuration from YAML files.","package":"pyyaml","optional":false}],"imports":[{"symbol":"Config","correct":"from donfig import Config"}],"quickstart":{"code":"import os\nfrom donfig import Config\n\n# Simulate environment variable for demonstration\nos.environ['MYAPP_SETTING_ONE'] = 'env_value'\n\n# Create a configuration object for your application/package\n# The name ('myapp' here) is used for environment variable prefixing (e.g., MYAPP_)\n# and YAML file searching (e.g., ~/.config/myapp/)\nconfig = Config('myapp', defaults={'setting_one': 'default_value', 'setting_two': 123})\n\n# Access configuration values\nvalue_one = config.get('setting_one')\nvalue_two = config.get('setting_two')\n\nprint(f\"Setting One (from env): {value_one}\")\nprint(f\"Setting Two (from default): {value_two}\")\n\n# Update configuration programmatically\nconfig.set(setting_two=456)\nprint(f\"Setting Two (updated): {config.get('setting_two')}\")\n\n# Use as a context manager to temporarily change configuration\nwith config.set(setting_one='context_value'):\n    print(f\"Setting One (in context): {config.get('setting_one')}\")\n\nprint(f\"Setting One (after context): {config.get('setting_one')}\")\n\n# Clean up environment variable (optional, for isolated testing)\ndel os.environ['MYAPP_SETTING_ONE']","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.8.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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})`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Monitor application-specific documentation for deprecation warnings related to configuration keys. Update your configurations as recommended to use newer, non-deprecated keys.","message":"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.","severity":"deprecated","affected_versions":">=0.8.0"},{"fix":"Ensure all configuration sources (e.g., values passed to `Config` constructor, loaded from files, or environment variables) are dictionary-like objects. Review how configurations are loaded and processed to prevent strings from being mistakenly treated as dictionaries in the internal update logic. If string values are intended as configuration, they might need to be wrapped in a dictionary or processed differently before being passed to `donfig`.","message":"When initializing `Config` objects or refreshing configurations, an internal `AttributeError: 'str' object has no attribute 'items'` can occur if a configuration source provides a string instead of a dictionary-like object. This happens during the internal `update` process, which expects to iterate over dictionary items. This indicates a breaking change in how configuration sources are handled or what they are expected to contain.","severity":"breaking","affected_versions":">=0.8.0"},{"fix":"Ensure all configuration sources (defaults, files, environment variables, etc.) that are intended to be merged by `donfig` are correctly formatted and parsed as dictionary-like objects before or during their loading. If a source unexpectedly yields a string, investigate how it's being produced and ensure it's converted to a dictionary or handled appropriately by Donfig's parsing mechanisms (e.g., by ensuring JSON strings are parsed as JSON objects).","message":"An `AttributeError: 'str' object has no attribute 'items'` occurs during `Config` object initialization within the `refresh` method. This happens when the internal `update` function, which expects a dictionary to merge, receives a string instead. This indicates a configuration source (e.g., an environment variable, a file's content, or a manually provided source) is being interpreted or passed as a string where a dictionary is expected, leading to a type mismatch during configuration merging.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'0.8.1':51 'activ':44 'add':58 'allow':27 'bug':62 'configur':13,18,28,63 'current':48 'dask':24 'design':7 'donfig':1,2 'draw':14 'environ':32,67 'environment-vari':66 'featur':59 'file':36 'fix':61 'found':21 'inspir':15 'librari':6,25,42 'locat':37 'logic':19 'maintain':45 'occur':55 'origin':20 'packag':10 'path':40 'period':56 'post1':52 'programmat':30 'python':5 'releas':54 'script':12 'set':31,64 'simplifi':9 'standard':39 'variabl':33,68 'version':49 'yaml':35,65","created_at":"2026-04-09T03:49:06.998238+00:00","updated_at":"2026-04-16T14:40:52.918971+00:00","problems":[{"fix":"Install the package using pip: `pip install donfig`","cause":"The 'donfig' package is not installed in the Python environment where the code is being run, or the environment is not correctly activated.","error":"ModuleNotFoundError: No module named 'donfig'"},{"fix":"Ensure the 'my_setting' key is defined in a YAML file, as an environment variable (e.g., `MYPKG_MY__SETTING`), or explicitly set in the `Config` object, for example: `config = Config('mypkg', defaults={'my_setting': 'default_value'})`","cause":"You are attempting to access a configuration key using attribute-style access (e.g., `config.my_setting`) that has not been defined in any of the loaded configuration sources (YAML files, environment variables, or programmatic defaults).","error":"AttributeError: 'Config' object has no attribute 'my_setting'"},{"fix":"Carefully review the YAML file for syntax errors, paying close attention to indentation and proper key-value pair formatting. A YAML linter can help identify issues.","cause":"A YAML configuration file used by donfig has a syntax error, such as incorrect indentation, a missing colon, or an invalid structure, preventing it from being parsed correctly.","error":"yaml.scanner.ScannerError: while scanning a simple key"},{"fix":"Define the key in your configuration sources, or use the `.get()` method for safe access with a default value, e.g., `value = config.get('some_other_setting', 'default_value')`.","cause":"When accessing configuration values using dictionary-style lookup (e.g., `config['some_other_setting']`), this error occurs if the specified key does not exist in the loaded configuration.","error":"KeyError: 'some_other_setting'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.8.1.post1","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/pytroll/donfig","docs":null,"changelog":null,"pypi":"https://pypi.org/project/donfig/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":"verified"}}