pyconfigurator: Easy Configuration Management

Common errors

• ModuleNotFoundError: No module named 'configurator'

  cause Attempting to import `Configurator` from `pyconfigurator` instead of `configurator`.
  fix Change your import statement from `from pyconfigurator import Configurator` to `from configurator import Configurator`.

• AttributeError: 'Configurator' object has no attribute 'some_missing_key'

  cause Attempting to access a configuration key that does not exist in any loaded configuration source.
  fix Ensure the key exists in your configuration files, environment variables, or CLI arguments. You can check for existence using `if 'some_key' in config.section:` or provide default values during access if the library supports it (though direct attribute access usually doesn't).

• FileNotFoundError: [Errno 2] No such file or directory: 'non_existent.ini'

  cause One of the files specified in the `files` argument to `Configurator` does not exist at the given path.
  fix Verify that all file paths provided to `Configurator(files=...)` are correct and the files actually exist. Use absolute paths or ensure your relative paths are correct from the execution directory.

Warnings

• gotcha The package name is `pyconfigurator` but the import path for the main class is `from configurator import Configurator`. Importing `from pyconfigurator import Configurator` will result in a `ModuleNotFoundError`.
  Fix: Always use `from configurator import Configurator`.
• gotcha Order of precedence for configuration sources matters. `pyconfigurator` loads files first, then applies environment variable substitutions/overrides, and finally command-line argument overrides. Be aware that later sources can overwrite values from earlier ones.
  Fix: Understand the loading order: files -> environment variables -> command-line arguments. Structure your configuration accordingly to ensure the correct values are applied.
• gotcha Starting with v0.4.19, `pyconfigurator` switched its internal parser implementation away from `SafeConfigParser`. While the public API (`Configurator`) remains stable, any code that directly interacted with or relied on specific internal behaviors of `SafeConfigParser` through private attributes might encounter issues.
  Fix: Avoid relying on `pyconfigurator`'s internal implementation details. Only interact with the documented public API of the `Configurator` object.

Install

• pip install pyconfigurator Install latest version

Imports

• Configurator
  wrong:

  from pyconfigurator import Configurator

  correct:

  from configurator import Configurator

  The package is named 'pyconfigurator' for PyPI, but the primary module is 'configurator'.

Quickstart

This quickstart demonstrates how to initialize `Configurator` with an INI file and environment variables, then access configuration settings using attribute-style access. It highlights environment variable substitution and default values.

import os
from configurator import Configurator

# 1. Create a dummy configuration file
config_file_path = 'my_app_config.ini'
with open(config_file_path, 'w') as f:
    f.write('[default]
app_name=MyApplication
data_path=/var/data
log_level=${LOG_LEVEL_ENV:INFO}

[database]
host=localhost
port=5432
user=admin
password=${DB_PASSWORD_ENV:secret}')

# 2. Set environment variables (optional, for demonstration)
os.environ['LOG_LEVEL_ENV'] = 'DEBUG'
# os.environ['DB_PASSWORD_ENV'] = 'super_secret'

# 3. Initialize the Configurator
# It loads files, then environment variables, then CLI args (if any)
config = Configurator(
    files=[config_file_path],
    environ=os.environ, # Pass os.environ to enable env var substitution
    # cli_args=['--database-user', 'cli_user'] # Example for CLI overrides
)

# 4. Access configuration values
print(f"Application Name: {config.default.app_name}")
print(f"Data Path: {config.default.data_path}")
print(f"Log Level: {config.default.log_level}")
print(f"Database Host: {config.database.host}")
print(f"Database User: {config.database.user}")
print(f"Database Password: {config.database.password}")

# Clean up the dummy file
os.remove(config_file_path)