Skip to content

Coyaml

Coyaml is a pragmatic Python library for YAML configuration that stays simple for small apps and scales to complex setups. It gives you clean dot access, powerful templates, zero‑boilerplate injection, and smooth Pydantic interop — without a heavy framework.

Tests Coverage Publish PyPI PyPI - License PyPI - Downloads

Why Coyaml

  • Simple dot access: cfg.section.option with safe nested creation
  • Templates that work: ${{ env:VAR }}, ${{ file:path }}, ${{ config:node }}, ${{ yaml:file }}
  • Pydantic interop: convert any node to models via .to(Model)
  • Zero‑boilerplate DI: @coyaml + Annotated[..., YResource] injects values into any function
  • Smart search: inject by parameter name, optionally constrained by glob masks (*, **) with deterministic behavior
  • Predictable merge: dicts deep‑merge, lists are replaced (documented and explicit)

10‑second example

from typing import Annotated
from coyaml import YSettings, YRegistry, YResource, coyaml
from coyaml.sources.yaml import YamlFileSource

# Load once
cfg = YSettings().add_source(YamlFileSource('config.yaml'))
cfg.resolve_templates()
YRegistry.set_config(cfg)

# Inject by name, constrained to debug subtree
@coyaml(mask='debug.**')
def connect(user: Annotated[str, YResource()], url: Annotated[str, YResource('debug.db.url')]):
    print(user, url)

connect()
  • Works with environment variables, files, and external YAML includes
  • Deterministic and helpful errors (missing, ambiguous, invalid templates)