Install & Compatibility
Where this runs
tested against v1.3.3 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.114s · 18.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.1s · import 0.100s · 19MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Config
✓ from confection import Config
set_registry
✓ from confection import set_registry
This quickstart demonstrates how to define a function in the registry, create a `Config` object, and resolve the configuration to execute the registered function with provided arguments. It also shows an example of loading a config from a string.
from confection import Config, set_registry
@set_registry("my_functions", "add")
def add_function(a: int, b: int):
return a + b
config = Config({"model": {"func": {"@my_functions": "add"}, "a": 1, "b": 2}})
resolved = config.resolve()
result = resolved["model"]["func"](resolved["model"]["a"], resolved["model"]["b"])
print(f"Result: {result}")
# Example with direct config creation
config_direct = Config().from_str("""
[model]
func = @my_functions.add
a = 10
b = 20
""")
resolved_direct = config_direct.resolve()
result_direct = resolved_direct["model"]["func"](resolved_direct["model"]["a"], resolved_direct["model"]["b"])
print(f"Direct Config Result: {result_direct}")
Debug
Known issues
breakingConfection v1.1.0 and later dropped support for Pydantic for validation, reverting to custom validation logic. If you were relying on Pydantic's specific validation behaviors with older versions, your configurations might behave differently or break.fixReview your configurations and update them to align with Confection's custom validation logic. Test thoroughly, especially if you had complex Pydantic validation schemas.
affects: >=1.1.0
gotchaPrior to v1.3.3, Python-style boolean (True, False) and None literals in configuration files were silently treated as strings instead of their corresponding Python types. This could lead to type errors, especially with newer Pydantic versions.fixUpgrade to confection v1.3.3 or later. If unable to upgrade, explicitly quote 'true', 'false', and 'null' as JSON-style lowercase literals in your config files, or ensure your consuming code handles string-based booleans/None.
affects: <1.3.3
breakingChanges in Pydantic v2 support across Confection versions (v1.0.0, v1.0.0a2, v1.1.0) could lead to compatibility issues. If you're using Pydantic in conjunction with Confection, ensure your Confection version aligns with the Pydantic version you're using.fixFor Pydantic v2 compatibility, Confection v1.0.0 and v1.0.0a2 aimed to support it. However, v1.1.0 reverted away from Pydantic entirely. The most stable approach is to use Confection v1.1.0 or newer if you wish to avoid Pydantic dependencies, or carefully test specific versions if Pydantic integration is critical.
affects: 1.0.0, 1.0.0a2, 1.1.0
gotchaWhen using `Config.from_str()` for loading configurations, pay close attention to the YAML/INI-like syntax. Incorrect indentation or malformed sections can lead to parsing errors. For example, top-level section references have had bug fixes.fixAlways validate your configuration strings carefully. Refer to the Confection documentation for the precise syntax. For older versions, be aware of potential issues with complex section references and consider upgrading to v1.2.0 or newer for bug fixes related to parsing.
affects: <1.2.0
breakingThe `set_registry` function was removed from the top-level `confection` module API. Attempting to import it directly will result in an ImportError.fixUpdate your import statements. Instead of `from confection import set_registry`, use `from confection import registry` and then access `registry.set` or `registry.register` for managing your registry entries.
affects: >=1.0.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'confection'
The 'confection' library is not installed in the Python environment being used.
fixInstall the library using pip: `pip install confection`
ConfigValidationError: Invalid config value for '...' (e.g., expected float but got string)
The configuration provided contains values that do not match the expected data types or schema defined by `confection`'s validation rules or type hints in registered functions.
fixReview your configuration file or dictionary and ensure all values conform to the expected types and structure for the respective settings, as indicated by the error message's specifics. For example, change a string to a float if required.
confection Cannot interpolate unknown variable
The configuration attempts to use an interpolation variable (e.g., `${vars.my_variable}`) that has not been defined or cannot be resolved within the configuration's scope.
fixDefine the missing variable in a `[vars]` section of your configuration or ensure the variable name is correctly spelled and accessible.
TypeError: argument 'x' has unexpected type 'y' in Confection config
During the processing or resolution of the `confection` configuration, a function or method received an argument of an incorrect Python type, often due to a mismatch between the config value and a function's type annotation.
fixAdjust the configuration value to match the expected type, or ensure the registered function's type hints accurately reflect the types of arguments it can receive from the configuration.
AttributeError: 'Config' object has no attribute '...' (e.g., 'optimizer')
You are attempting to access a key or section of the `Config` object that either does not exist, has not yet been resolved by `registry.resolve()`, or is misspelled.
fixVerify the key name is correct and present in your configuration. If the key refers to a registered function, ensure `registry.resolve(config)` has been called and the result is being accessed, or that the registry itself is correctly set up.
Upgrade
Version history
1.3.3latest on PyPI · released Mar 24, 2026
Audit
Dependencies
No dependency data recorded yet.