Commands#

Commands are the core component of a CLI, running a user-defined function that may be parameterized with arguments or options.

Commands may be included within Groups, which usually contain a set of related commands.

Commands may be executed using run().

Understanding function signatures#

To understand how Feud converts a function into a click.Command, consider the following function.

# func.py

import feud

def func(arg1: int, arg2: str, *, opt1: float, opt2: int = 0):
    ...

if __name__ == "__main__":
    feud.run(func)

This function signature consists of:

two positional parameters arg1 and arg2,
two keyword-only parameters opt1 and opt2.

Note

The * operator in Python is used to indicate where positional parameters end and keyword-only parameters begin.

When calling func in Python:

values for the positional parameters can be provided without specifying the parameter name,
values for the keyword-only parameters must be provided by specifying the parameter name.

func(1, "hello", opt1=2.0, opt2=3)

where arg1 takes the value 1, and arg2 takes the value "hello".

Similarly, when building a click.Command, Feud treats:

positional parameters as arguments (specified without providing a parameter name),
keyword-only parameters as options (specified by providing a parameter name).

$ python func.py 1 hello --opt1 2.0 --opt2 3

Note that --opt1 is a required option as it has no default specified, whereas --opt2 is not required.

API reference#

feud.core.command(func=None, /, *, negate_flags=None, show_help_defaults=None, show_help_datetime_formats=None, show_help_envvars=None, pydantic_kwargs=None, rich_click_kwargs=None, config=None, **click_kwargs)#

Decorate a function and convert it into a click.Command with automatically defined arguments, options and help documentation.

Parameters:

func (Callable | None) – Function used to generate a command.
negate_flags (bool | None) – Whether to automatically add a negated variant for boolean flags.
show_help_defaults (bool | None) – Whether to display default parameter values in command help.
show_help_datetime_formats (bool | None) – Whether to display datetime parameter formats in command help.
show_help_envvars (bool | None) – Whether to display environment variable names in command help.
pydantic_kwargs (dict[str, Any] | None) – Validation settings for pydantic.validate_call_decorator.validate_call().
rich_click_kwargs (dict[str, Any] | None) –
Styling settings for rich-click.

See all available options here (as of rich-click v1.7.2).
config (Config | None) –
Configuration for the command.

This argument may be used either in place or in conjunction with the other arguments in this function. If a value is provided as both an argument to this function, as well as in the provided config, the function argument value will take precedence.
**click_kwargs (Any) – Keyword arguments to forward click.command().

Returns:

The generated command.

Return type:

click.Command

Examples

>>> import feud
>>> @feud.command(name="my-command", negate_flags=False)
... def f(arg: int, *, opt: int) -> tuple[int, int]:
...     return arg, opt
>>> feud.run(f, ["3", "--opt", "-1"], standalone_mode=False)
(3, -1)