argh

library0.31.3pypypi✓ verified 23d ago

Argh is a lightweight Python library that simplifies the creation of command-line interfaces (CLIs) by building on top of the `argparse` module. It allows developers to define CLI commands using plain Python functions, reducing boilerplate code and inferring arguments from function signatures and type annotations. The library is actively maintained, with regular releases, and is currently at version 0.31.3.

devops

pip install argh

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · ARGH

argh

devopspythonv0.31.3

Install

1.6s avg

Import

65ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.31.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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.066s · 18MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.064s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

dispatch_command

✓ from argh import dispatch_command

Used for single-command CLI applications.

dispatch_commands

✓ from argh import dispatch_commands

Used for multi-command CLI applications.

arg

✓ from argh import arg

✗ from argh.decorators import arg

The `arg` decorator is directly available from the top-level `argh` package since v0.30.0 for cleaner imports, although older paths might still work for compatibility.

This quickstart demonstrates how to create a simple CLI application with a single command (`verify_paths`) that accepts a list of paths and an optional verbose flag. Argh automatically infers arguments and types from the function signature and annotations. Run the script with `python your_script.py path1.txt path2.csv --verbose`.

import argh import os def verify_paths(paths: list[str], *, verbose: bool = False): """Verify that all given paths exist.""" for path in paths: if verbose: print(f"Checking {path}...") if not os.path.exists(path): raise FileNotFoundError(f"Path does not exist: {path}") print("All paths verified successfully.") if __name__ == "__main__": # For a single command application, use dispatch_command. # For multiple commands, use argh.dispatch_commands([cmd1, cmd2]). # Note: old_name_mapping_policy=False is often recommended during the transition # for explicit argument mapping, especially with positional arguments having defaults. argh.dispatch_command(verify_paths, old_name_mapping_policy=False)

argh --version

Debug

Known issues

breakingArgh v0.31.0 automatically enables typing hints introspection for functions without `@arg` decorators. This may change behavior if you previously relied on no introspection for such functions, potentially leading to unexpected argument parsing.

fix

Explicitly use `@argh.arg` decorators for arguments where automatic type hint introspection is not desired, or adjust your function signatures to match the desired CLI behavior.

affects: >=0.31.0

breakingArgh v0.30.0 introduced a new default policy for mapping function arguments to CLI arguments. Positional arguments with default values now map to positional CLI arguments instead of optional flags (e.g., `def func(foo, bar=None)` maps `bar` as a positional `[bar]` instead of `--bar`).

fix

To retain the old behavior of mapping to an option, explicitly define the argument as keyword-only (e.g., `def func(foo, *, bar=None)`). For complex cases, explicitly specify `old_name_mapping_policy=True` in `dispatch_command` or `dispatch_commands` during the transition, though this will change in future versions.

affects: >=0.30.0

gotchaSince v0.30.2, Argh raises `ArgumentNameMappingError` if a non-keyword-only argument has a default value and no explicit name mapping policy is defined. This prevents silent misinterpretation of CLI arguments based on the new policy.

fix

Review affected function signatures and either make the argument keyword-only (e.g., `def func(foo, *, bar=None)`) or explicitly pass `old_name_mapping_policy=True` to `dispatch_command`/`dispatch_commands` if the legacy behavior is intended.

affects: >=0.30.2

deprecatedThe `@expects_obj` decorator and the `add_help_command` argument in `dispatch()` (which enabled the `help` positional command alias) were deprecated in v0.30.0 and subsequently removed in v0.31.0.

fix

Remove usages of `@expects_obj` and rely on standard function signatures or `@arg` decorators. For help, use the standard `--help` flag instead of `help` as a positional command.

affects: 0.30.0 - 0.30.x

gotchaEarlier versions (prior to v0.31.2) had broken support for type aliases like `typing.List` and `typing.Optional[List]`, leading to incorrect argument parsing for these types.

fix

Upgrade to Argh v0.31.2 or later to ensure correct parsing of `List` and `Optional[List]` type hints.

affects: <0.31.2

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'argh'

The 'argh' module is not installed in the current Python environment.

fix

pip install argh

ImportError: cannot import name 'alias' from 'argh'

The 'alias' function has been removed in recent versions of 'argh'.

fix

Use 'argh.decorators.alias' instead of 'argh.alias'.

ImportError: No module named 'context_locals'

The 'tool' package depends on 'context_locals', which is not installed or incompatible.

fix

Ensure 'context_locals' is installed and compatible with your Python version.

AttributeError: 'Namespace' object has no attribute 'command_name'

This error typically occurs when trying to access a sub-command's attribute on the parsed arguments (the `Namespace` object) before ensuring a sub-command was actually called, or if the `dest` parameter for `add_subparsers` was not set, leading to an unexpected attribute name for the chosen sub-command.

fix

Ensure that `argh.dispatch_commands` (or `parser.add_subparsers`) has a `dest` argument set to capture the sub-command's name, and then access the arguments from the correct attribute or check if the command exists. Example: `subparsers = parser.add_subparsers(dest='command')` and later `if args.command == 'my_command': ...`

error: the following arguments are required: sub_command

This error, originating from `argparse` (which `argh` uses), means a required sub-command was not provided on the command line, often because `subparsers.required = True` was explicitly set or implied in older `argparse` versions.

fix

Provide the required sub-command when executing the script, or, if the sub-command should be optional, ensure `subparsers.required = False` (which is the default in newer `argparse` versions) and handle the case where no sub-command is given. You might also need to explicitly set `dest` for subparsers.

Upgrade

Version history

0.31.3latest on PyPI · released Jul 13, 2024

Audit

Dependencies

pythonrequiredRequired Python version

argparserequiredBuilt-in standard library module that Argh wraps

argcompleteoptionalOptional dependency for shell tab-completion

Agent activity

24 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/neithere/argh ↗

packagehttps://pypi.org/project/argh/ ↗

docshttps://argh.readthedocs.io/en/latest ↗

changeloghttps://github.com/neithere/argh/releases ↗