Running and building CLIs#
run()
: Build and run runnable objects as aclick.Command
orclick.Group
.build()
: Build runnable object(s) into aclick.Command
,click.Group
(orGroup
).
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
orclick.Group
from a runnable object.See
run()
for details on runnable objects.Warning
name
,help
,epilog
andconfig
are ignored if aclick.Command
,click.Group
orGroup
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 moduleobj
is provided, the configuration will be forwarded to the nested runnable objects within.warn (bool) – Silences warnings that are produced if
name
,help
,epilog
orconfig
are provided whenobj
is aclick.Command
,click.Group
orGroup
.compile (bool) – Whether or not to compile
Group
objects intoclick.Group
objects.
- Returns:
The runnable object.
- Return type:
- 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
, orclick.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 aclick.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
andconfig
are ignored if aclick.Command
,click.Group
orGroup
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 moduleobj
is provided, the configuration will be forwarded to the nested runnable objects within.warn (bool) – Silences warnings that are produced if
name
,help
,epilog
orconfig
are provided whenobj
is aclick.Command
,click.Group
orGroup
.**click_kwargs (Any) – Additional keyword arguments provided to
click.Command
.
- Returns:
Output of the called object.
- Return type:
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()