pyaml-env

library1.2.2pypypi✓ verified 89d ago

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.

serialization http-networking

pip install pyaml-env

github ↗package ↗

INSTALL

IMPORT

SIG · PYAML-ENV

pyaml-env

serializationpythonv1.2.2

Install

1.7s avg

Import

148ms

Disk

18MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.2.2 · 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.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.151s · 20MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.7s · import 0.145s · 21MB

18MB installed

● package 18MB

Code

Verified usage

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

parse_config

✓ from pyaml_env import parse_config

✗ import pyaml_env; pyaml_env.parse_config(...)

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

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']

Debug

Known issues

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

affects: >=1.1.0

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

affects: >=1.2.0 (feature added)

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

affects: <1.2.0

gotchaFile 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')`.

affects: <1.1.4

Errors

Common errors & fixes

KeyError: 'MY_ENVIRONMENT_VARIABLE'

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

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

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

Upgrade

Version history

1.2.2latest on PyPI · released Jan 13, 2025

Audit

Dependencies

PyYAMLrequiredCore YAML parsing functionality. pyaml-env is built as an extension to PyYAML.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/mkaranasou/pyaml_env ↗

packagehttps://pypi.org/project/pyaml-env/ ↗