Install & Compatibility
Where this runs
tested against v0.2.3 · 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
muslpy 3.10–3.960 runs
installs and imports cleanly · install 0.0s · import 0.078s · 18.9MB
glibcpy 3.10–3.960 runs
installs and imports cleanly · install 1.7s · import 0.070s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ConfigFileReader
✓ from click_configfile import ConfigFileReader
Param
✓ from click_configfile import Param
SectionSchema
✓ from click_configfile import SectionSchema
matches_section
✓ from click_configfile import matches_section
assign_param_names
✓ from click_configfile import assign_param_names
This example demonstrates how to set up a Click command to read configuration from a file. It defines a schema for a 'main' section, specifies `myconfig.ini` as the config file, and integrates its values into Click's `default_map`. Run `python your_script.py` to see config values applied, or `python your_script.py --name CLIUser --value 123` to observe command-line parameter precedence over config file values.
import click
from click_configfile import ConfigFileReader, Param, SectionSchema, matches_section
import os
# Create a dummy config file for demonstration
config_content = """
[main]
name = RegistryUser
value = 42
"""
config_file_path = "myconfig.ini"
with open(config_file_path, "w") as f:
f.write(config_content)
# Define your config file schema
@matches_section("main")
class ConfigSectionSchema(SectionSchema):
name = Param(type=str, default="world")
value = Param(type=int, default=10)
# Create a config file reader instance
class MyConfigFileReader(ConfigFileReader):
# Prioritize 'myconfig.ini' in the current directory
config_files = [f"./{config_file_path}"]
config_section_schemas = [ConfigSectionSchema]
# Decorator to apply config file processing
@click.command(context_settings=dict(default_map=MyConfigFileReader.read_config()))
@click.option("--name", default=None, help="Name to greet.")
@click.option("--value", default=None, type=int, help="A numeric value.")
def cli(name, value):
"""A simple CLI that uses a config file."""
# If 'name' or 'value' were not provided via CLI, they'll come from default_map (config or Param default)
name_to_use = name if name is not None else ConfigSectionSchema.name.default
value_to_use = value if value is not None else ConfigSectionSchema.value.default
click.echo(f"Hello, {name_to_use}! Your value is {value_to_use}.")
click.echo(f"Config files searched: {MyConfigFileReader.config_files}")
click.echo(f"Default map from config: {MyConfigFileReader.read_config()}")
# Clean up the dummy config file
os.remove(config_file_path)
if __name__ == "__main__":
cli()
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'json5'
Attempting to read a JSON config file without installing the optional `json5` dependency.
fixInstall `click-configfile` with JSON support: `pip install click-configfile[json]`.
ModuleNotFoundError: No module named 'PyYAML'
Attempting to read a YAML config file without installing the optional `PyYAML` dependency.
fixInstall `click-configfile` with YAML support: `pip install click-configfile[yaml]`.
ValueError: Invalid type for parameter 'value'. Expected <class 'int'>, got 'a_string'
A value in the configuration file does not match the expected type defined in the `Param` in your `SectionSchema`.
fixEnsure that values in your config file (e.g., `value = a_string`) match the `type` specified in your `Param` definition (e.g., `value = Param(type=int)`).
Config values are not being applied, even though the file exists.
The section name in the config file does not match the `@matches_section` decorator, or the parameter names don't match the `Param` definitions, or the file path is incorrect.
fixVerify that `ConfigFileReader.config_files` contains the correct path, the `[section]` name in your config file matches `@matches_section`, and parameter keys (e.g., `name = ...`) match `Param(name='name', ...)`.
Upgrade
Version history
0.2.3latest on PyPI · released Sep 24, 2017
Audit
Dependencies
clickrequiredCore dependency for CLI applications.
json5optionalOptional dependency for JSON config file parsing.
PyYAMLoptionalOptional dependency for YAML config file parsing.