pyya - Simple tool that converts YAML configuration files to Python objects

Features

• Very lightweight and simple API (currently it contains only one function)
• Easy to use
• Based on popular and well-tested libraries (like pydantic, camel-converter, PyYAML and munch)
• Automatically merge default and production configuration files
• Convert keys in configuration files to snake_case
• YAML validation with Pydantic models

Installation

pip install pyya

Or download a specific version from Releases page and install it with:

pip install /path/to/pyya-[version]-py3-none-any.whl

Usage

Example

Create YAML configuration files for your project:

# default.config.yaml - this file usually goes to version control system
database:
  host: localhost
  port: 5432
  username: postgres
  password: postgres

redis:
  host: localhost
  port: 6379

# config.yaml - this file for production usage
database:
  username: username
  password: password
  name: db

Import configuration files in your Python code with pyya:

import json

from pyya import init_config, logger

logger.setLevel(logging.INFO)

config = init_config(
    'config.yaml', 'default.config.yaml',
    convert_keys_to_snake_case = False,
    add_underscore_prefix_to_keywords = False,
    raise_error_non_identifiers = False,
    merge_configs = True,
    sections_ignored_on_merge = ['redis'], # do not include redis in your config
    validate_data_types = True,
    allow_extra_sections = True,
    warn_extra_sections = True,
    )
print(json.dumps(config))

# Output:
# 2025-09-05 09:13:17,280         WARNING         pyya            The following extra sections will be ignored:
# {'database.name': 'db'}
# 2025-09-05 09:13:17,281         INFO            pyya            The following sections were overwritten:
# {database: {'host': 'localhost', 'port': 5432}}
# {database: {"host": "localhost", "port": 5432, "username": "username", "password": "password"}}

As you can see, pyya automatically merges default config file with production config file.

Under the hood pyya uses PyYAML to parse YAML files and munch library to create attribute-stylish dictionaries.

Flags

# convert `camelCase` or `PascalCase` keys to `snake_case`
convert_keys_to_snake_case=False

# add underscore prefix to keys that are Python keywords
add_underscore_prefix_to_keywords=False

# raise error if key name is not valid Python identifier
raise_error_non_identifiers=False

# merge default and production configuration files
# setting to `False` disables below flags and makes default config optional
# `False` means "open config file and apply `yaml.safe_load` and `munchify` with specified formatting"
merge_configs=True

# list of sections to ignore when merging configs
# it is useful when you have examples in your default config but do not want to have in the main one
sections_ignored_on_merge=None

# raise error if data types in production config are not the same as default
# validation based on data types inferred from default config
validate_data_types=True

# raise error on any extra sections in production config
allow_extra_sections=True

# if extra sections are allowed, warn about extra keys and values
warn_extra_sections=True

Contributing

Are you a developer?

• Fork the repository https://github.com/shadowy-pycoder/pyya/fork
• Clone the repository: git clone https://github.com/<your-username>/pyya.git && cd pyya
• Create your feature branch: git switch -c my-new-feature
• Commit your changes: git commit -am 'Add some feature'
• Push to the branch: git push origin my-new-feature
• Submit a pull request