Install & Compatibility
Where this runs
tested against v0.3.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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.962s · 41MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.0s · import 0.843s · 42MB
41MB installed
● package 41MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
fiddle
✓ import fiddle as fdl
The official documentation and examples consistently use the `fdl` alias for `fiddle`.
Config
✓ from fiddle import Config
This quickstart demonstrates how to define configurations for Python callables using `fdl.Config` and `fdl.Partial`, and then build them using `fdl.build()`. `fdl.Config` directly builds the callable with the specified arguments, while `fdl.Partial` returns a `functools.partial` object that can be called later.
import fiddle as fdl
def create_greeting(prefix: str, name: str = "World", punctuation: str = "!"):
return f"{prefix} {name}{punctuation}"
# Create a Fiddle configuration for the function
cfg = fdl.Config(create_greeting, prefix="Hello", name="Fiddle")
# Build the configured function to get the result
result = fdl.build(cfg)
print(f"Original Fiddle build: {result}")
# Modify the configuration
cfg.punctuation = "!!"
result_modified = fdl.build(cfg)
print(f"Modified Fiddle build: {result_modified}")
# Demonstrate fdl.Partial, which returns a functools.partial object
partial_cfg = fdl.Partial(create_greeting, prefix="Hi")
partial_func = fdl.build(partial_cfg) # This returns a functools.partial object
result_partial = partial_func(name="Python") # Call the partial function
print(f"Partial Fiddle build: {result_partial}")
Debug
Known issues
breakingFiddle is currently in 'Development Status :: 3 - Alpha'. This means the API is not yet stable, and breaking changes may occur in future releases.fixBe prepared for API adjustments and refer to release notes when upgrading. Consider pinning minor versions in production environments.
affects: 0.x.x (especially pre-1.0.0)
gotchaUsing mutable default arguments (e.g., lists, dictionaries) in functions configured by Fiddle can lead to unexpected shared state across different configurations or calls. Python evaluates default arguments once when the function is defined.fixAlways use `None` as a default argument, and then initialize the mutable object inside the function if `None` is passed. Example: `def func(arg=None): arg = arg or []`.
affects: All Python versions, relevant for Fiddle configurations
gotcha`fdl.Config` and `fdl.Partial` behave differently when `fdl.build()` is called. `fdl.Config` directly invokes the callable and returns its result, while `fdl.Partial` returns a `functools.partial` object that needs to be called separately to get the final result.fixUnderstand the distinction: use `fdl.Config` when you want the immediate result of the callable's execution, and `fdl.Partial` when you want a configurable, pre-filled callable that can be invoked later with additional arguments.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'fiddle'
The `fiddle` library is not installed in the current Python environment or the import statement has a typo.
fixInstall the library using pip: `pip install fiddle`
TypeError: Configuration did not resolve to an fdl.Buildable. Got: <class 'list'>
A Fiddle configuration, often sourced from `fdl_flags` or a default string, was expected to be an `fdl.Buildable` object (like `fdl.Config` or `fdl.Partial`) but instead resulted in a standard Python list, preventing further Fiddle operations.
fixEnsure that the configuration value, particularly when using `fdl_flags.DEFINE_fiddle_config` with string defaults, is properly resolved into an `fdl.Buildable` instance. This may involve explicitly building the configuration if it's still a list of command strings.
AttributeError: 'list' object has no attribute '...'
This error often occurs when Fiddle's name resolution logic or `fdl.build()` attempts to access an attribute on what it expects to be an `fdl.Buildable` (e.g., a configured module or recipe) but is instead a Python list. This can happen when `default_module` is a list and Fiddle tries to interpret a string as an attribute of an item within that list.
fixReview how `default_module` is defined and how configurations are referenced. Ensure that Fiddle's parsing mechanisms correctly resolve names to `fdl.Buildable` objects or actual modules/callables, rather than leaving them as unresolved strings within a list that is then treated as a configuration object.
AttributeError: module 'fiddle.config' has no attribute '__qualname__'
This is an internal `AttributeError` within the `fiddle` library, specifically related to the `__qualname__` attribute in `fiddle.config.py`. While a fix for this specific issue has been implemented, it might be encountered with older versions of the library or in specific, complex scenarios related to how Python objects are qualified within Fiddle's configuration system.
fixEnsure you are using the latest version of the `fiddle` library by running `pip install --upgrade fiddle`. If the issue persists, simplify the configuration that triggers the error, or consult the `fiddle` documentation/issue tracker for similar cases.
TypeError: <callable_name>() got an unexpected keyword argument '...' OR TypeError: <callable_name>() missing 1 required positional argument: '...'
When using `fdl.Config` to configure a function or class, `fiddle` passes the configured arguments directly to the underlying callable. If the arguments provided to `fdl.Config` do not match the expected parameters of the callable (e.g., misspelled keyword arguments, missing required arguments, or incorrect number of positional arguments), Python will raise a standard `TypeError`.
fixCarefully check the `fdl.Config` definition against the signature of the target function or class (`<callable_name>`). Correct any misspelled parameter names, provide all required positional and keyword arguments, and ensure argument types are compatible if type hints are present.
Upgrade
Version history
0.3.0latest on PyPI · released Apr 9, 2024
Audit
Dependencies
absl-pyoptionalProvides command-line flag support when installed with the 'flags' extra.