ArgBind

Common errors

• ModuleNotFoundError: No module named 'argbind'

  cause The 'argbind' library has not been installed in your Python environment.
  fix Run `pip install argbind` in your terminal to install the library.

• TypeError: func() got multiple values for keyword argument 'arg'

  cause This typically occurs when an argument is provided through multiple mechanisms (e.g., command line, YAML file, and direct function call) and their priority is not correctly understood, or a default value is conflicting.
  fix Understand ArgBind's argument priority: explicit Python code arguments > command-line arguments > YAML file arguments > default keyword arguments. Check your calls and configurations for conflicts and remove redundant argument specifications.

• The boolean flag I'm passing on the command line isn't changing the value set in my YAML config.

  cause ArgBind has a known behavior where a boolean argument set to `True` in a YAML file cannot be overridden back to `False` using command-line arguments in certain scenarios.
  fix Redefine the problematic boolean argument as an integer (`int`) in your function signature, using `0` for `False` and `1` for `True`. Then, specify the value on the command line as `--func.arg 0` or `--func.arg 1`.

Warnings

• gotcha Boolean arguments overridden from a YAML file cannot be easily unset (flipped to `False`) from the command line. If a boolean is `True` in YAML, passing `--func.arg False` may not work as expected.
  Fix: For arguments that need to be dynamically flippable between `True` and `False` from both YAML and CLI, define them as `int` (0 or 1) instead of `bool`. For example, use `--func.arg 0` or `--func.arg 1` on the command line.
• gotcha Positional arguments specified in a `.yml` configuration file will override any positional arguments provided directly on the command line. This can lead to unexpected behavior if a user expects CLI arguments to always take precedence for positional parameters.
  Fix: Avoid saving positional arguments within `.yml` files. Instead, use `.yml` files exclusively for keyword arguments, and pass positional arguments directly via the command line when running the script.
• gotcha Bound function names must be unique across your entire application. ArgBind resolves function arguments by their immediate function name, not their fully qualified path or module.
  Fix: Ensure that any function decorated with `@argbind.bind()` has a unique name. If you have similarly named functions in different modules, consider refactoring or using distinct aliases if ArgBind supported them (which it does not explicitly mention).

Install

• pip install argbind Install latest version

Imports

• argbind

  import argbind

• bind

  from argbind import bind
  # or use as decorator: @argbind.bind()

• parse_args

  from argbind import parse_args
  # or: args = argbind.parse_args()

• scope

  from argbind import scope
  # or: with argbind.scope(args):

• load_args

  from argbind import load_args
  # or: args = argbind.load_args('config.yaml')

Quickstart

This quickstart demonstrates how to define a function with `argbind.bind()`, parse arguments (either defaults, command-line, or from a YAML file), and execute the bound function within an `argbind.scope` context. Arguments are prefixed with the function name (e.g., `--greet.name`).

import argbind

@argbind.bind()
def greet(name: str = 'World', excited: bool = False):
    """Greets the given name, optionally with excitement."""
    message = f"Hello, {name}"
    if excited:
        message += "!"
    print(message)

if __name__ == '__main__':
    # In a real CLI, this would parse sys.argv
    # For quickstart, simulate args or load from file
    
    # Example 1: Default execution
    print('--- Running with defaults ---')
    args_default = argbind.parse_args([]) # No CLI args provided
    with argbind.scope(args_default):
        greet()

    # Example 2: Override from simulated CLI args
    print('\n--- Running with CLI override ---')
    # Simulate `python your_script.py --greet.name Alice --greet.excited True`
    args_cli = argbind.parse_args(['--greet.name', 'Alice', '--greet.excited', 'True'])
    with argbind.scope(args_cli):
        greet()

    # Example 3: Load from a YAML file
    print('\n--- Running from YAML file ---')
    config_content = """
greet.name: Bob
greet.excited: False
"""
    with open('config.yaml', 'w') as f:
        f.write(config_content)

    args_yaml = argbind.load_args('config.yaml')
    with argbind.scope(args_yaml):
        greet()

    # Clean up (optional for quickstart, but good practice)
    import os
    os.remove('config.yaml')