{"id":7085,"library":"click-configfile","title":"click-configfile","description":"click-configfile extends Click commands with support for configuration files. It enables parsing of various formats (INI, JSON, YAML) through a defined schema, seamlessly integrating configuration values into Click's default parameter map. It is currently at version 0.2.3 and has a stable, low-cadence release cycle.","status":"active","version":"0.2.3","language":"en","source_language":"en","source_url":"https://github.com/click-contrib/click-configfile","tags":["click","cli","configuration","config file","ini","json","yaml"],"install":[{"cmd":"pip install click-configfile","lang":"bash","label":"Install base package"},{"cmd":"pip install click-configfile[json]","lang":"bash","label":"Install with JSON support"},{"cmd":"pip install click-configfile[yaml]","lang":"bash","label":"Install with YAML support"}],"dependencies":[{"reason":"Core dependency for CLI applications.","package":"click"},{"reason":"Optional dependency for JSON config file parsing.","package":"json5","optional":true},{"reason":"Optional dependency for YAML config file parsing.","package":"PyYAML","optional":true}],"imports":[{"symbol":"ConfigFileReader","correct":"from click_configfile import ConfigFileReader"},{"symbol":"Param","correct":"from click_configfile import Param"},{"symbol":"SectionSchema","correct":"from click_configfile import SectionSchema"},{"symbol":"matches_section","correct":"from click_configfile import matches_section"},{"symbol":"assign_param_names","correct":"from click_configfile import assign_param_names"}],"quickstart":{"code":"import click\nfrom click_configfile import ConfigFileReader, Param, SectionSchema, matches_section\nimport os\n\n# Create a dummy config file for demonstration\nconfig_content = \"\"\"\n[main]\nname = RegistryUser\nvalue = 42\n\"\"\"\nconfig_file_path = \"myconfig.ini\"\nwith open(config_file_path, \"w\") as f:\n    f.write(config_content)\n\n# Define your config file schema\n@matches_section(\"main\")\nclass ConfigSectionSchema(SectionSchema):\n    name = Param(type=str, default=\"world\")\n    value = Param(type=int, default=10)\n\n# Create a config file reader instance\nclass MyConfigFileReader(ConfigFileReader):\n    # Prioritize 'myconfig.ini' in the current directory\n    config_files = [f\"./{config_file_path}\"]\n    config_section_schemas = [ConfigSectionSchema]\n\n# Decorator to apply config file processing\n@click.command(context_settings=dict(default_map=MyConfigFileReader.read_config()))\n@click.option(\"--name\", default=None, help=\"Name to greet.\")\n@click.option(\"--value\", default=None, type=int, help=\"A numeric value.\")\ndef cli(name, value):\n    \"\"\"A simple CLI that uses a config file.\"\"\"\n    # If 'name' or 'value' were not provided via CLI, they'll come from default_map (config or Param default)\n    name_to_use = name if name is not None else ConfigSectionSchema.name.default\n    value_to_use = value if value is not None else ConfigSectionSchema.value.default\n\n    click.echo(f\"Hello, {name_to_use}! Your value is {value_to_use}.\")\n    click.echo(f\"Config files searched: {MyConfigFileReader.config_files}\")\n    click.echo(f\"Default map from config: {MyConfigFileReader.read_config()}\")\n\n    # Clean up the dummy config file\n    os.remove(config_file_path)\n\nif __name__ == \"__main__\":\n    cli()","lang":"python","description":"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."},"warnings":[{"fix":"Install with `pip install click-configfile[json]` or `pip install click-configfile[yaml]`.","message":"To use JSON or YAML configuration files, you must install the respective optional dependencies (json5 or PyYAML). Without them, `ConfigFileReader` will fail if it encounters these file types.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware of Click's precedence rules: command-line > environment variables > config file (via `default_map`) > Click `default`.","message":"Configuration values from files are populated into Click's `default_map`. Command-line arguments explicitly provided by the user will always override values from the configuration file.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Order `config_files` carefully. If you need to merge values from multiple files, you would need to implement custom logic.","message":"If `ConfigFileReader.config_files` contains multiple paths, files are searched in the order specified. The first file found and successfully parsed will be used. Later files are ignored.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure section names in your config files (e.g., `[main]` for INI) correspond directly to the argument passed to `@matches_section` (e.g., `matches_section(\"main\")`).","message":"Sections in the config file must exactly match the section names specified by the `@matches_section` decorator in your `SectionSchema` classes. Mismatches will result in those sections not being parsed.","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":"Install `click-configfile` with JSON support: `pip install click-configfile[json]`.","cause":"Attempting to read a JSON config file without installing the optional `json5` dependency.","error":"ModuleNotFoundError: No module named 'json5'"},{"fix":"Install `click-configfile` with YAML support: `pip install click-configfile[yaml]`.","cause":"Attempting to read a YAML config file without installing the optional `PyYAML` dependency.","error":"ModuleNotFoundError: No module named 'PyYAML'"},{"fix":"Ensure 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)`).","cause":"A value in the configuration file does not match the expected type defined in the `Param` in your `SectionSchema`.","error":"ValueError: Invalid type for parameter 'value'. Expected <class 'int'>, got 'a_string'"},{"fix":"Verify 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', ...)`.","cause":"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.","error":"Config values are not being applied, even though the file exists."}]}