helpers_yaml

Version: 7.0.5

wexample-helpers-yaml provides thin wrappers around PyYAML for reading and writing YAML files (yaml_read, yaml_read_dict, yaml_write in src/wexample_helpers_yaml/helper/yaml_helpers.py), plus yaml_fill_unresolved_vars which replaces ${VAR} placeholders in a YAML string before parsing. It also ships HasYamlEnvKeysFile (src/wexample_helpers_yaml/classes/mixin/has_yaml_env_keys_file.py), a mixin that loads a YAML file into a class's env_config mapping without touching os.environ. The package is aimed at Python projects in the wexample suite that need structured YAML I/O or want to drive environment configuration from YAML files.

Installation
Quickstart
Tests
Architecture
Integration in the Suite
Dependencies
Versioning & Compatibility Policy
License
About us
Known Limitations & Roadmap
Status & Compatibility
Useful Links
Migration Notes

Installation

pip install wexample-helpers-yaml

Requires Python >=3.10.

Quickstart

Install from PyPI:

pip install wexample-helpers-yaml

All functions are in src/wexample_helpers_yaml/helper/yaml_helpers.py.

Write and read back a YAML file:

from wexample_helpers_yaml.helper.yaml_helpers import yaml_write, yaml_read_dict

yaml_write("/tmp/config.yml", {"host": "localhost", "port": 5432})

config = yaml_read_dict("/tmp/config.yml")
print(config["host"])  # localhost

Strip unresolved ${VAR} placeholders before parsing:

import yaml
from wexample_helpers_yaml.helper.yaml_helpers import yaml_fill_unresolved_vars

raw = "host: ${DB_HOST}\nport: 5432"
data = yaml.safe_load(yaml_fill_unresolved_vars(raw))
print(data)  # {'host': '', 'port': 5432}

Pass fill_value to substitute something other than an empty string: yaml_fill_unresolved_vars(raw, fill_value="localhost").

Tests

This project uses pytest for testing and pytest-cov for code coverage analysis.

Installation

First, install the required testing dependencies:

.venv/bin/python -m pip install pytest pytest-cov

Basic Usage

Run all tests with coverage:

.venv/bin/python -m pytest --cov --cov-report=html

Common Commands

# Run tests with coverage for a specific module
.venv/bin/python -m pytest --cov=your_module

# Show which lines are not covered
.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing

# Generate an HTML coverage report
.venv/bin/python -m pytest --cov=your_module --cov-report=html

# Combine terminal and HTML reports
.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing --cov-report=html

# Run specific test file with coverage
.venv/bin/python -m pytest tests/test_file.py --cov=your_module --cov-report=term-missing

Viewing HTML Reports

After generating an HTML report, open htmlcov/index.html in your browser to view detailed line-by-line coverage information.

Coverage Threshold

To enforce a minimum coverage percentage:

.venv/bin/python -m pytest --cov=your_module --cov-fail-under=80

This will cause the test suite to fail if coverage drops below 80%.

Architecture

The package has three parts: a helper module with all public functions, a mixin class, and a type-alias module. There is no framework layer, no registry, and no configuration at import time.

Helper module

src/wexample_helpers_yaml/helper/yaml_helpers.py is where every callable lives.

yaml_read(file_path, default) opens the file, calls yaml.safe_load, and returns the result when it is a dict. Any exception — missing file, parse error, wrong type — is caught and the default is returned instead.

yaml_read_dict(file_path, default) wraps yaml_read and guarantees a dict return: if yaml_read comes back falsy it returns default or {}, otherwise it asserts the value is a dict and hands it back.

yaml_write(file_path, content) opens the file for writing and calls yaml.safe_dump.

yaml_fill_unresolved_vars(yml_text, fill_value) replaces every ${VAR_NAME} placeholder in a raw YAML string before it reaches a parser. The regex _UNRESOLVED_VAR_RE = re.compile(r"\$\{([^}]+)\}") is compiled once at module import; fill_value defaults to an empty string so unset variables silently become blank rather than breaking the parse.

Call path for file I/O

caller
  └─ yaml_read_dict(path)
       └─ yaml_read(path)
            └─ open(path) → yaml.safe_load()

yaml_read_dict is the preferred entry point. Call yaml_read directly only when a non-dict result (e.g. a plain list) is acceptable.

Call path for placeholder substitution

caller
  └─ yaml_fill_unresolved_vars(raw_text, fill_value)
       └─ _UNRESOLVED_VAR_RE.sub(lambda _: fill_str, yml_text)

The caller is responsible for feeding the result into yaml.safe_load — the function returns a string, not a parsed structure.

Mixin class

src/wexample_helpers_yaml/classes/mixin/has_yaml_env_keys_file.py defines HasYamlEnvKeysFile, which extends HasEnvKeysFile from wexample-helpers. Its single method _init_env_file_yaml(file_path) loads a YAML file into the instance's env_config mapping and then calls the inherited _validate_env_keys(). It deliberately does not write to os.environ; that step is left to callers that need it.

HasYamlEnvKeysFile._init_env_file_yaml(file_path)
  └─ yaml_read_dict(file_path)          # helper module
  └─ self.env_config.update(result)
  └─ self._validate_env_keys()          # inherited from HasEnvKeysFile

Type aliases

src/wexample_helpers_yaml/const/types.py re-exports two aliases from wexample-helpers:

YamlContent — alias of StructuredData, used as the return type of yaml_read.
YamlContentDict — alias of StringKeysDict, used as the return type of yaml_read_dict and the argument type of yaml_write.

These aliases exist to give callers a YAML-specific name to import without pulling in the underlying wexample-helpers types directly.

Integration in the Suite

This package is part of the Wexample Suite — a collection of high-quality, modular tools designed to work seamlessly together across multiple languages and environments.

The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.

Visit the Wexample Suite documentation for the complete package ecosystem.

Dependencies

attrs: >=23.1.0
cattrs: >=23.1.0
pyyaml:
wexample-helpers: >=20.2.0

Versioning & Compatibility Policy

Wexample packages follow Semantic Versioning (SemVer):

MAJOR: Breaking changes
MINOR: New features, backward compatible
PATCH: Bug fixes, backward compatible

We maintain backward compatibility within major versions and provide clear migration guides for breaking changes.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Free to use in both personal and commercial projects.

About us

Wexample stands as a cornerstone of the digital ecosystem — a collective of seasoned engineers, researchers, and creators driven by a relentless pursuit of technological excellence. More than a media platform, it has grown into a vibrant community where innovation meets craftsmanship, and where every line of code reflects a commitment to clarity, durability, and shared intelligence.

This packages suite embodies this spirit. Trusted by professionals and enthusiasts alike, it delivers a consistent, high-quality foundation for modern development — open, elegant, and battle-tested. Its reputation is built on years of collaboration, refinement, and rigorous attention to detail, making it a natural choice for those who demand both robustness and beauty in their tools.

Wexample cultivates a culture of mastery. Each package, each contribution carries the mark of a community that values precision, ethics, and innovation — a community proud to shape the future of digital craftsmanship.

Known Limitations & Roadmap

Current limitations and planned features are tracked in the GitHub issues.

See the project roadmap for upcoming features and improvements.

Status & Compatibility

Maturity: Production-ready

Python Support: >=3.10

OS Support: Linux, macOS, Windows

Status: Actively maintained

Useful Links

Homepage: https://github.com/wexample/python-helpers-yaml
Documentation: docs.wexample.com
Issue Tracker: https://github.com/wexample/python-helpers-yaml/issues
Discussions: https://github.com/wexample/python-helpers-yaml/discussions
PyPI: pypi.org/project/wexample-helpers-yaml

Migration Notes

When upgrading between major versions, refer to the migration guides in the documentation.

Breaking changes are clearly documented with upgrade paths and examples.

License
- OSI Approved :: MIT License
Operating System
- OS Independent
Programming Language
- Python :: 3

Metadata

License
- OSI Approved :: MIT License
Operating System
- OS Independent
Programming Language
- Python :: 3

Release files for wexample-helpers-yaml 7.0.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for wexample-helpers-yaml 7.0.5
File	Size	Uploaded
wexample_helpers_yaml-7.0.5.tar.gz	10.6 kB	Oct 5, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for wexample-helpers-yaml 7.0.5
File	Interpreter	ABI	Platform	Reset
wexample_helpers_yaml-7.0.5-py3-none-any.whl 8.8 kB Oct 5, 2026	Python 3	none	any	Details

Total release size: 19.4 kB

Release files / wexample_helpers_yaml-7.0.5.tar.gz

Download URL	wexample_helpers_yaml-7.0.5.tar.gz
Size	10.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`e6f2a484a56f74ec3e4a77b662b2daca724e1f6fb1d228029e519d966a7fc433`
BLAKE2b-256 checksum How to use checksums	`e8e8a0a9976feb8bcf9c8ca6824b8bda70b4b1c99a85bb941331850fd5316b65`
Upload date	Oct 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`pdm/2.25.9 CPython/3.12.3 Linux/6.8.0-139-generic`

Release files / wexample_helpers_yaml-7.0.5-py3-none-any.whl

Download URL	wexample_helpers_yaml-7.0.5-py3-none-any.whl
Size	8.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`5e6b4b2d93c412cc513f06d8de14f262658ba9cfd1a240f3b053d3d493209449`
BLAKE2b-256 checksum How to use checksums	`47fb63ca3eb1f59673bbfcb356b7973ca0af602037fa8cd90265b2de37aedc04`
Upload date	Oct 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`pdm/2.25.9 CPython/3.12.3 Linux/6.8.0-139-generic`