Aliasing parameters

In CLIs, it is common for options to have an alias allowing for quicker short-hand usage.

For instance, an option named --verbose may be aliased as -v.

Instead of manually specifying an alias with click.option(), e.g.

import feud
from feud import click

@click.option("--verbose", "-v", help="Whether to print or not.", type=bool)
def my_command(*, verbose: bool = False):
    """A command that does some logging."""

feud.run(my_command)

You can use the alias() decorator to do this, which also means you do not have to manually provide help or type to click.option(), and can instead rely on type hints and docstrings.

import feud

@feud.alias(verbose="-v")
def my_command(*, verbose: bool = False):
    """A command that does some logging.

    Parameters
    ----------
    verbose:
        Whether to print or not.
    """

feud.run(my_command)

Note

In the case of boolean flags such as --verbose in this case, the --no-verbose option will also have a corresponding --no-v alias automatically defined.

---

API reference

feud.decorators.alias(**aliases)

Alias command options.

Decorates a function by attaching command option alias metadata, to be used at compile time to alias click.Option objects.

Aliases may only be defined for command-line options, not arguments.

Parameters:

**aliases (str | list[str]) – Mapping of option names to aliases. Option names must be keyword-only parameters in the decorated function signature.

Return type:

Function decorated with command option alias metadata.

Examples

Aliasing a single option.

>>> import feud
>>> @feud.alias(verbose="-v")
... def func(*, verbose: bool) -> bool:
...     return verbose
>>> feud.run(func, ["--verbose"], standalone_mode=False)
True
>>> feud.run(func, ["-v"], standalone_mode=False)
True
>>> feud.run(func, ["--no-verbose"], standalone_mode=False)
False
>>> feud.run(func, ["--no-v"], standalone_mode=False)
False

Aliasing a single option with multiple aliases.

>>> import feud
>>> @feud.alias(verbose=["-v", "-V"])
>>> def func(*, verbose: bool) -> bool:
...     return verbose
>>> feud.run(func, ["-v"], standalone_mode=False)
True
>>> feud.run(func, ["--no-v"], standalone_mode=False)
False
>>> feud.run(func, ["-V"], standalone_mode=False)
True
>>> feud.run(func, ["--no-V"], standalone_mode=False)
False

Aliasing multiple options.

>>> import feud
>>> from feud.typing import Counter
>>> @feud.alias(verbose="-v", stringify="-s")
... def func(*, verbose: Counter, stringify: bool) -> int | str:
...     return f"Verbose level: {verbose}" if stringify else verbose
>>> feud.run(func, ["-vvvs"], standalone_mode=False)
"Verbose level: 3"
>>> feud.run(func, ["-v", "-v", "-v", "-s"], standalone_mode=False)
"Verbose level: 3"
>>> feud.run(func, ["-vvv", "--no-s"], standalone_mode=False)
3