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 registering 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 a Config), group-level configuration can be specified when subclassing Group.

>>> 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 to click.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:

add_commands()
commands()
compile()
deregister()
descendants()
name()
register()
subgroups()

See rename() if you wish to define a command with one of the above names.

Methods

`add_commands`([commands])	Add a command to the group.
`commands`(*[, name])	Commands defined in the group.
`compile`()	Compile the group into a `click.Group`.
`deregister`([sub])	Deregister one or more subgroups.
`descendants`()	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:

cls (type[Group]) – Group class reference.
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:

Any

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.

Returns:: Command sections.
Return type:: list[Section]

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 add_commands(commands=None, /, **kwargs)#

Add a command to the group.

Provided commands may be functions or click.Command objects (which may be generated using command()).

If a function is provided, it will be converted into a click.Command using the group’s Config.

Parameters:

commands (list[Callable | Command] | None) –
Commands to add to the group.

Commands will keep their original name, but will be assigned as a member to the group class using the name of the original function (if decorated by command()).
**kwargs (Callable | Command) –
Command to add to the group.

Commands will be renamed according to the specified keys, but will be assigned as a member to the group class using the name of the original function (if decorated by command()).

Return type:

None

Examples

Registering a function and a click.Command.

>>> import feud
>>> class CLI(feud.Group):
...     pass
>>> def func(arg: int) -> int:
...     return arg
>>> @feud.command
... def command(arg: int) -> int:
...     return arg
>>> CLI.add_commands([func, command])
>>> CLI.commands(name=True)
['func', 'command']

Registering a function and a click.Command (with renaming).

>>> import feud
>>> class CLI(feud.Group):
...     pass
>>> def func(arg: int) -> int:
...     return arg
>>> @feud.command
... def command(arg: int) -> int:
...     return arg
>>> CLI.add_commands(renamed1=func, renamed2=command)
>>> CLI.commands(name=True)
['renamed1', 'renamed2']

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:: click.Group

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:: str

Examples

>>> import feud
>>> class A(feud.Group):
...     pass
>>> A.name()
'a'

classmethod register(sub, /)#

Parameters:: sub (type[Group] | list[type[Group]]) – The subgroup(s) to register.
Return type:: None

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:: list[type[Group]] | list[str]

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.

field items: list[str] = []#

Names of commands or subgroups to include in the section.

If rename() was used to rename a command, the new command name should be used.

field name: str [Required]#: Name of the command section.