Running and building CLIs#

API reference#

Core utilities for building and running a command-line interface.

feud.core.build(obj=None, /, *, name=None, help=None, epilog=None, config=None, warn=True, compile=True)#

Build a click.Command or click.Group from a runnable object.

See run() for details on runnable objects.

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.

  • 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.

  • 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.

  • compile (bool) – Whether or not to compile Group objects into click.Group objects.

Returns:

The runnable object.

Return type:

click.Command | click.Group | Group

Raises:

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

Examples

>>> import feud
>>> from feud import click
>>> def func1(*, opt: int) -> int:
...     return opt
>>> def func2(*, opt: float) -> float:
...     return opt
>>> group: click.Group = feud.build([func1, func2])
>>> isinstance(group, click.Group)
True
feud.core.run(obj=None, /, args=None, *, name=None, help=None, epilog=None, config=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.

  • 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.

Returns:

Output of the called object.

Return type:

Any

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 = CLI.compile()
>>> 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()