Install & Compatibility
Where this runs
tested against v0.4.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
py 3.10
✕ build_error
✕ build_error
py 3.9
✕ build_error
✕ build_error
15MB installed
● package 15MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Blueprint
✓ from chz import Blueprint
✗ from chz.blueprint import Blueprint
While 'blueprint' is a core concept, it's typically imported directly from the top-level 'chz' package, not a submodule.
Field
✓ from chz import Field
This quickstart defines a simple configuration using a `chz.Blueprint` class with `Field`s for type hints, defaults, and help text. It then shows how to use this configuration in a `main` function. In a command-line scenario, `chz` would automatically parse arguments into this `Config` object. For programmatic use, you can instantiate `Config` directly.
from chz import Blueprint, Field
class Config(Blueprint):
name: str = Field(default='World', help='The name to greet')
loud: bool = Field(default=False, help='Whether to shout the greeting')
def main(config: Config):
greeting = f'Hello, {config.name}!'
if config.loud:
greeting = greeting.upper()
print(greeting)
if __name__ == '__main__':
# Example of how to run from a script with overrides
# In a real CLI, this would be parsed from command-line arguments
# To simulate command line: python your_script.py --name Alice --loud
# Or, using the Blueprint directly for programmatic use:
try:
# Simulate parsing command line arguments or provide defaults
# For simplicity in quickstart, directly create a config instance.
# In a CLI application, you'd use Blueprint.apply_args() or similar.
my_config = Config(name='Registry', loud=True)
main(my_config)
except Exception as e:
print(f"Error running quickstart: {e}")
Debug
Known issues
gotchachz objects are designed to be immutable; you cannot reassign fields after creation. This is a deliberate design choice to prevent certain classes of configuration bugs. If you find yourself frequently needing to modify configurations, consider using `Blueprint`'s partial application features or creating new instances instead of trying to mutate existing ones.fixEmbrace immutability. If dynamic changes are needed, leverage `chz.Blueprint` for partial application or construct new configuration instances with updated values. Avoid direct field reassignment.
affects: All versions
gotchaUsers new to `chz.Blueprint` might experience a learning curve, particularly with concepts like partial application and how configurations are built up. The power comes from its flexibility in defining and combining configuration parts, but this can be unfamiliar initially.fixRefer to the official documentation's sections on `Blueprint` and partial application. Experiment with small, isolated examples to understand how configurations are composed and applied.
affects: All versions
breakingThe `CHANGELOG.md` indicates significant internal refactoring, especially around `blueprint` and `meta_factory` unification in March 2025 and November 2024. While direct user-facing API changes are not explicitly flagged as 'breaking' for stable releases, these internal shifts suggest that relying on undocumented internal behaviors could lead to breakage in minor or patch releases.fixStick to the documented public API. Avoid deep introspection or reliance on internal `chz` structures. Regularly review `CHANGELOG.md` for major refactorings that might indirectly impact complex integrations, even if not explicitly marked as breaking.
affects: Versions prior to 0.3.0 and 0.4.0 (November 2024 and March 2025 changes)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'chz'
The 'chz' library is not installed in the current Python environment or the Python interpreter cannot find it in its search path.
fixInstall the library using pip: `pip install chz`
AttributeError: 'Blueprint' object has no attribute 'undeclared_field'
You are attempting to access a configuration field or attribute on a `chz` Blueprint or configuration object that has not been explicitly defined in your declarative model. `chz` aims to provide native Python suggestions for such attribute access errors.
fixEnsure that all accessed fields are correctly defined as part of your `chz` configuration Blueprint. For example, if 'undeclared_field' is intended, it must be declared within the Blueprint class.
TypeError: Value for field 'config_item' has unexpected type <class 'int'>, expected <class 'str'>
A value provided for a `chz` configuration field does not match the expected type annotation defined in the Blueprint, indicating a type mismatch during validation.
fixProvide a value that matches the declared type for the field. For instance, if `config_item` expects a `str`, ensure you pass a string value.
chz.exceptions.ConfigurationError: Ambiguous definition: multiple classes named 'MyConfig' found.
This error occurs when `chz` detects multiple configuration Blueprint classes with the same name within the scope it is searching, making it ambiguous which definition to use.
fixRename your configuration Blueprint classes to have unique names, or explicitly specify the exact module path to the intended class when loading your configuration.
Upgrade
Version history
0.4.0latest on PyPI · released Nov 24, 2025
Audit
Dependencies
typing-extensionsrequiredProvides backports of new type features for older Python versions, required by chz.