confection

confection is a configuration library built by Explosion (the makers of spaCy) that lets you describe arbitrary trees of Python objects in a .cfg file and resolve them into fully instantiated function calls. Instead of exposing every hyperparameter as a CLI flag or environment variable, you register functions with a decorator, reference them by name in the config, and confection recursively builds the object graph — validating argument types along the way using Python type hints and optional Pydantic schemas.

What You Get

• A .cfg-based config format with sections, nested blocks, and ${section.value} variable interpolation
• A registry decorator system for mapping config blocks to registered Python functions/classes by name
• Type validation of resolved arguments via Python type hints, with optional Pydantic model support
• Versionable function registration so config-driven APIs can evolve without breaking old configs
• A Config object that round-trips cleanly between .cfg text and nested Python dicts

Common Use Cases

• Configuring ML training pipelines where hyperparameters live several function calls deep
• Powering spaCy and Thinc’s own config-driven model and pipeline definitions
• Building CLI or research tools that need reproducible, versioned experiment configs
• Replacing ad hoc argument-parsing/env-var configuration with a single declarative file

Under The Hood

Architecture: the core Config class (confection/_config.py) parses .cfg text into a nested dict via a small custom parser (_parser.py), then a separate resolution pass (_registry.py) walks the tree looking for @registered.function references and recursively instantiates them bottom-up, passing resolved child values as arguments to parent factory calls. Tech Stack: pure Python 3.10+ with no required third-party runtime dependency for core parsing, and an optional integration layer for Pydantic-based type validation (validation.py, typechecker.py). Code Quality: a large tests/ directory (including dedicated regression tests per historical GitHub issue, e.g. test_issue58.py) exercises parsing edge cases, error messages, and registry resolution, with ruff and pyright enforced via pyproject.toml/pyrightconfig.json. API Design: the @my_registry.optimizers("my_optimizer.v1")-style decorator plus INI config syntax keeps the public surface small — two or three concepts (Config, registry, resolve) cover the whole library, though the config format itself takes some getting used to versus plain Python kwargs.