Config

Warnings

• breaking The underlying CFG configuration format used by this library introduced changes in syntax. Specifically, boolean and null literals changed from Python's `True`, `False`, `None` to JSON-compatible `true`, `false`, `null`. Also, cross-references evolved from `$A.B.C` to `${A.B.C}` for improved expressivity. Older configuration files using the deprecated syntax may fail to parse or produce unexpected results with newer versions of the library that adhere to the updated CFG format specification.
  Fix: Review and update existing `.cfg` files to conform to the latest CFG format syntax, particularly for boolean/null literals and cross-reference patterns.
• gotcha The library offers 'flexible access to real Python objects without full-blown eval()' as a feature. While this avoids direct `eval()`, constructing complex Python objects or invoking methods based on configuration values can still pose a security risk if configuration files are sourced from untrusted inputs, potentially leading to unintended code execution or resource manipulation.
  Fix: Always ensure configuration files come from trusted sources. Sanitize or validate complex configuration values if there's any doubt about their origin or content. Avoid allowing arbitrary object instantiation or method calls if security is paramount and config sources are not fully controlled.
• gotcha As with any configuration management system, storing sensitive information (e.g., API keys, database credentials) directly in plain text configuration files is a security risk. While the library supports environment variable integration, hardcoding secrets is a common footgun.
  Fix: Utilize environment variables (e.g., `os.environ.get('SECRET_KEY')`) or a dedicated secret management solution for sensitive data. Use environment variable fallbacks in your configuration files as demonstrated in the quickstart (e.g., `password: ${DB_PASSWORD|}`).

Install

• pip install config Install latest version

Imports

• Config

  from config import Config

• config module functions

  import config

  The module may also expose top-level functions, such as `config.create()` mentioned in some examples, for simpler setup without direct `Config` class instantiation.

Quickstart

This quickstart demonstrates how to load a configuration from a file using the `Config` class. It shows how to define sections, key-value pairs, references to other configuration values (e.g., `base_url`), and how to inject values from environment variables (e.g., `DB_USER`, `DB_PASSWORD`) with optional default fallbacks.

import os
from config import Config

# Create a dummy config file for demonstration
config_content = """
[DEFAULT]
log_level: INFO
data_path: /var/data

[server]
host: 127.0.0.1
port: ${server.default_port|8080}
base_url: http://${server.host}:${server.port}

[database]
type: postgres
host: db.example.com
user: ${DB_USER|guest}
password: ${DB_PASSWORD|}
"""

with open('example.cfg', 'w') as f:
    f.write(config_content)

# Set environment variables for demonstration
os.environ['DB_USER'] = 'admin'
os.environ['DB_PASSWORD'] = os.environ.get('TEST_DB_PASSWORD', 's3cr3t_p@ssw0rd')

# Load the configuration
cfg = Config('example.cfg')

# Access configuration values
print(f"Log Level: {cfg.log_level}")
print(f"Server Host: {cfg.server.host}")
print(f"Server Port: {cfg.server.port}")
print(f"Base URL: {cfg.server.base_url}")
print(f"DB User: {cfg.database.user}")
print(f"DB Password: {cfg.database.password}")

# Clean up the dummy config file
os.remove('example.cfg')

# Example of overriding a default with an environment variable
# The config file specifies `default_port: 8080`, but the example config uses a direct reference.
# Let's show how an environment variable for `DB_USER` works.
# Expected output for DB User: admin (from environment variable)
# Expected output for DB Password: s3cr3t_p@ssw0rd (from environment variable, if TEST_DB_PASSWORD is not set)