Groups#
Groups are a component of CLIs that allow you to group together related Commands.
In addition to commands, groups may also contain further nested groups by register
ing subgroups,
allowing for the construction of complex CLIs with many levels.
Groups and their subgroups or commands can be executed using run()
.
See also
The Click API documentation does a great job at clarifying the following command-line terminology:
API reference#
- class feud.core.group.Group#
Representation of a command group, compiling into a
click.Group
.Functions defined in the class body represent commands within the group and are automatically decorated with
command()
(if not already decorated and do not begin with an underscore).Groups may be registered as subgroups to another parent group.
Similarly to providing configuration keyword arguments to
command()
(directly or with aConfig
), group-level configuration can be specified when subclassingGroup
.>>> import feud >>> class CLI(feud.Group, show_help_defaults=False, name="my-cli"): ... def func(*, opt: int): ... pass
Note that Click-level keyword arguments such as
name
, which are not Feud configuration parameters, are passed toclick.group()
.Feud configuration parameters defined on a group are automatically forwarded to the commands within the group, provided that the function in the class body is not manually decorated with
command()
. In the above example,func
is automatically wrapped with@feud.command(show_help_defaults=False)
.Caution
The following function names should NOT be used in a group:
See
rename()
if you wish to define a command with one of the above names.Methods
commands
(*[, name])Commands defined in the group.
compile
()Compile the group into a
click.Group
.deregister
([sub])Deregister one or more subgroups.
Directed acyclic graph of subgroup descendants.
name
()Return the name of the group.
register
(sub, /)Register one or more subgroups.
subgroups
(*[, name])Registered subgroups.
- static __new__(cls, args=None, /, **kwargs)#
Compile and run the group.
Warning
This function should be considered internal. The preferred way to run a group is to use the
run()
function.- Parameters:
args (list[str] | None) – Command-line arguments provided to
click.Command
.**kwargs (Any) – Additional keyword arguments provided to
click.Command
.
- Returns:
Output of the called
click.Command
.- Return type:
Examples
>>> import feud >>> class CLI(feud.Group): ... def func(*, opt: int) -> int: ... return opt >>> CLI(["func", "--opt", "3"], standalone_mode=False) 3
See also
run
Run a command or group.
- classmethod __sections__()#
Sections to partition commands and subgroups into.
These sections are displayed on the group help page if
rich-click
is installed.Examples
>>> import feud >>> class Test(feud.Group): ... def one(): ... pass ... def two(): ... pass ... def three(): ... pass ... def __sections__() -> list[feud.Section]: ... return [ ... feud.Section( ... name="Odd commands", items=["one", "three"] ... ), ... feud.Section(name="Even commands", items=["two"]), ... feud.Section(name="Groups", items=["subgroup"]), ... ] >>> class Subgroup(feud.Group): ... pass >>> Test.register(Subgroup)
- classmethod commands(*, name=False)#
Commands defined in the group.
- Parameters:
name (bool) – Whether or not to return the command names.
- Returns:
Group commands.
- Return type:
list[click.Command] | list[str]
Examples
>>> import feud >>> class Test(feud.Group): ... def func_a(): ... pass ... def func_b(): ... pass >>> Test.commands() [<Command func_a>, <Command func_b>]
- classmethod compile()#
Compile the group into a
click.Group
.- Returns:
The generated group.
- Return type:
Examples
>>> import feud, click >>> class CLI(feud.Group): ... def func(*, opt: int) -> int: ... return opt >>> isinstance(CLI.compile(), click.Group) True
- classmethod deregister(sub=None, /)#
Deregister one or more subgroups.
- Parameters:
sub (type[Group] | list[type[Group]] | None) – The subgroup(s) to register.
- Return type:
None
Examples
Deregistering a single subgroup.
>>> import feud >>> class A(feud.Group): ... pass >>> class B(feud.Group): ... pass >>> A.register(B) >>> A.subgroups() [<class 'group.B'>] >>> A.deregister(B) >>> A.subgroups() []
Deregistering multiple subgroups.
>>> import feud >>> class A(feud.Group): ... pass >>> class B(feud.Group): ... pass >>> class C(feud.Group): ... pass >>> A.register([B, C]) >>> A.subgroups() [<class 'group.B'>, <class 'group.C'>] >>> A.deregister([B, C]) >>> A.subgroups() []
See also
register
Register one or more subgroups.
- classmethod descendants()#
Directed acyclic graph of subgroup descendants.
- Returns:
Subgroup descendants.
- Return type:
collections.OrderedDict[type[Group], collections.OrderedDict]
Examples
>>> import feud >>> class A(feud.Group): ... pass >>> class B(feud.Group): ... pass >>> class C(feud.Group): ... pass >>> A.register(B) >>> B.register(C) >>> A.descendants() OrderedDict([ ( <class 'group.B'>, OrderedDict([ ( <class 'group.C'>, OrderedDict() ) ]) ) ])
See also
subgroups
Registered subgroups.
- classmethod name()#
Return the name of the group.
- Returns:
The group name.
- Return type:
Examples
>>> import feud >>> class A(feud.Group): ... pass >>> A.name() 'a'
- classmethod register(sub, /)#
Register one or more subgroups.
Examples
Registering a single subgroup.
>>> import feud >>> class A(feud.Group): ... pass >>> class B(feud.Group): ... pass >>> A.register(B) >>> A.subgroups() [<class 'group.B'>]
Registering multiple subgroups.
>>> import feud >>> class A(feud.Group): ... pass >>> class B(feud.Group): ... pass >>> class C(feud.Group): ... pass >>> A.register([B, C]) >>> A.subgroups() [<class 'group.B'>, <class 'group.C'>]
See also
deregister
Deregister one or more subgroups.
- classmethod subgroups(*, name=False)#
Registered subgroups.
- Parameters:
name (bool) – Whether or not to return the subgroup names.
- Returns:
Registered subgroups.
- Return type:
Examples
>>> import feud >>> class A(feud.Group): ... pass >>> class B(feud.Group): ... pass >>> class C(feud.Group): ... pass >>> A.register([B, C]) >>> A.subgroups() [<class 'group.B'>, <class 'group.C'>]
See also
descendants
Directed acyclic graph of subgroup descendants.
- pydantic model feud.Section#
Commands or subgroups to display in a separate section on the help page of a
Group
.- Fields:
description (str | None)
items (list[str])
name (str)
- field description: str | None = None#
Description of the command section.
Deprecated since version 0.3.0: Not yet supported by
rich-click
.