Running commands/groups#

API reference#

feud.core.run(obj=None, /, args=None, *, name=None, help=None, epilog=None, config=None, rich_settings=None, warn=True, **click_kwargs)#

Run a function, click.Command, Group, or click.Group.

Multiple functions/commands can also be provided as a dict, iterable or module object. dict objects may also be nested.

If called on a function, it will be automatically decorated with command() using the default configuration to convert it into a click.Command which will then be executed.

If no runnable object is provided, automatic discovery will be done on the current module.

Warning

name, help, epilog and config are ignored if a click.Command, click.Group or Group is provided.

Parameters:

  • obj (Command | type[Group] | Callable | module | Iterable | dict | None) – Runnable group, command or function to run, or dict, iterable or module of runnable objects.

  • args (list[str] | None) – Command-line arguments provided to click.Command.

  • name (str | None) – CLI command or group name.

  • help (str | None) – CLI command or group description, displayed when --help is called. If not set, the docstring of the object will be used if available.

  • epilog (str | None) – CLI command or group epilog. Appears at the bottom of --help.

  • config (Config | None) –

    Configuration for the command or group.

    If a dict, iterable or module obj is provided, the configuration will be forwarded to the nested runnable objects within.

  • rich_settings (dict[str, Any] | None) –

    Styling options for rich-click, e.g. {"SHOW_ARGUMENTS": False, "MAX_WIDTH": 60}.

    See all available options here (as of rich-click v1.7.2).

  • warn (bool) – Silences warnings that are produced if name, help, epilog or config are provided when obj is a click.Command, click.Group or Group.

  • **click_kwargs (Any) – Additional keyword arguments provided to click.Command.

Return type:

Output of the called object.

Raises:

feud.exceptions.CompilationError – If no runnable object or current module can be determined.

Examples

Running an undecorated function.

>>> import feud
>>> def func(*, opt: int) -> int:
...     return opt
>>> feud.run(func, ["--opt", "3"], standalone_mode=False)
3

Running a click.Command.

>>> import feud
>>> @feud.command
... def func(*, opt: int) -> int:
...     return opt
>>> feud.run(func, ["--opt", "3"], standalone_mode=False)
3

Running a Group.

>>> import feud
>>> class CLI(feud.Group):
...     def func(*, opt: int) -> int:
...         return opt
>>> feud.run(CLI, ["func", "--opt", "3"], standalone_mode=False)
3

Running a click.Group.

>>> import feud
>>> from feud import click
>>> class CLI(feud.Group):
...     def func(*, opt: int) -> int:
...         return opt
>>> group: click.Group = feud.compile(CLI)
>>> feud.run(group, ["func", "--opt", "3"], standalone_mode=False)
3

Running a dict of functions, commands, groups or modules.

>>> import feud
>>> def func1(*, opt: int) -> int:
...     return opt
>>> def func2(*, opt: float) -> float:
...     return opt
>>> feud.run(
...     {"f": func1, "g": func2},
...     ["g", "--opt", "0.12"],
...     standalone_mode=False,
... )
0.12

Running an iterable of functions, commands, groups or modules.

>>> import feud
>>> def func1(*, opt: int) -> int:
...     return opt
>>> def func2(*, opt: float) -> float:
...     return opt
>>> feud.run(
...     (func1, func2),
...     ["func2", "--opt", "0.12"],
...     standalone_mode=False,
... )
0.12

Running a module of functions, commands or groups.

>>> import feud
>>> import types
>>> feud.run(types)

Running with automatic discovery

>>> import feud
>>> def func1(*, opt: int) -> int:
...     return opt
>>> feud.run()