Registry / serialization / click-configfile

click-configfile

JSON →
library0.2.3pypypi✓ verified 86d ago

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.

pip install click-configfile
INSTALL
IMPORT
SIG · CLICK-CONFIGFILE
C
click-configfile
serializationpythonv0.2.3
Install
1.7s avg
Import
74ms
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.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
musl
py 3.103.960 runs
installs and imports cleanly · install 0.0s · import 0.078s · 18.9MB
glibc
py 3.103.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()
Debug
Known issues
gotchaTo 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.
fix
Install with `pip install click-configfile[json]` or `pip install click-configfile[yaml]`.
affects: All versions
gotchaConfiguration 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.
fix
Be aware of Click's precedence rules: command-line > environment variables > config file (via `default_map`) > Click `default`.
affects: All versions
gotchaIf `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.
fix
Order `config_files` carefully. If you need to merge values from multiple files, you would need to implement custom logic.
affects: All versions
gotchaSections 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.
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")`).
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'json5'
Attempting to read a JSON config file without installing the optional `json5` dependency.
fix
Install `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.
fix
Install `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`.
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)`).
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.
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', ...)`.
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.
Agent activity
16 hits · last 30 days
node
14
OpenAI (training)
1
Resources
click-configfile — pip install click-configfile · libregistry