{"id":7533,"library":"pyaml-env","title":"Pyaml-env: YAML with Environment Variable Resolution","description":"Pyaml-env provides a straightforward way to parse YAML configuration files, automatically resolving environment variables denoted by the `!ENV` tag. It's built on top of PyYAML and is currently at version 1.2.2. The library maintains an active release cadence, with updates typically addressing bug fixes, dependency compatibility, and feature enhancements a few times a year.","status":"active","version":"1.2.2","language":"en","source_language":"en","source_url":"https://github.com/mkaranasou/pyaml_env","tags":["yaml","configuration","environment-variables","config-management"],"install":[{"cmd":"pip install pyaml-env","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core YAML parsing functionality. pyaml-env is built as an extension to PyYAML.","package":"PyYAML","optional":false}],"imports":[{"note":"While technically possible, direct import of `parse_config` is the idiomatic and recommended way to use the library's main function.","wrong":"import pyaml_env; pyaml_env.parse_config(...)","symbol":"parse_config","correct":"from pyaml_env import parse_config"}],"quickstart":{"code":"import os\nfrom pyaml_env import parse_config\n\n# Simulate setting environment variables\nos.environ['API_KEY'] = 'your_secret_api_key'\nos.environ['DEBUG_MODE'] = 'true'\nos.environ['DB_PORT'] = '5432'\n\n# Create a dummy YAML file for demonstration\nconfig_content = \"\"\"\napi_config:\n  key: !ENV API_KEY\n  endpoint: https://api.example.com/v1\ndebug:\n  enabled: !ENV DEBUG_MODE:false # 'false' is default if DEBUG_MODE is not set\ndatabase:\n  host: localhost\n  port: !ENV DB_PORT:3306 # '3306' is default if DB_PORT is not set\n  user: !ENV DB_USER:default_user # 'default_user' is default if DB_USER is not set\nlogging:\n  level: INFO\n\"\"\"\nwith open('config.yaml', 'w') as f:\n    f.write(config_content)\n\n# Parse the configuration file\nconfig = parse_config('config.yaml')\n\n# Access resolved configuration values\nprint(f\"API Key: {config['api_config']['key']}\")\nprint(f\"Debug Enabled: {config['debug']['enabled']} (type: {type(config['debug']['enabled'])})\")\nprint(f\"Database Port: {config['database']['port']} (type: {type(config['database']['port'])})\")\nprint(f\"Database User: {config['database']['user']}\")\n\n# Clean up the dummy file and environment variables\nos.remove('config.yaml')\ndel os.environ['API_KEY']\ndel os.environ['DEBUG_MODE']\ndel os.environ['DB_PORT']\nif 'DB_USER' in os.environ: # Only delete if it was actually set by this script or existed before\n    del os.environ['DB_USER']\n","lang":"python","description":"This quickstart demonstrates how to load a YAML configuration file with embedded `!ENV` tags. It shows how environment variables are resolved and how to provide default values using a colon (`:`) separator. It also illustrates accessing the parsed configuration and cleans up after execution."},"warnings":[{"fix":"Update your YAML files to use the colon separator: `!ENV VAR:default_value`.","message":"The default separator for environment variables and their default values changed from `|` to `:` in v1.1.0. If you were using `!ENV VAR|default_value`, it will now be interpreted incorrectly.","severity":"breaking","affected_versions":">=1.1.0"},{"fix":"Instead of `!ENV VAR !!float`, use `!ENV VAR tag:yaml.org,2002:float`. For example, `!ENV DB_PORT:3306 tag:yaml.org,2002:int`.","message":"When combining `!ENV` tags with explicit YAML type tags (e.g., `!!float`), the standard `!!float` syntax is not directly supported. You must use `tag:yaml.org,2002:datatype` instead.","severity":"gotcha","affected_versions":">=1.2.0 (feature added)"},{"fix":"Upgrade to v1.2.0 or newer. This version correctly restricts parsing only to values explicitly marked with `!ENV`.","message":"Prior to v1.2.0, pyaml-env would parse *any* environment variable, even if it was not explicitly marked with the `!ENV` tag. This could lead to unexpected behavior if an environment variable accidentally matched a YAML key.","severity":"gotcha","affected_versions":"<1.2.0"},{"fix":"Specify the encoding explicitly when calling `parse_config` using the `encoding` parameter, e.g., `parse_config('config.yaml', encoding='latin-1')`.","message":"File encoding defaults to `utf-8` since v1.1.4. If you are using files with a different encoding, you might encounter `UnicodeDecodeError` or incorrect parsing.","severity":"gotcha","affected_versions":"<1.1.4"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure the environment variable is set before running the application, or provide a default value in your YAML: `!ENV MY_ENVIRONMENT_VARIABLE:default_value`.","cause":"An `!ENV` tag was used for 'MY_ENVIRONMENT_VARIABLE' without a default value, and this environment variable was not set in the shell.","error":"KeyError: 'MY_ENVIRONMENT_VARIABLE'"},{"fix":"Carefully review the YAML file for syntax errors, paying close attention to indentation and character usage, especially around `!ENV` tags.","cause":"This error typically indicates a syntax error in your YAML file (e.g., incorrect indentation, missing colon, unquoted special characters).","error":"yaml.scanner.ScannerError: while scanning a simple key"},{"fix":"Verify that all intermediate keys exist in your YAML structure and resolve to mapping types. Ensure `!ENV` variables are correctly set or have defaults, preventing entire sections from becoming `None`.","cause":"This often occurs when trying to access a nested key (e.g., `config['section']['key']`) but 'section' itself was resolved to `None` or was not found, leading to `config['section']` returning `None`.","error":"TypeError: 'NoneType' object is not subscriptable"}]}