AnyConfig

Warnings

• gotcha AnyConfig dynamically loads backend parsers. If a dependency for a specific format (e.g., `PyYAML` or `toml`) is not installed, that format will silently not be supported, which can lead to unexpected errors if not handled.
  Fix: Ensure all necessary backend packages for the formats you intend to use are installed. The official documentation lists the required dependencies for each format. For example, `pip install anyconfig[yaml,toml]`.
• gotcha Template processing (e.g., Jinja2) within configuration files is disabled by default to prevent unintended side effects. If your configuration files use templating features, they will not be rendered unless explicitly enabled.
  Fix: When calling `anyconfig.load()` or `anyconfig.loads()`, pass `ac_template=True` to enable template rendering. You may also provide a context dictionary via `ac_context` for template variables, e.g., `anyconfig.load(path, ac_template=True, ac_context={'VAR': 'value'})` or `ac_context=os.environ`.
• gotcha When dumping YAML files, using the default `PyYAML` backend may result in loss of comments, key order, and specific formatting (e.g., block vs. flow style). This is due to `PyYAML`'s limitations in round-trip preservation.
  Fix: Install `ruamel.yaml` (e.g., `pip install 'anyconfig[yaml]' ruamel.yaml`) and ensure it's available. `anyconfig` will prefer `ruamel.yaml` if installed, which offers superior round-trip preservation for YAML, retaining comments and ordering.
• gotcha When loading multiple configuration files, `anyconfig` employs a default recursive merge strategy (`anyconfig.MS_DICTS`). This might not be the desired behavior if a simple overwrite or a different merge logic is expected.
  Fix: Specify the desired merge strategy using the `ac_merge` parameter in `anyconfig.load()`. Available strategies include `anyconfig.MS_REPLACE` (later values replace earlier ones), `anyconfig.MS_NO_REPLACE` (earlier values are kept), and `anyconfig.MS_DICTS_AND_LISTS` (recursive merge for both dicts and lists).

Install

• pip install anyconfig Base Installation
• pip install anyconfig[yaml,toml,xml,msgpack,configobj,bson,ini,properties] Installation with common backends
• pip install 'anyconfig[yaml]==0.15.1' 'ruamel.yaml<0.18' Install with ruamel.yaml for YAML 1.2 and round-trip support

Imports

• anyconfig.load

  import anyconfig
  config = anyconfig.load('config.yaml')

• anyconfig.dump

  import anyconfig
  anyconfig.dump(data, 'output.json')

• anyconfig.loads

  import anyconfig
  config = anyconfig.loads('key: value', ac_parser='yaml')

• anyconfig.dumps

  import anyconfig
  config_str = anyconfig.dumps({'key': 'value'}, ac_parser='json')

Quickstart

This quickstart demonstrates how to load a YAML configuration file using `anyconfig.load()`. It highlights automatic format detection by file extension and the use of Jinja2 templating to resolve environment variables within the configuration. It also shows how to dump the loaded configuration to a different format like JSON.

import anyconfig
import os

# Create a dummy YAML config file for demonstration
config_content = """
app:
  name: MyWebApp
  version: 1.0.0
database:
  host: localhost
  port: 5432
  user: dbuser
  password: ${DB_PASSWORD|default_secret}
"""

config_file_path = "./app_config.yaml"
with open(config_file_path, "w") as f:
    f.write(config_content)

# Set an environment variable for template processing (optional)
os.environ['DB_PASSWORD'] = 'supersecurepassword'

# Load the configuration, enabling template processing
config = anyconfig.load(config_file_path, ac_template=True, ac_context=os.environ)

print(f"Application Name: {config['app']['name']}")
print(f"Database Host: {config['database']['host']}")
print(f"Database Password: {config['database']['password']}")

# Example of dumping to another format (e.g., JSON)
output_json_path = "./app_config.json"
anyconfig.dump(config, output_json_path, ac_parser='json', indent=2)
print(f"Configuration dumped to {output_json_path}")

# Clean up dummy files
os.remove(config_file_path)
os.remove(output_json_path)