chz: Configuration Management

Warnings

• gotcha chz 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.
  Fix: Embrace immutability. If dynamic changes are needed, leverage `chz.Blueprint` for partial application or construct new configuration instances with updated values. Avoid direct field reassignment.
• gotcha Users 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.
  Fix: Refer to the official documentation's sections on `Blueprint` and partial application. Experiment with small, isolated examples to understand how configurations are composed and applied.
• breaking The `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.
  Fix: Stick 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.

Install

• pip install chz Install latest version

Imports

• Blueprint

  from chz 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

Quickstart

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