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

Warning

The following function names should NOT be used in a group:

deregister()
descendants()
register()
subgroups()

Methods

`deregister`([sub])	Deregister one or more subgroups.
`descendants`()	Directed acyclic graph of subgroup descendants.
`register`(sub, /)	Register one or more subgroups.
`subgroups`()	Registered subgroups.

static __new__(cls, args=None, /, **kwargs)#

Compile and run the group.

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.

Return type:

Output of the called click.Command.

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

Return type:: Subgroup descendants.

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 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()#

Registered subgroups.

Return type:: Registered subgroups.

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.

feud.core.group.compile(group, /)#

Compile a Group into a click.Group.

Parameters:: group (type[Group]) – Group to compile into a click.Group.
Return type:: The generated click.Group.

Examples

>>> import feud
>>> class CLI(feud.Group):
...     def func(*, opt: int) -> int:
...         return opt
>>> isinstance(feud.compile(CLI), click.Group)
True