{"id":8015,"library":"click-config-file","title":"click-config-file","description":"click-config-file is a Python library that provides configuration file support for Click applications. It simplifies adding configuration options to Click commands using a single decorator, handling sensible defaults and resolution order (CLI > Environment > Configuration file > Default). The current version is 0.6.0, with the latest release in April 2020, indicating a stable but infrequently updated project.","status":"active","version":"0.6.0","language":"en","source_language":"en","source_url":"https://github.com/phha/click_config_file","tags":["click","cli","configuration","config file","ini"],"install":[{"cmd":"pip install click-config-file","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for Click CLI applications.","package":"click","optional":false},{"reason":"Default configuration file parser provider. Can be replaced with custom providers.","package":"configobj","optional":false}],"imports":[{"symbol":"configuration_option","correct":"from click_config_file import configuration_option"}],"quickstart":{"code":"import click\nfrom click_config_file import configuration_option\nimport os\n\n# Create a dummy config file for demonstration\n# In a real scenario, this file would be created by the user\n# e.g., 'my_app.cfg' in the application directory or specified via --config\nwith open(\"my_app.cfg\", \"w\") as f:\n    f.write('name=\"Universe\"\\n')\n\n@click.command()\n@click.option('--name', default='World', help='Who to greet.')\n@configuration_option(\n    cmd_name='my_app', \n    config_file_name='my_app.cfg'\n)\ndef hello(name):\n    \"\"\"Simple program that greets NAME from config or CLI.\"\"\"\n    click.echo(f'Hello {name}!')\n\nif __name__ == '__main__':\n    print(\"--- Running with config file (name=Universe) ---\")\n    # Simulate running without CLI arguments to pick up config\n    hello.main(args=[]) \n\n    print(\"\\n--- Running with CLI argument (name=Multiverse) ---\")\n    # Simulate running with CLI arguments to override config\n    hello.main(args=['--name', 'Multiverse'])\n    \n    # Clean up dummy config file\n    os.remove(\"my_app.cfg\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"TypeError: Attempted to convert a callback into a command twice."},{"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]`).","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.","error":"Incorrect or unexpected parsing of options defined with `multiple=True` from a configuration file."}]}