Coqpit Configuration Management

Common errors

• ValueError: list typehinted values require a default_factory for instantiation.

  cause You defined a list field in your `Coqpit` dataclass without using `field(default_factory=list)`.
  fix Update your dataclass definition: `my_list_param: list[str] = field(default_factory=list)`.

• AttributeError: 'TextIOWrapper' object has no attribute 'read'

  cause You attempted to pass an open file handle (e.g., from `open()`) to `config.load_json()` or `config.save_json()`.
  fix Pass the file path as a string directly to `load_json()` or `save_json()`: `config.load_json('my_config.json')`.

• TypeError: __init__() got an unexpected keyword argument 'some_undefined_param'

  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.
  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.

Warnings

• breaking 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`.
  Fix: Change `my_list: list = []` to `my_list: list = field(default_factory=list)`.
• breaking 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.
  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')`).
• gotcha `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.
  Fix: Always provide explicit and correct type hints for all fields in your `Coqpit` subclass to ensure proper serialization and deserialization.
• gotcha 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.
  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`.

Install

• pip install coqpit Install latest version

Imports

• Coqpit

  from coqpit import Coqpit

• BaseConfig

  from coqpit import BaseConfig

  BaseConfig is an alias for Coqpit, use either.

Quickstart

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.

from coqpit import Coqpit
from dataclasses import dataclass, field
import os

@dataclass
class MyConfig(Coqpit):
    # Basic fields with defaults
    project_name: str = "MyProject"
    learning_rate: float = 1e-4
    epochs: int = 100
    is_train: bool = True
    
    # List and dict fields require default_factory for mutable defaults
    data_dirs: list[str] = field(default_factory=lambda: [os.path.join(".", "data")])
    model_params: dict = field(default_factory=lambda: {"layers": 3, "activation": "relu"})

# Instantiate with default values
config_default = MyConfig()
print(f"Default epochs: {config_default.epochs}")

# Instantiate and override values
config_custom = MyConfig(learning_rate=0.001, epochs=200)
print(f"Custom learning rate: {config_custom.learning_rate}, epochs: {config_custom.epochs}")

# Example of loading/saving (requires file I/O)
# config_custom.save_json("my_config.json")
# loaded_config = MyConfig().load_json("my_config.json")
# print(f"Loaded project name: {loaded_config.project_name}")
# os.remove("my_config.json")

# Example of parsing CLI arguments (run with e.g., python your_script.py --project_name NewProject)
# config_cli = MyConfig()
# config_cli.parse_args()
# print(f"CLI parsed project name: {config_cli.project_name}")