envyaml

library1.10.211231pypypi✓ verified 24d ago

EnvYAML is a Python library that simplifies reading YAML configuration files and seamlessly integrates environment variables. It allows referencing environment variables directly within YAML files using the `${VAR_NAME}` or `$VAR_NAME` syntax, providing a flexible and secure way to manage configurations. The library is currently at version 1.10.211231 and is actively maintained with regular updates, often focusing on bug fixes and minor feature enhancements.

serialization devops

pip install envyaml

github ↗package ↗

INSTALL

IMPORT

SIG · ENVYAML

envyaml

serializationpythonv1.10.211231

Install

1.7s avg

Import

139ms

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.10.211231 · 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.95 runs

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

glibc

py 3.10–3.95 runs

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

18MB installed

● package 18MB

Code

Verified usage

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

EnvYAML

✓ from envyaml import EnvYAML

This quickstart demonstrates how to create a simple YAML configuration file that references environment variables, load it using EnvYAML, and access the configuration values. It includes examples for mandatory and optional environment variables with default values.

import os from envyaml import EnvYAML # Create a dummy YAML file with open('config.yaml', 'w') as f: f.write('app:\n') f.write(' name: "${APP_NAME}"\n') f.write(' version: "${APP_VERSION|1.0.0}"\n') f.write('database:\n') f.write(' host: $DB_HOST\n') f.write(' port: $DB_PORT|5432\n') f.write(' password: $DB_PASSWORD ') # Set environment variables (or they will default if specified in YAML) os.environ['APP_NAME'] = 'MyAwesomeApp' os.environ['DB_HOST'] = 'localhost' os.environ['DB_PASSWORD'] = os.environ.get('DB_PASSWORD', 'super_secret_dev') # Initialize EnvYAML env = EnvYAML('config.yaml') # Access configuration values print(f"App Name: {env['app.name']}") print(f"App Version: {env['app.version']}") print(f"Database Host: {env['database.host']}") print(f"Database Port: {env['database.port']}") print(f"Database Password: {env['database.password']}") # Clean up dummy file os.remove('config.yaml')

envyaml --version

Debug

Known issues

breakingEnabling 'strict' mode (which is default) can cause `ValueError` exceptions if environment variables are not defined. Prior to version 1.5.201226, strict mode might have been less stringent about duplicate variable definitions in `.env` files.

fix

To disable strict mode, initialize `EnvYAML('config.yaml', strict=False)` or set the `ENVYAML_STRICT_DISABLE` environment variable before initialization. Ensure all referenced environment variables are set if strict mode is active.

affects: <1.5.201226

gotchaSingle dollar sign (`$VAR_NAME`) is used for environment variable substitution. To use a literal dollar sign in your YAML, it must be escaped with a double dollar sign (`$$`). For example, `escaped: $$.extra` will result in `$.extra`.

fix

Use `$$` for a literal `$` in your YAML configuration.

affects: All versions

gotchaParsing of boolean values can be ambiguous in YAML. Strings like `NO`, `ON`, `OFF`, `YES`, `TRUE`, `FALSE` (case-insensitive) can be interpreted as boolean `False` or `True` respectively by underlying YAML parsers (like PyYAML, which EnvYAML uses).

fix

Always quote values that should be treated as strings, e.g., `country: "NO"` instead of `country: NO`, to prevent unintended boolean conversion.

affects: All versions

deprecatedOlder versions of EnvYAML might have handled escaped dollar signs or multiple variable definitions differently. Version 1.10.211231 specifically made a 'specific replacement instead of a general replacement for escaped dollar signs', indicating a refinement in how escaping is processed.

fix

Review configurations using `$` or `$$` notation, especially if upgrading from much older versions, to ensure they parse as intended. The current behavior (1.10.211231+) is more precise for escaped dollar signs.

affects: <1.10.211231

Errors

Common errors & fixes

ValueError: Strict mode enabled, variable $VAR not defined!

By default, envyaml operates in 'strict mode' which raises this error if an environment variable referenced in the YAML file (e.g., `${VAR}` or `$VAR`) is not defined in the environment.

fix

Either define the missing environment variable, provide a default value in your YAML (e.g., `${VAR|default_value}`), or disable strict mode when initializing EnvYAML: `env = EnvYAML('config.yaml', strict=False)` or by setting the environment variable `ENVYAML_STRICT_DISABLE=1`.

ModuleNotFoundError: No module named 'envyaml'

The 'envyaml' package has not been installed in your Python environment or the environment where your script is being run is not active.

fix

Install the package using pip: `pip install envyaml`.

AttributeError: module 'envyaml' has no attribute 'EnvYAML'

You are attempting to access the `EnvYAML` class incorrectly, most likely by importing the module directly as `import envyaml` and then trying `envyaml.EnvYAML` (note the casing) or `envyaml.EnvYAML()`.

fix

Import the `EnvYAML` class directly from the `envyaml` package using `from envyaml import EnvYAML`.

KeyError: 'some.undefined.key'

This error occurs when you try to access a configuration key or path (e.g., `env['some.undefined.key']`) that does not exist in your loaded YAML configuration.

fix

Ensure the key path exists in your YAML file. You can also use the `.get()` method with a default value to prevent a KeyError: `value = env.get('some.undefined.key', 'default_value')`.

Upgrade

Version history

1.10.211231latest on PyPI · released Jan 8, 2022

Audit

Dependencies

PyYAMLrequiredEnvYAML is built on top of PyYAML for core YAML parsing functionality.

Agent activity

27 hits · last 30 days

node

Resources

githubhttps://github.com/thesimj/envyaml ↗

packagehttps://pypi.org/project/envyaml/ ↗