Pyaml-env: YAML with Environment Variable Resolution

Common errors

• KeyError: 'MY_ENVIRONMENT_VARIABLE'

  cause An `!ENV` tag was used for 'MY_ENVIRONMENT_VARIABLE' without a default value, and this environment variable was not set in the shell.
  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`.

• yaml.scanner.ScannerError: while scanning a simple key

  cause This error typically indicates a syntax error in your YAML file (e.g., incorrect indentation, missing colon, unquoted special characters).
  fix Carefully review the YAML file for syntax errors, paying close attention to indentation and character usage, especially around `!ENV` tags.

• TypeError: 'NoneType' object is not subscriptable

  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`.
  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`.

Warnings

• breaking 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.
  Fix: Update your YAML files to use the colon separator: `!ENV VAR:default_value`.
• gotcha 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.
  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`.
• gotcha 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.
  Fix: Upgrade to v1.2.0 or newer. This version correctly restricts parsing only to values explicitly marked with `!ENV`.
• gotcha 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.
  Fix: Specify the encoding explicitly when calling `parse_config` using the `encoding` parameter, e.g., `parse_config('config.yaml', encoding='latin-1')`.

Install

• pip install pyaml-env Install stable version

Imports

• parse_config
  wrong:

  import pyaml_env; pyaml_env.parse_config(...)

  correct:

  from pyaml_env import parse_config

  While technically possible, direct import of `parse_config` is the idiomatic and recommended way to use the library's main function.

Quickstart

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.

import os
from pyaml_env import parse_config

# Simulate setting environment variables
os.environ['API_KEY'] = 'your_secret_api_key'
os.environ['DEBUG_MODE'] = 'true'
os.environ['DB_PORT'] = '5432'

# Create a dummy YAML file for demonstration
config_content = """
api_config:
  key: !ENV API_KEY
  endpoint: https://api.example.com/v1
debug:
  enabled: !ENV DEBUG_MODE:false # 'false' is default if DEBUG_MODE is not set
database:
  host: localhost
  port: !ENV DB_PORT:3306 # '3306' is default if DB_PORT is not set
  user: !ENV DB_USER:default_user # 'default_user' is default if DB_USER is not set
logging:
  level: INFO
"""
with open('config.yaml', 'w') as f:
    f.write(config_content)

# Parse the configuration file
config = parse_config('config.yaml')

# Access resolved configuration values
print(f"API Key: {config['api_config']['key']}")
print(f"Debug Enabled: {config['debug']['enabled']} (type: {type(config['debug']['enabled'])})")
print(f"Database Port: {config['database']['port']} (type: {type(config['database']['port'])})")
print(f"Database User: {config['database']['user']}")

# Clean up the dummy file and environment variables
os.remove('config.yaml')
del os.environ['API_KEY']
del os.environ['DEBUG_MODE']
del os.environ['DB_PORT']
if 'DB_USER' in os.environ: # Only delete if it was actually set by this script or existed before
    del os.environ['DB_USER']