{"id":9620,"library":"coqpit","title":"Coqpit Configuration Management","description":"Coqpit is a lightweight configuration management library built around Python dataclasses. It simplifies defining, loading, and parsing configurations from various sources (JSON, YAML, CLI arguments) by leveraging dataclass features. Developed by Coqui-AI, it has a rapid release cycle with frequent minor updates.","status":"active","version":"0.0.17","language":"en","source_language":"en","source_url":"https://github.com/coqui-ai/coqpit","tags":["configuration","dataclass","cli","coqui-ai","json","yaml"],"install":[{"cmd":"pip install coqpit","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"Coqpit","correct":"from coqpit import Coqpit"},{"note":"BaseConfig is an alias for Coqpit, use either.","symbol":"BaseConfig","correct":"from coqpit import BaseConfig"}],"quickstart":{"code":"from coqpit import Coqpit\nfrom dataclasses import dataclass, field\nimport os\n\n@dataclass\nclass MyConfig(Coqpit):\n    # Basic fields with defaults\n    project_name: str = \"MyProject\"\n    learning_rate: float = 1e-4\n    epochs: int = 100\n    is_train: bool = True\n    \n    # List and dict fields require default_factory for mutable defaults\n    data_dirs: list[str] = field(default_factory=lambda: [os.path.join(\".\", \"data\")])\n    model_params: dict = field(default_factory=lambda: {\"layers\": 3, \"activation\": \"relu\"})\n\n# Instantiate with default values\nconfig_default = MyConfig()\nprint(f\"Default epochs: {config_default.epochs}\")\n\n# Instantiate and override values\nconfig_custom = MyConfig(learning_rate=0.001, epochs=200)\nprint(f\"Custom learning rate: {config_custom.learning_rate}, epochs: {config_custom.epochs}\")\n\n# Example of loading/saving (requires file I/O)\n# config_custom.save_json(\"my_config.json\")\n# loaded_config = MyConfig().load_json(\"my_config.json\")\n# print(f\"Loaded project name: {loaded_config.project_name}\")\n# os.remove(\"my_config.json\")\n\n# Example of parsing CLI arguments (run with e.g., python your_script.py --project_name NewProject)\n# config_cli = MyConfig()\n# config_cli.parse_args()\n# print(f\"CLI parsed project name: {config_cli.project_name}\")","lang":"python","description":"Define your configuration by inheriting from `Coqpit` and using Python dataclasses. Fields can have default values. For mutable defaults (lists, dicts), always use `field(default_factory=...)`. Instantiate the config directly or use `parse_args()` to integrate with `argparse`, or `load_json`/`load_yaml` for file-based configuration."},"warnings":[{"fix":"Change `my_list: list = []` to `my_list: list = field(default_factory=list)`.","message":"As of v0.0.17, `Coqpit` strictly enforces `default_factory` for mutable list type hints. Defining a `list` field without `field(default_factory=...)` will now raise a `ValueError`.","severity":"breaking","affected_versions":">=0.0.17"},{"fix":"Always pass a string representing the file path (e.g., `'config.json'`) instead of an open file handle (e.g., `open('config.json', 'r')`).","message":"Support for passing file-like objects to `load_json` and `save_json` was briefly introduced in v0.0.15 but reverted in the same version due to issues. `Coqpit` now expects file paths (strings) for these methods.","severity":"breaking","affected_versions":"0.0.15"},{"fix":"Always provide explicit and correct type hints for all fields in your `Coqpit` subclass to ensure proper serialization and deserialization.","message":"`Coqpit` relies heavily on Python's dataclass type hinting. Missing or incorrect type hints for your configuration fields can lead to unexpected behavior during deserialization from JSON/YAML or when parsing CLI arguments.","severity":"gotcha","affected_versions":"*"},{"fix":"Be aware that `None` values in your config file might be replaced by dataclass defaults. For fields that must be explicitly present, consider setting `default_factory=lambda: ...` with a sentinel value and custom validation, or checking for `None` after loading if the default is not `None`.","message":"From v0.0.16, `Coqpit` deserializes using default values if a field in the loaded configuration is `None` or implicitly missing. This can sometimes mask missing data in your config file, as the dataclass default will be used instead of signaling an error for a truly absent value.","severity":"gotcha","affected_versions":">=0.0.16"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Update your dataclass definition: `my_list_param: list[str] = field(default_factory=list)`.","cause":"You defined a list field in your `Coqpit` dataclass without using `field(default_factory=list)`.","error":"ValueError: list typehinted values require a default_factory for instantiation."},{"fix":"Pass the file path as a string directly to `load_json()` or `save_json()`: `config.load_json('my_config.json')`.","cause":"You attempted to pass an open file handle (e.g., from `open()`) to `config.load_json()` or `config.save_json()`.","error":"AttributeError: 'TextIOWrapper' object has no attribute 'read'"},{"fix":"Ensure all parameters in your configuration sources are explicitly defined as fields in your `Coqpit` dataclass, or remove the undefined parameter from the source.","cause":"Your configuration source (JSON, YAML, or CLI) included a parameter (`some_undefined_param`) that is not defined as a field in your `Coqpit` subclass.","error":"TypeError: __init__() got an unexpected keyword argument 'some_undefined_param'"}]}