Registry / serialization / click-config-file

click-config-file

JSON →
library0.6.0pypypi✓ verified 87d ago

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.

pip install click-config-file
INSTALL
IMPORT
SIG · CLICK-CONFIG-FILE
C
click-config-file
serializationpythonv0.6.0
Install
1.7s avg
Import
78ms
Disk
17MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.6.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.081s · 18.9MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 1.7s · import 0.075s · 19MB
17MB installed
● package 17MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

configuration_option
from click_config_file import configuration_option

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")
Debug
Known issues
gotchaTypographical 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.
affects: All versions
gotchaThe 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.
affects: All versions
gotchaThe `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`.
affects: All versions
Errors
Common errors & fixes
TypeError: Attempted to convert a callback into a command twice.
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.
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]`).
Upgrade
Version history
0.6.0latest on PyPI · released Apr 28, 2020
Audit
Dependencies
clickrequiredCore dependency for Click CLI applications.
configobjrequiredDefault configuration file parser provider. Can be replaced with custom providers.
Agent activity
9 hits · last 30 days
node
8
OpenAI (training)
1
Resources
click-config-file — pip install click-config-file · libregistry