{"id":5877,"library":"chz","title":"chz: Configuration Management","description":"chz (pronounced \"चीज़\") is a Python library designed for managing configuration, particularly from the command line. It features a declarative object model, immutability, validation, and type checking. Currently at version 0.4.0, it appears to have a relatively active release cadence with several updates in the past year.","status":"active","version":"0.4.0","language":"en","source_language":"en","source_url":"https://github.com/openai/chz","tags":["configuration","cli","dataclasses","validation","immutability","type-checking"],"install":[{"cmd":"pip install chz","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Provides backports of new type features for older Python versions, required by chz.","package":"typing-extensions","optional":false}],"imports":[{"note":"While 'blueprint' is a core concept, it's typically imported directly from the top-level 'chz' package, not a submodule.","wrong":"from chz.blueprint import Blueprint","symbol":"Blueprint","correct":"from chz import Blueprint"},{"symbol":"Field","correct":"from chz import Field"}],"quickstart":{"code":"from chz import Blueprint, Field\n\nclass Config(Blueprint):\n    name: str = Field(default='World', help='The name to greet')\n    loud: bool = Field(default=False, help='Whether to shout the greeting')\n\ndef main(config: Config):\n    greeting = f'Hello, {config.name}!'\n    if config.loud:\n        greeting = greeting.upper()\n    print(greeting)\n\nif __name__ == '__main__':\n    # Example of how to run from a script with overrides\n    # In a real CLI, this would be parsed from command-line arguments\n    # To simulate command line: python your_script.py --name Alice --loud\n    # Or, using the Blueprint directly for programmatic use:\n    try:\n        # Simulate parsing command line arguments or provide defaults\n        # For simplicity in quickstart, directly create a config instance.\n        # In a CLI application, you'd use Blueprint.apply_args() or similar.\n        my_config = Config(name='Registry', loud=True)\n        main(my_config)\n    except Exception as e:\n        print(f\"Error running quickstart: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"Versions prior to 0.3.0 and 0.4.0 (November 2024 and March 2025 changes)"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}