cfgv

library3.5.0pypypi✓ verified 26d ago

cfgv is a Python library designed to validate configuration files and produce human-readable error messages. The current version is 3.5.0, and it follows a regular release cadence with updates and improvements.

serialization

pip install cfgv

github ↗package ↗

INSTALL

IMPORT

SIG · CFGV

cfgv

serializationpythonv3.5.0

Install

1.6s avg

Import

14ms

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 v3.5.0 · 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.95 runs

installs and imports cleanly · install 0.0s · import 0.012s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.008s · 18MB

16MB installed

● package 16MB

Code

Verified usage

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

cfgv

✓ import cfgv

Ensure correct import path to avoid ImportError

A simple example demonstrating how to define a schema, load a configuration, and validate it using cfgv.

import cfgv # Define your configuration schema schema = { 'host': str, 'port': int, 'debug': bool } # Load your configuration config = { 'host': 'localhost', 'port': 8080, 'debug': True } # Validate the configuration cfgv.validate(config, schema)

Debug

Known issues

breakingIn version 3.5.0, the validate function now raises a ValidationError instead of returning a boolean value. Ensure your code handles this exception appropriately.

fix

Update your code to handle ValidationError exceptions raised by the validate function.

affects: 3.5.0

gotchaWhen defining schemas, ensure that all required fields are included to prevent validation errors. Missing fields can lead to unexpected behavior.

fix

Always include all required fields in your schema definitions.

affects: all

breakingThe 'schema' argument passed to `cfgv.validate` must be a cfgv schema object (e.g., `cfgv.Map`, `cfgv.Required`), not a raw Python dictionary. Passing a dictionary leads to an `AttributeError: 'dict' object has no attribute 'check'`.

fix

Ensure the 'schema' argument is a cfgv schema object, typically constructed using `cfgv.Map`, `cfgv.Map(cfgv.Required(...))`, `cfgv.Sequence`, etc., before passing it to `cfgv.validate`.

affects: all

breakingThe `schema` argument to `cfgv.validate` must be a `cfgv` schema object (e.g., `cfgv.Map`, `cfgv.Required`, etc.), not a plain Python dictionary. Passing a dictionary will raise an `AttributeError` because dictionaries lack the `check` method required by the validation process.

fix

Ensure the `schema` argument passed to `cfgv.validate` is an instantiated `cfgv` schema object (e.g., `schema = cfgv.Map(...)`), not a raw Python dictionary.

affects: all

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'cfgv'

The 'cfgv' library is not installed in your Python environment or the environment where your code is being executed.

fix

Install the 'cfgv' library using pip: `pip install cfgv`

cfgv.ValidationError: Expected <type> got <other_type>

The provided configuration value does not match the expected type defined in your 'cfgv' schema.

fix

Adjust the input data to conform to the type specified in the `cfgv` schema, or modify your schema definition to correctly reflect the expected data type. For example, if 'Expected bool got str.', change the string value to a boolean.

TypeError: 'Map' object is not callable

This error typically occurs when you attempt to call a `cfgv.Map` (or other schema object like `Required`, `Optional`) directly as a function, rather than passing it as an argument to `cfgv.validate` or using it correctly within a schema definition.

fix

Ensure you are using `cfgv.Map` and other schema components correctly in your schema definition and passing the schema object to `cfgv.validate(value, schema)`.

Upgrade

Version history

3.5.0latest on PyPI · released Nov 19, 2025

Audit

Dependencies

pyyamlrequiredRequired for YAML file parsing

Agent activity

67 hits · last 30 days

node

Bingbot

Amazon

OpenAI (training)

Resources

githubhttps://github.com/asottile/cfgv ↗

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