coqpit

library0.0.17pypypi✓ verified 90d ago

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.

serialization

pip install coqpit

github ↗package ↗

INSTALL

IMPORT

SIG · COQPIT

coqpit

serializationpythonv0.0.17

Install

1.5s avg

Import

64ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.0.17 · 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.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.067s · 17.9MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 1.5s · import 0.060s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Coqpit

✓ from coqpit import Coqpit

BaseConfig

✓ from coqpit import BaseConfig

BaseConfig is an alias for Coqpit, use either.

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}")

Debug

Known issues

breakingAs 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)`.

affects: >=0.0.17

breakingSupport 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')`).

affects: 0.0.15

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.

affects: *

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

affects: >=0.0.16

Errors

Common errors & fixes

ValueError: list typehinted values require a default_factory for instantiation.

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'

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'

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.

Upgrade

Version history

0.0.17latest on PyPI · released Dec 21, 2022

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/coqui-ai/coqpit ↗

packagehttps://pypi.org/project/coqpit/ ↗