click-config-file

Common errors

• TypeError: Attempted to convert a callback into a command twice.

  cause This error typically occurs in Click when a function is decorated with both `@click.group()` and `@click.command()` or other conflicting decorators, which might happen inadvertently when adding `click-config-file`'s decorators.
  fix Ensure that a function is decorated as either a `click.command()` or a `click.group()`, but not both. Review your decorator stack and remove the conflicting decorator.

• Incorrect or unexpected parsing of options defined with `multiple=True` from a configuration file.

  cause When a Click option is defined with `multiple=True` (e.g., `--numbers TEXT --numbers TEXT`), `click-config-file` (and Click itself) expects the corresponding value from the configuration file to be a list or tuple of values. Providing a single string may result in unexpected string splitting (e.g., 'abc' becoming ['a', 'b', 'c']) or errors.
  fix Ensure that values for options defined with `multiple=True` are explicitly formatted as a list or array within your configuration file. For `configobj` (the default provider), this typically means space-separated values on a single line, which `configobj` will parse into a list. For other providers (e.g., YAML with a custom provider), use standard list syntax (e.g., `numbers: [1, 2, 3]`).

Warnings

• gotcha Typographical errors or unsupported options in the configuration file are silently ignored by click-config-file. This can lead to unexpected behavior and makes debugging misconfigurations difficult, as no warnings or errors are raised.
  Fix: Manually validate configuration keys against expected options within your Click command or implement a custom provider with validation logic. Consider using alternative libraries that offer strict validation if this is a critical requirement.
• gotcha The hierarchy for option resolution is strictly defined: Command-Line Interface (CLI) arguments override Environment Variables, which override Configuration File settings, which in turn override default option values. Misunderstanding this order can lead to unexpected values being applied.
  Fix: Always remember the precedence: CLI > Environment > Config File > Default. Design your application's configuration with this order in mind and clearly document it for users.
• gotcha The `configuration_option` decorator internally uses `is_eager=True`, which forces Click to invoke its callback before other options. If other Click options on the same command also set `is_eager=True`, it can lead to conflicts or unpredictable behavior regarding option parsing order.
  Fix: Be cautious when combining `configuration_option` with other custom Click decorators or options that modify the parsing process or rely on `is_eager=True`. Test combinations thoroughly. If conflicts arise, you may need to manually manage the `ctx.default_map` instead of relying solely on `configuration_option`.

Install

• pip install click-config-file Install stable version

Imports

• configuration_option

  from click_config_file import configuration_option

Quickstart

This example demonstrates how to add configuration file support to a Click command. By decorating with `configuration_option`, a `--config` option is automatically added (or an implicit config file is sought). The `cmd_name` and `config_file_name` arguments help locate the configuration file. Values from the config file are applied before CLI arguments.

import click
from click_config_file import configuration_option
import os

# Create a dummy config file for demonstration
# In a real scenario, this file would be created by the user
# e.g., 'my_app.cfg' in the application directory or specified via --config
with open("my_app.cfg", "w") as f:
    f.write('name="Universe"\n')

@click.command()
@click.option('--name', default='World', help='Who to greet.')
@configuration_option(
    cmd_name='my_app', 
    config_file_name='my_app.cfg'
)
def hello(name):
    """Simple program that greets NAME from config or CLI."""
    click.echo(f'Hello {name}!')

if __name__ == '__main__':
    print("--- Running with config file (name=Universe) ---")
    # Simulate running without CLI arguments to pick up config
    hello.main(args=[]) 

    print("\n--- Running with CLI argument (name=Multiverse) ---")
    # Simulate running with CLI arguments to override config
    hello.main(args=['--name', 'Multiverse'])
    
    # Clean up dummy config file
    os.remove("my_app.cfg")